Classes
struct	AccountEquityPoint
	One timestamped point on an account-level equity curve. More...

struct	Allocation
	Requested capital allocation to one strategy and market sleeve. More...

struct	BacktestConfiguration
	Immutable engine settings applied to every execution owned by a TrialExecutor. More...

class	BooleanDimension
	Named dimension whose legal values are exactly `false` and `true`. More...

struct	Candidate
	Complete parameter assignment proposed by a sampler. More...

class	CategoricalDimension
	Named dimension backed by an ordered, non-empty set of scalar choices. More...

struct	Constraint
	Named scalar feasibility constraint with an absolute non-negative tolerance. More...

class	Dataset
	Immutable owned or file-mapped OHLCV input shared by independent trial executions. More...

struct	DatasetView
	Immutable, non-copying range of bars retaining its Dataset owner. More...

class	DlibGlobalSampler
	Adaptive derivative-free optimizer backed by `dlib::global_function_search`. More...

class	EngineError
	An engine-owned failure whose optional metadata is forwarded without reclassification. More...

struct	EngineVersion
	Embedded runtime identity admitted for selected-window execution. More...

struct	EquityPointsView
	Borrowed, strided view of an ordered array of records holding `(time_ms, equity)`. More...

class	ErrorArgument
	A typed JSON scalar; strings in HPO-owned arguments use closed catalog vocabularies. More...

struct	EvaluationPolicy
	Policies controlling exceptional arithmetic during metric-expression evaluation. More...

class	ExpressionError
	Parse error raised while compiling a metric expression. More...

struct	ExpressionEvaluation
	Non-throwing result envelope returned by MetricExpression::evaluate(). More...

class	GridSampler
	Lazy exhaustive sampler over a finite SearchSpace in mixed-radix order. More...

class	HpoError
	Stable machine-readable failure metadata shared by the standard exception families. More...

class	IntegerDimension
	Named signed-integer dimension with inclusive bounds and a positive step. More...

class	MetricExpression
	Parsed metric expression that is compiled once and evaluated repeatedly. More...

struct	ObjectiveResult
	Objective values, constraints, and diagnostics produced for one observation. More...

struct	PlanRequest
	Owned request strings and fixed-width fields for the selected primary C planner. More...

struct	PlanResult
	Value copy of the complete 248-byte engine result, including planner refusals. More...

struct	PortfolioObservation
	Account-level observation supplied to a custom portfolio objective. More...

class	Pruner
	Coordinator-owned rung history. More...

class	RandomSampler
	Seeded independent sampler with replacement. More...

class	RealDimension
	Named binary64 dimension with inclusive bounds and an optional finite-grid step. More...

struct	ReportSnapshot
	Owning report snapshot detached from strategy and C-ABI report lifetimes. More...

struct	ReturnBlockLayout
	Block layout of one bar-return series: how many intervals each block holds and which curve point opens it. More...

struct	ReturnBlockMoments
	Moments of every block of one bar-return series, ascending block. More...

struct	ReturnSeriesStats
	All published fields of one series plus diagnostics. More...

struct	ReturnStatsFields
	Published fields of one return-statistics series, in wire order: count, skipped, periods_per_year, mean, std, sharpe_per_period, skew, kurt_raw, status. More...

struct	ReturnStatsMetric
	One of the eighteen metric names, decomposed. More...

struct	ReturnStatsRequest
	Selects the series to compute. A series that is not requested costs nothing. More...

struct	ReturnStatsResult
	The series that were requested; an absent series was not requested. More...

class	Sampler
	Minimal pull-based interface shared by candidate samplers. More...

class	SearchSpace
	Ordered product of named dimensions with validation and finite-space codecs. More...

class	SelectedEvaluation
	Dedicated one-shot OOS execution on a fresh handle using full report mode. More...

struct	SelectedEvaluationResult
	One fully checked selected run, detached from the engine handle and report. More...

struct	SelectedExpectedCounts
	Already-planned retained primary counts; no planning is performed by SelectedEvaluation. More...

struct	SelectedPlan
	One selected-window prediction and the immutable rows to supply to SelectedEvaluation. More...

struct	SleeveSummary
	Compact start/end summary for one independently evaluated portfolio sleeve. More...

class	StrategyPlugin
	RAII wrapper around one compiled PineForge strategy plugin. More...

struct	SymbolData
	Fixed other-symbol data installed into every fresh trial strategy. More...

struct	SymbolFact
	One catalog fact installed through strategy_set_symbol_facts. More...

struct	SymbolFeed
	Owned, immutable-after-loading bars for one exact request timeframe. More...

struct	SymbolInfo
	Optional instrument metadata applied after trial inputs and runtime overrides. More...

class	TpeSampler
	Independent, single-objective Tree-structured Parzen Estimator sampler. More...

struct	TpeSamplerConfig
	Tuning parameters for the native product-density TPE implementation. More...

struct	TrialContext
	Metadata supplied to a custom objective while evaluating one trial. More...

struct	TrialExecutionResult
	Result envelope returned by TrialExecutor::execute(). More...

class	TrialExecutor
	Deterministic one-shot adapter from serialized parameters to a detached report. More...

class	TypedHpoError
	Adds stable metadata while preserving a standard exception's catch compatibility. More...

struct	ValidationIssue
	One candidate-validation failure tied to a parameter name. More...

struct	WarmStartObservation
	One previously attempted candidate; only finite, feasible completed objectives are supplied. More...

class	WarmStartSource
	Immutable, ordered sampler observations, optionally backed by mapped binary columns. More...

class	WindowPlanHelper
	Owns a verified, privately snapshotted standalone planner library. More...

Typedefs
using	ErrorArguments = std::map< std::string, ErrorArgument >
	Deterministically ordered failure arguments. No strategy-computed value belongs here.

using	MetricMap = std::unordered_map< std::string, double >
	Metric values keyed by canonical objective path.

template<typename Observation >
using	ObjectiveFn = std::function< ObjectiveResult(const Observation &, const TrialContext &)>
	Type-erased custom objective accepting an observation and immutable trial context.

using	PortfolioObjectiveFn = ObjectiveFn< PortfolioObservation >
	Custom objective function specialized for PortfolioObservation.

using	Dimension = std::variant< IntegerDimension, RealDimension, BooleanDimension, CategoricalDimension >
	Closed variant over every supported search-space dimension type.

using	SymbolFeeds = std::vector< SymbolData >
	Study-owned collection shared read-only by all trial workers.

using	ParameterValues = std::map< std::string, std::string >
	Serialized Pine input or runtime-override values keyed by strategy parameter name.

using	ParameterValue = std::variant< std::int64_t, double, bool, std::string >
	Scalar parameter value accepted by search spaces and the PineForge strategy ABI.

Enumerations
enum class	BinaryVerification { Full , Sidecar }
	Verification of a binary chart's sidecar and mapped bytes. More...

enum class	FailureOrigin : std::uint8_t { Hpo , Engine }
	Provenance of a failure, independent of its human-readable diagnostic. More...

enum class	DivisionByZeroPolicy { Reject , Ieee754 }
	Behavior when an objective expression divides by zero. More...

enum class	NonFinitePolicy { Reject , Allow }
	Behavior when a metric or expression result is not finite. More...

enum class	EvaluationError { None , MissingMetric , NonFiniteMetric , DivisionByZero , NonFiniteResult }
	Stable reason code for an invalid ExpressionEvaluation. More...

enum class	ConstraintRelation { LessEqual , GreaterEqual , Equal }
	Comparison relation applied by Constraint. More...

enum class	PrunerKind { None , Median , Halving }
	Prefix pruning policy; disabled by default in the native runner. More...

enum class	ReturnSeries : std::uint8_t { Bar , Monthly }
	Return frequency of one statistics series. More...

enum class	ReturnStatistic : std::uint8_t { Count , Skipped , PeriodsPerYear , Mean , Std , SharpePerPeriod , Skew , KurtRaw , Status }
	One published field of a series. Declaration order is the wire order of the metric names. More...

enum class	ReturnStatsStatus : std::uint8_t { Ok = 0 , InsufficientCount = 1 , ZeroVariance = 2 , NonfiniteInput = 4 , PeriodUnavailable = 6 , UnsupportedTimezone = 7 , DerivedNonfinite = 8 }
	Stable numeric status of one series. More...

enum class	ReturnPeriodFailure : std::uint8_t { None , TooFewPoints , NonPositiveSpan , SpanOverflow , UtcRange }
	Why the period or time basis of a series is unavailable. Diagnostic only; not on the wire. More...

enum class	ReturnBlocksStatus : std::uint8_t { NotRequested = 0 , Ok = 1 , NonPositiveEquity = 2 , Nonfinite = 3 , UnusableCurve = 4 , UnusableLayout = 5 }
	Status of one row's block moments. More...

enum class	ObjectiveDirection { Maximize , Minimize }
	Direction used to rank a scalar objective. More...

enum class	CandidatePolicy { SamplerDefault , WithoutReplacement , Exhaustive }
	Uniqueness and coverage contract applied to sampler proposals. More...

enum class	DimensionKind { Integer , Real , Boolean , Categorical }
	Concrete dimension category stored by Dimension. More...

enum class	TrialExecutionStatus : std::uint8_t { kSucceeded = 0 , kEngineError = 1 }
	Terminal status of one native strategy execution. More...

enum class	ParameterType { Integer , Real , Boolean , String }
	Runtime discriminator for a ParameterValue alternative. More...

enum class	PlanStatus : std::int32_t { Ok = 0 , RequestInvalid = 1 , CalendarUnsupported = 2 , BoundaryUnaligned = 3 , FeedRangeInvalid = 4 , RowsUnordered = 5 , InternalError = 6 }
	Planner status words, independent of the C bridge's negative call return codes. More...

Functions
template<typename Record >
EquityPointsView	make_equity_points_view (const Record records, std::size_t count, std::int64_t Record::time_ms, double Record::*equity) noexcept
	Builds an EquityPointsView over `count` records of type `Record` from pointers to its `time_ms` and `equity` members, for example `&pf_equity_point_t::time_ms`.

ReturnStatsResult	compute_return_stats (const EquityPointsView &points, const ReturnStatsRequest &request) noexcept
	Computes the requested return statistics from a borrowed equity curve.

bool	is_utc_chart_timezone (std::string_view chart_timezone) noexcept
	True for the chart timezone names that select UTC bucketing: empty, `UTC` and `Etc/UTC`.

std::string_view	return_stats_metric_name (ReturnSeries series, ReturnStatistic statistic) noexcept
	Returns the wire metric name, for example `returns.bar.sharpe_per_period`.

std::optional< ReturnStatsMetric >	parse_return_stats_metric (std::string_view name) noexcept
	Resolves a metric name; returns an empty value for every name outside the eighteen.

bool	return_stats_contraction_free () noexcept
	Sanity probe of this translation unit's build: true when a multiply followed by an add is evaluated as two rounded operations (no contraction) and explicit fma is fused.

std::string_view	return_blocks_status_text (ReturnBlocksStatus status) noexcept
	Returns the wire text of a status: `ok`, `non_positive_equity`, `non_finite`, and empty for the statuses that are never published as a payload status.

ReturnBlockLayout	compute_block_layout (const EquityPointsView &points, std::uint32_t blocks)
	Cuts the adjacent intervals of a curve into `blocks` (S) blocks, and reads the opening timestamp of every one of them from the borrowed curve.

ReturnBlockMoments	reduce_return_blocks (const EquityPointsView &points, const ReturnBlockLayout &layout)
	Reduces the bar returns of a curve into the blocks of its own layout.

constexpr bool	return_stats_identity_bound () noexcept
	True when this build's return-statistics identity is bound to the compile commands that the build system generated for the reducer translation units.

constexpr std::string_view	return_stats_identity_unbound_reason () noexcept
	Short code naming why the identity is unbound; empty when it is bound.

constexpr std::string_view	return_stats_contract () noexcept
	Contract string that was bound into this build's identity at configure time.

constexpr std::string_view	return_stats_numeric_build_identity () noexcept
	Opaque identity of the build that computes return statistics; empty when unbound.

constexpr std::string_view	return_stats_identity_descriptor () noexcept
	Exact descriptor text that the identity is the SHA-256 digest of.

constexpr std::string_view	return_stats_source_digest () noexcept
	SHA-256 digest, in lower-case hexadecimal, of the sorted reducer source and header entries; empty when unbound.

const char *	candidate_policy_name (CandidatePolicy policy) noexcept
	Returns the stable StudySpec spelling of `policy`.

std::uint64_t	continuation_seed (std::uint64_t seed, std::uint64_t warm_trials) noexcept
	Derives a portable continuation RNG seed; an empty history preserves the original seed.

DimensionKind	dimension_kind (const Dimension &dimension) noexcept
	Returns the concrete category stored in `dimension`.

std::string_view	dimension_name (const Dimension &dimension) noexcept
	Returns the name of the concrete `dimension`.

bool	dimension_contains (const Dimension &dimension, const ParameterValue &value) noexcept
	Dispatches a type-aware membership test to the concrete `dimension`.

SelectedPlan	plan_selected_window (const WindowPlanHelper &helper, const DatasetView &tape, const PlanRequest &request)
	Plans one window over a shared tape or prefix without copying or repacking any bars.

bool	sobol_numeric_identity_bound ()
	True when this build's Sobol numeric identity is bound to the compile commands that the build system generated for the Sobol sources and the portable-math target.

std::string_view	sobol_numeric_identity_unbound_reason ()
	Short code naming why the identity is unbound; empty when it is bound.

std::string	sobol_numeric_build_identity ()
	Numeric build identity of the floating-point Sobol mapper, starting with `portable-sobol-v1`.

std::string_view	sobol_numeric_identity_descriptor ()
	Exact descriptor text whose SHA-256 digest is the `build_sha256` field of the identity.

EngineVersion	validate_selected_engine_version (const std::optional< pf_version_t > &numbers, const std::optional< std::string > &full, const std::optional< std::string > &expected_manifest_version=std::nullopt)
	Parses and cross-checks embedded metadata without loading a plugin or consulting build headers.

void	require_return_stats_identity ()
	Refuses return statistics in a build whose identity is unbound.

ParameterType	parameter_type (const ParameterValue &value) noexcept
	Returns the discriminator of `value`.

const char *	parameter_type_name (ParameterType type) noexcept
	Returns a stable lowercase name for `type`.

std::string	serialize_parameter_value (const ParameterValue &value)
	Produces the exact text passed to `strategy_set_input` or `strategy_set_override`.

Variables
constexpr std::string_view	kReturnStatsContract = "pineforge-hpo-return-stats/v1"
	Contract string of the result-level `return_stats` object (legacy mode, version 1).

constexpr std::string_view	kReturnBlocksContract = "pineforge-hpo-return-blocks/v1"
	Contract string of the per-row `block_returns` object and of the result-level `return_blocks` object that declares the layout its rows were reduced under (version 1, bar series).

constexpr double	kReturnStatsRiskFreeAnnual = 0.02
	Fixed annual risk-free rate.

constexpr std::int64_t	kReturnStatsUtcMinMs = -1099511627775000
	Earliest Unix millisecond timestamp whose UTC month can be derived (inclusive).

constexpr std::int64_t	kReturnStatsUtcMaxMs = 1099511627775999
	Latest Unix millisecond timestamp whose UTC month can be derived (inclusive).

constexpr std::size_t	kReturnStatisticCount = 9
	Number of published fields per series.

constexpr std::size_t	kReturnStatsMetricCount = 18
	Number of metric names of this contract (two series times nine fields).

Typedef Documentation

◆ Dimension

using pineforge::hpo::Dimension = typedef std::variant<IntegerDimension, RealDimension, BooleanDimension, CategoricalDimension>

Closed variant over every supported search-space dimension type.

Definition at line 135 of file search_space.hpp.

◆ ErrorArguments

using pineforge::hpo::ErrorArguments = typedef std::map<std::string, ErrorArgument>

Deterministically ordered failure arguments. No strategy-computed value belongs here.

Definition at line 44 of file error.hpp.

◆ MetricMap

using pineforge::hpo::MetricMap = typedef std::unordered_map<std::string, double>

Metric values keyed by canonical objective path.

Definition at line 18 of file objective.hpp.

◆ ObjectiveFn

template<typename Observation >

using pineforge::hpo::ObjectiveFn = typedef std::function<ObjectiveResult(const Observation&, const TrialContext&)>

Type-erased custom objective accepting an observation and immutable trial context.

Definition at line 162 of file objective.hpp.

◆ ParameterValue

using pineforge::hpo::ParameterValue = typedef std::variant<std::int64_t, double, bool, std::string>

Scalar parameter value accepted by search spaces and the PineForge strategy ABI.

Definition at line 11 of file types.hpp.

◆ ParameterValues

using pineforge::hpo::ParameterValues = typedef std::map<std::string, std::string>

Serialized Pine input or runtime-override values keyed by strategy parameter name.

Definition at line 23 of file trial_executor.hpp.

◆ PortfolioObjectiveFn

using pineforge::hpo::PortfolioObjectiveFn = typedef ObjectiveFn<PortfolioObservation>

Custom objective function specialized for PortfolioObservation.

Definition at line 67 of file portfolio.hpp.

◆ SymbolFeeds

using pineforge::hpo::SymbolFeeds = typedef std::vector<SymbolData>

Study-owned collection shared read-only by all trial workers.

Definition at line 43 of file symbol_feeds.hpp.

Enumeration Type Documentation

◆ BinaryVerification

enum class pineforge::hpo::BinaryVerification

strong

Verification of a binary chart's sidecar and mapped bytes.

Enumerator
Full
Sidecar

Definition at line 14 of file dataset.hpp.

◆ CandidatePolicy

enum class pineforge::hpo::CandidatePolicy

strong

Uniqueness and coverage contract applied to sampler proposals.

Finite policies require a positive step on every varying real dimension. Candidates are reserved before ask() returns, so pending, completed, and abandoned points all remain seen.

Enumerator
SamplerDefault	Preserve native sampler behavior, including possible duplicates.
WithoutReplacement	Issue at most the requested number of unique finite candidates.
Exhaustive	Require a budget equal to cardinality and cover every candidate.

Definition at line 84 of file sampler.hpp.

◆ ConstraintRelation

enum class pineforge::hpo::ConstraintRelation

strong

Comparison relation applied by Constraint.

Enumerator
LessEqual	Require `lhs <= rhs + tolerance`.
GreaterEqual	Require `lhs >= rhs - tolerance`.
Equal	Require `abs(lhs - rhs) <= tolerance`.

Definition at line 114 of file objective.hpp.

◆ DimensionKind

enum class pineforge::hpo::DimensionKind

strong

Concrete dimension category stored by Dimension.

Enumerator
Integer	Discrete signed-integer lattice.
Real	Continuous or stepped binary64 interval.
Boolean	The two values `false` and `true`.
Categorical	Explicit ordered set of scalar choices.

Definition at line 16 of file search_space.hpp.

◆ DivisionByZeroPolicy

enum class pineforge::hpo::DivisionByZeroPolicy

strong

Behavior when an objective expression divides by zero.

Enumerator
Reject	Return an invalid ExpressionEvaluation.
Ieee754	Permit IEEE-754 infinity or NaN, subject to the result policy.

Definition at line 21 of file objective.hpp.

◆ EvaluationError

enum class pineforge::hpo::EvaluationError

strong

Stable reason code for an invalid ExpressionEvaluation.

Enumerator
None	Evaluation succeeded.
MissingMetric	A referenced identifier was absent from the metric map.
NonFiniteMetric	A referenced metric violated the non-finite metric policy.
DivisionByZero	Division by zero was rejected.
NonFiniteResult	Evaluation failed or produced a disallowed non-finite result.

Definition at line 43 of file objective.hpp.

◆ FailureOrigin

enum class pineforge::hpo::FailureOrigin : std::uint8_t

strong

Provenance of a failure, independent of its human-readable diagnostic.

Enumerator
Hpo
Engine

Definition at line 14 of file error.hpp.

◆ NonFinitePolicy

enum class pineforge::hpo::NonFinitePolicy

strong

Behavior when a metric or expression result is not finite.

Enumerator
Reject	Reject the non-finite value.
Allow	Preserve the non-finite value for the caller.

Definition at line 27 of file objective.hpp.

◆ ObjectiveDirection

enum class pineforge::hpo::ObjectiveDirection

strong

Direction used to rank a scalar objective.

Enumerator
Maximize	Larger finite values are better.
Minimize	Smaller finite values are better.

Definition at line 75 of file sampler.hpp.

◆ ParameterType

enum class pineforge::hpo::ParameterType

strong

Runtime discriminator for a ParameterValue alternative.

Enumerator
Integer	Signed 64-bit integer.
Real	IEEE-754 binary64 real.
Boolean	Boolean value.
String	UTF-8 string value.

Definition at line 14 of file types.hpp.

◆ PlanStatus

enum class pineforge::hpo::PlanStatus : std::int32_t

strong

Planner status words, independent of the C bridge's negative call return codes.

Enumerator
Ok	A complete plan is available.
RequestInvalid	The planner refused a request member or row pointer.
CalendarUnsupported	The calendar, clock or timeframe pairing is unsupported.
BoundaryUnaligned	T, E or F is not a script interval boundary.
FeedRangeInvalid	A supplied timestamp is outside [F, E).
RowsUnordered	Supplied timestamps are not strictly increasing.
InternalError	The planner reported an internal failure as result data.

Definition at line 19 of file window_plan.hpp.

◆ PrunerKind

enum class pineforge::hpo::PrunerKind

strong

Prefix pruning policy; disabled by default in the native runner.

Enumerator
None
Median
Halving

Definition at line 10 of file pruner.hpp.

◆ ReturnBlocksStatus

enum class pineforge::hpo::ReturnBlocksStatus : std::uint8_t

strong

Status of one row's block moments.

A payload carrying moment arrays is published only with status Ok. The other two wire statuses, NonPositiveEquity and Nonfinite, are published status-only so the module refuses the row by name. That is what the executor needs: requesting blocks must never turn a successful trial into a failed one, because that would move the optimizer's history.

Enumerator
NotRequested	No blocks were requested: no layout and no payload.
Ok	Every interval of every block was usable; wire text `ok`.
NonPositiveEquity	An interval was skipped because a prior equity is not positive; wire text `non_positive_equity`.
Nonfinite	An equity, a return or a moment is not finite; wire text `non_finite`.
UnusableCurve	The borrowed view cannot be read; no reduction was attempted.
UnusableLayout	No layout can be formed for this curve: S is odd or below 2, K is below S, a block-size rule of the module fails, an opening timestamp is below the one before it, or the layout handed to the reducer is not the one the rule gives for this curve and its block count.

Definition at line 223 of file return_stats.hpp.

◆ ReturnPeriodFailure

enum class pineforge::hpo::ReturnPeriodFailure : std::uint8_t

strong

Why the period or time basis of a series is unavailable. Diagnostic only; not on the wire.

Enumerator
None	The period is available.
TooFewPoints	Bar series with fewer than three points.
NonPositiveSpan	Bar series whose last timestamp does not exceed its first.
SpanOverflow	Bar series whose timestamp difference overflows 64 bits.
UtcRange	Monthly series with a timestamp outside the supported UTC range.

Definition at line 76 of file return_stats.hpp.

◆ ReturnSeries

enum class pineforge::hpo::ReturnSeries : std::uint8_t

strong

Return frequency of one statistics series.

Enumerator
Bar	Simple returns between adjacent curve points.
Monthly	Simple returns between consecutive last points of UTC calendar-month buckets.

Definition at line 41 of file return_stats.hpp.

◆ ReturnStatistic

enum class pineforge::hpo::ReturnStatistic : std::uint8_t

strong

One published field of a series. Declaration order is the wire order of the metric names.

Enumerator
Count	Number of valid returns of the series (T), never a bar counter.
Skipped	Intervals skipped because the prior equity is not positive.
PeriodsPerYear	Annualization basis P of the series; reported, never applied.
Mean	Raw mean of the valid returns.
Std	Sample standard deviation (T - 1 divisor).
SharpePerPeriod	Unannualised excess Sharpe ratio.
Skew	Population-moment skewness g1.
KurtRaw	Population-moment raw kurtosis b2 (a normal distribution gives 3).
Status	Numeric ReturnStatsStatus code.

Definition at line 47 of file return_stats.hpp.

◆ ReturnStatsStatus

enum class pineforge::hpo::ReturnStatsStatus : std::uint8_t

strong

Stable numeric status of one series.

Codes 3 and 5 of the draft proposal are not used.

When several causes apply the first match in this order wins: NonfiniteInput, UnsupportedTimezone, DerivedNonfinite, PeriodUnavailable, InsufficientCount, ZeroVariance, Ok. Status Ok holds if and only if every numeric field of the series is finite; a skipped return or a tiny finite variance is data and never a status.

Enumerator
Ok	Every field is finite.
InsufficientCount	Fewer than four valid returns: the full statistic set is undefined.
ZeroVariance	The computed variance is exactly zero.
NonfiniteInput	An input equity is not finite, or the view is unusable; all null.
PeriodUnavailable	The period or time basis is unavailable.
UnsupportedTimezone	Monthly series requested for a chart timezone other than UTC.
DerivedNonfinite	A derived return, sum, moment or ratio is not finite.

Definition at line 65 of file return_stats.hpp.

◆ TrialExecutionStatus

enum class pineforge::hpo::TrialExecutionStatus : std::uint8_t

strong

Terminal status of one native strategy execution.

Enumerator
kSucceeded	Backtest completed and a detached snapshot is available.
kEngineError	Strategy reported an error; no comparable snapshot is available.

Definition at line 204 of file trial_executor.hpp.

Function Documentation

◆ candidate_policy_name()

const char * pineforge::hpo::candidate_policy_name ( CandidatePolicy policy )

noexcept

Returns the stable StudySpec spelling of policy.

◆ compute_block_layout()

ReturnBlockLayout pineforge::hpo::compute_block_layout	(	const EquityPointsView &	points,
		std::uint32_t	blocks
	)

Cuts the adjacent intervals of a curve into blocks (S) blocks, and reads the opening timestamp of every one of them from the borrowed curve.

A pure function of the immutable curve view and S: it keeps no state, retains no pointer and reads the view only for its point count and its timestamps. An unusable view gives a layout that is not usable. No interval is ever dropped from K. An accepted request allocates S and S + 1 entries, which cannot exceed the point count of a curve the caller already holds.

References compute_block_layout().

Referenced by compute_block_layout().

◆ compute_return_stats()

ReturnStatsResult pineforge::hpo::compute_return_stats	(	const EquityPointsView &	points,
		const ReturnStatsRequest &	request
	)

noexcept

Computes the requested return statistics from a borrowed equity curve.

A pure function: it allocates nothing, throws nothing, keeps no state and retains no pointer, so it is safe to call concurrently on shared immutable input. Operation order is fixed and sequential (ascending index, centred two-pass); the translation unit must be built with floating-point contraction and fast-math disabled. When neither series is requested no work is done and the view is not read. An unusable view (null records with a nonzero count, a layout that does not fit its stride, or more than 2^53 records) yields status 4 for the requested series instead of being read.

References compute_return_stats().

Referenced by compute_return_stats().

◆ continuation_seed()

std::uint64_t pineforge::hpo::continuation_seed	(	std::uint64_t	seed,
		std::uint64_t	warm_trials
	)

noexcept

Derives a portable continuation RNG seed; an empty history preserves the original seed.

◆ dimension_contains()

bool pineforge::hpo::dimension_contains	(	const Dimension &	dimension,
		const ParameterValue &	value
	)

noexcept

Dispatches a type-aware membership test to the concrete dimension.

◆ dimension_kind()

DimensionKind pineforge::hpo::dimension_kind ( const Dimension & dimension )

noexcept

Returns the concrete category stored in dimension.

◆ dimension_name()

std::string_view pineforge::hpo::dimension_name ( const Dimension & dimension )

noexcept

Returns the name of the concrete dimension.

◆ is_utc_chart_timezone()

bool pineforge::hpo::is_utc_chart_timezone ( std::string_view chart_timezone )

noexcept

True for the chart timezone names that select UTC bucketing: empty, UTC and Etc/UTC.

References is_utc_chart_timezone().

Referenced by is_utc_chart_timezone().

◆ make_equity_points_view()

template<typename Record >

EquityPointsView pineforge::hpo::make_equity_points_view	(	const Record *	records,
		std::size_t	count,
		std::int64_t Record::*	time_ms,
		double Record::*	equity
	)

noexcept

Builds an EquityPointsView over count records of type Record from pointers to its time_ms and equity members, for example &pf_equity_point_t::time_ms.

Definition at line 101 of file return_stats.hpp.

◆ parameter_type()

ParameterType pineforge::hpo::parameter_type ( const ParameterValue & value )

noexcept

Returns the discriminator of value.

◆ parameter_type_name()

const char * pineforge::hpo::parameter_type_name ( ParameterType type )

noexcept

Returns a stable lowercase name for type.

◆ parse_return_stats_metric()

std::optional< ReturnStatsMetric > pineforge::hpo::parse_return_stats_metric ( std::string_view name )

noexcept

Resolves a metric name; returns an empty value for every name outside the eighteen.

References parse_return_stats_metric().

Referenced by parse_return_stats_metric().

◆ plan_selected_window()

SelectedPlan pineforge::hpo::plan_selected_window	(	const WindowPlanHelper &	helper,
		const DatasetView &	tape,
		const PlanRequest &	request
	)

Plans one window over a shared tape or prefix without copying or repacking any bars.

Binary searches cut the input to F <= timestamp < E before calling the helper. Dataset construction and both loaders already enforce strictly increasing timestamps; the owner must remain immutable, including mapped bytes. The request's T/E/F/N, timeframes and clock are passed unchanged. Empty cuts (including a possibly null pointer with count zero) reach the planner unchanged. Its retained rows are exactly the tail after trim_index.

Cutting and checking row endpoints take O(log n) time and constant auxiliary storage; the engine planner walks the bounded rows. No allocation scales with the tape. The returned view keeps the Dataset alive. Concurrent calls are compatible with an immutable tape and a helper kept alive for every call. Mapped-file verification remains the owner's duty.

Parameters

helper	Already loaded, verified planner helper.
tape	Owner-retaining immutable primary input, possibly spanning several folds.
request	One unmodified engine planning request.

Returns: Complete prediction, retained view and six native execution expectations.

Exceptions

TypedHpoError<std::invalid_argument>	with hpo_walkforward_plan_refused and closed status/option arguments for a planner refusal.
HpoError	with hpo_invariant for inconsistent successful plan data. Helper bridge failures propagate unchanged, including reason window_plan_load.

◆ reduce_return_blocks()

ReturnBlockMoments pineforge::hpo::reduce_return_blocks	(	const EquityPointsView &	points,
		const ReturnBlockLayout &	layout
	)

Reduces the bar returns of a curve into the blocks of its own layout.

A pure function of the immutable curve view and the layout: no worker, global or random state is read and nothing is retained except the returned vectors. The layout is accepted only when it equals the one compute_block_layout returns for the same curve and layout.blocks; anything else (including a layout marked usable that the rule would refuse) gives status UnusableLayout and no arrays. If both a skipped interval and a non-finite value occur, the status is Nonfinite. An interval whose prior equity is not positive is skipped, while a current equity at or below zero is allowed; a non-finite equity, return or moment gives status Nonfinite instead of an error, so a request never fails the trial it describes.

Within a block the order is fixed and sequential and matches the return-statistics reducer: sum the usable returns in ascending interval k, divide that sum by the count, then add the separately rounded (r - mean) * (r - mean) in ascending interval k, forcing m2 = 0 for a block of one interval. This translation unit must therefore be built with floating-point contraction and fast-math disabled, like the statistics reducer it sits beside.

References reduce_return_blocks().

Referenced by reduce_return_blocks().

◆ require_return_stats_identity()

void pineforge::hpo::require_return_stats_identity ( )

Refuses return statistics in a build whose identity is unbound.

Return statistics are published only by a build whose identity is bound to the compile commands that produced the reducer (see docs/internal/return-stats-identity.md). When it is not, because of a multi-configuration generator, a compiler launcher, a disabled compilation database, a CMake older than 3.19 and the like, this throws hpo_toolchain_unavailable (reason native_runner) whose text names the exact unbound reason. Every ordinary run, which requests no return statistics, never calls it and is unaffected. TrialExecutor calls it when a series is requested; the command line calls it earlier, before any plugin or dataset is loaded.

◆ return_blocks_status_text()

std::string_view pineforge::hpo::return_blocks_status_text ( ReturnBlocksStatus status )

noexcept

Returns the wire text of a status: ok, non_positive_equity, non_finite, and empty for the statuses that are never published as a payload status.

References return_blocks_status_text().

Referenced by return_blocks_status_text().

◆ return_stats_contract()

constexpr std::string_view pineforge::hpo::return_stats_contract ( )

constexprnoexcept

Contract string that was bound into this build's identity at configure time.

It is a separate constant from the reducer's own contract constant; a caller that includes both headers should assert that the two are equal.

Definition at line 30 of file return_stats_identity.hpp.

◆ return_stats_contraction_free()

bool pineforge::hpo::return_stats_contraction_free ( )

noexcept

Sanity probe of this translation unit's build: true when a multiply followed by an add is evaluated as two rounded operations (no contraction) and explicit fma is fused.

This is a fail-closed check, not an attestation of the whole translation unit and not a proof of cross-architecture equality.

References return_stats_contraction_free().

Referenced by return_stats_contraction_free().

◆ return_stats_identity_bound()

constexpr bool pineforge::hpo::return_stats_identity_bound ( )

constexprnoexcept

True when this build's return-statistics identity is bound to the compile commands that the build system generated for the reducer translation units.

It is false for builds that cannot be bound exactly: multi-configuration generators, compiler launchers or wrappers, response files, a missing or ambiguous compilation database entry, or a CMake older than 3.19. Such a build compiles and runs as usual, but a caller must refuse to publish return statistics, because no claim-bearing identity exists for them.

Definition at line 16 of file return_stats_identity.hpp.

◆ return_stats_identity_descriptor()

constexpr std::string_view pineforge::hpo::return_stats_identity_descriptor ( )

constexprnoexcept

Exact descriptor text that the identity is the SHA-256 digest of.

The text names every hashed source and header with its digest, the compiler fields and one line per normalized compile-command token. Proof tooling compares it with the compilation database of the build; it is not part of any result. An unbound build carries a short descriptor that names the reason.

Definition at line 54 of file return_stats_identity.hpp.

◆ return_stats_identity_unbound_reason()

constexpr std::string_view pineforge::hpo::return_stats_identity_unbound_reason ( )

constexprnoexcept

Short code naming why the identity is unbound; empty when it is bound.

Definition at line 21 of file return_stats_identity.hpp.

◆ return_stats_metric_name()

std::string_view pineforge::hpo::return_stats_metric_name	(	ReturnSeries	series,
		ReturnStatistic	statistic
	)

noexcept

Returns the wire metric name, for example returns.bar.sharpe_per_period.

References return_stats_metric_name().

Referenced by return_stats_metric_name().

◆ return_stats_numeric_build_identity()

constexpr std::string_view pineforge::hpo::return_stats_numeric_build_identity ( )

constexprnoexcept

Opaque identity of the build that computes return statistics; empty when unbound.

It binds the reducer source digest, the compiler identity and driver bytes, the compile command of each reducer translation unit as generated by the build system, and the contract string. It is the same on every sampler path (grid, random, TPE and candidate lists) and is never derived from, combined with or compared to a sampler checkpoint identity. Equal identities name equal builds; they do not attest that two builds produce equal arithmetic, and they say nothing about other architectures.

Definition at line 43 of file return_stats_identity.hpp.

◆ return_stats_source_digest()

constexpr std::string_view pineforge::hpo::return_stats_source_digest ( )

constexprnoexcept

SHA-256 digest, in lower-case hexadecimal, of the sorted reducer source and header entries; empty when unbound.

Definition at line 61 of file return_stats_identity.hpp.

◆ serialize_parameter_value()

std::string pineforge::hpo::serialize_parameter_value ( const ParameterValue & value )

Produces the exact text passed to strategy_set_input or strategy_set_override.

Real values use enough digits for a binary64 round trip. Non-finite real values are rejected because the engine input grammar has no portable representation for them.

Exceptions

std::invalid_argument if value is a non-finite real.

◆ sobol_numeric_build_identity()

std::string pineforge::hpo::sobol_numeric_build_identity ( )

Numeric build identity of the floating-point Sobol mapper, starting with portable-sobol-v1.

Request it only for a space with a varying real, stepped-real or log-integer column; a discrete-only space has no numeric identity. The portable-math environment is checked first and refused with the same typed error as the TPE sampler. An unbound build then throws hpo_toolchain_unavailable (reason native_runner) naming the exact unbound reason, so a missing identity can neither be published nor admit a floating-point continuation.

The string binds the mapper contract and revision, the Joe-Kuo table name, subset digest and word size, the digest of the build descriptor (sources, generated table, compile commands of every Sobol and portable-math translation unit, both compiler drivers), and the current rounding, gradual-underflow, contraction-canary and portable-probe evidence. The evidence is a sanity limit of this process, not an attestation: equal strings name equal builds, they do not show that two builds or two architectures compute equal values, and they are independent of the TPE checkpoint identity and of the return-statistics identity.

◆ sobol_numeric_identity_bound()

bool pineforge::hpo::sobol_numeric_identity_bound ( )

True when this build's Sobol numeric identity is bound to the compile commands that the build system generated for the Sobol sources and the portable-math target.

It is false for builds that cannot be bound exactly: multi-configuration generators, compiler launchers or wrappers, response files, a disabled, missing or ambiguous compilation database entry, or a CMake older than 3.19. Such a build compiles and runs as usual, including Sobol spaces without a floating-point column; only the floating-point identity is unavailable.

◆ sobol_numeric_identity_descriptor()

std::string_view pineforge::hpo::sobol_numeric_identity_descriptor ( )

Exact descriptor text whose SHA-256 digest is the build_sha256 field of the identity.

Proof tooling compares it with the compilation database of the build; it is not part of any result. An unbound build carries a short descriptor that names the reason.

◆ sobol_numeric_identity_unbound_reason()

std::string_view pineforge::hpo::sobol_numeric_identity_unbound_reason ( )

Short code naming why the identity is unbound; empty when it is bound.

◆ validate_selected_engine_version()

EngineVersion pineforge::hpo::validate_selected_engine_version	(	const std::optional< pf_version_t > &	numbers,
		const std::optional< std::string > &	full,
		const std::optional< std::string > &	expected_manifest_version = `std::nullopt`
	)

Parses and cross-checks embedded metadata without loading a plugin or consulting build headers.

Requires stable engine 1.x at least 1.6.2. Parses X.Y.Z[-rc.N][-D-gSHA][-dirty]; dirty suffixes are admitted with or without git distance, but release candidates are refused. A supplied manifest version must match the full embedded string exactly. Missing, malformed, unsupported and mismatched identities raise hpo_walkforward_unavailable with the corresponding engine reason.

Variable Documentation

◆ kReturnBlocksContract

constexpr std::string_view pineforge::hpo::kReturnBlocksContract = "pineforge-hpo-return-blocks/v1"

inlineconstexpr

Contract string of the per-row block_returns object and of the result-level return_blocks object that declares the layout its rows were reduced under (version 1, bar series).

Definition at line 17 of file return_stats.hpp.

◆ kReturnStatisticCount

constexpr std::size_t pineforge::hpo::kReturnStatisticCount = 9

inlineconstexpr

Number of published fields per series.

Definition at line 35 of file return_stats.hpp.

◆ kReturnStatsContract

constexpr std::string_view pineforge::hpo::kReturnStatsContract = "pineforge-hpo-return-stats/v1"

inlineconstexpr

Contract string of the result-level return_stats object (legacy mode, version 1).

Definition at line 13 of file return_stats.hpp.

◆ kReturnStatsMetricCount

constexpr std::size_t pineforge::hpo::kReturnStatsMetricCount = 18

inlineconstexpr

Number of metric names of this contract (two series times nine fields).

Definition at line 38 of file return_stats.hpp.

◆ kReturnStatsRiskFreeAnnual

constexpr double pineforge::hpo::kReturnStatsRiskFreeAnnual = 0.02

inlineconstexpr

Fixed annual risk-free rate.

The per-period rate is this value divided by the series' periods per year; it is not configurable in contract version 1.

Definition at line 21 of file return_stats.hpp.

◆ kReturnStatsUtcMaxMs

constexpr std::int64_t pineforge::hpo::kReturnStatsUtcMaxMs = 1099511627775999

inlineconstexpr

Latest Unix millisecond timestamp whose UTC month can be derived (inclusive).

Definition at line 32 of file return_stats.hpp.

◆ kReturnStatsUtcMinMs

constexpr std::int64_t pineforge::hpo::kReturnStatsUtcMinMs = -1099511627775000

inlineconstexpr

Earliest Unix millisecond timestamp whose UTC month can be derived (inclusive).

The monthly series refuses a timestamp outside [kReturnStatsUtcMinMs, kReturnStatsUtcMaxMs] explicitly (status 6) instead of converting it with unproved arithmetic. The range is floor(time_ms / 1000) within plus or minus (2^40 - 1) seconds, about 34,800 years each way. Negative epochs inside the range are valid: months are floored, never truncated toward zero.

Definition at line 29 of file return_stats.hpp.

Classes

Typedefs

Enumerations

Functions

Variables

Typedef Documentation

◆ Dimension

◆ ErrorArguments

◆ MetricMap

◆ ObjectiveFn

◆ ParameterValue

◆ ParameterValues

◆ PortfolioObjectiveFn

◆ SymbolFeeds

Enumeration Type Documentation

◆ BinaryVerification

◆ CandidatePolicy

◆ ConstraintRelation

◆ DimensionKind

◆ DivisionByZeroPolicy

◆ EvaluationError

◆ FailureOrigin

◆ NonFinitePolicy

◆ ObjectiveDirection

◆ ParameterType

◆ PlanStatus

◆ PrunerKind

◆ ReturnBlocksStatus

◆ ReturnPeriodFailure

◆ ReturnSeries

◆ ReturnStatistic

◆ ReturnStatsStatus

◆ TrialExecutionStatus

Function Documentation

◆ candidate_policy_name()

◆ compute_block_layout()

◆ compute_return_stats()

◆ continuation_seed()

◆ dimension_contains()

◆ dimension_kind()

◆ dimension_name()

◆ is_utc_chart_timezone()

◆ make_equity_points_view()

◆ parameter_type()

◆ parameter_type_name()

◆ parse_return_stats_metric()

◆ plan_selected_window()

◆ reduce_return_blocks()

◆ require_return_stats_identity()

◆ return_blocks_status_text()

◆ return_stats_contract()

◆ return_stats_contraction_free()

◆ return_stats_identity_bound()

◆ return_stats_identity_descriptor()

◆ return_stats_identity_unbound_reason()

◆ return_stats_metric_name()

◆ return_stats_numeric_build_identity()

◆ return_stats_source_digest()

◆ serialize_parameter_value()

◆ sobol_numeric_build_identity()

◆ sobol_numeric_identity_bound()

◆ sobol_numeric_identity_descriptor()

◆ sobol_numeric_identity_unbound_reason()

◆ validate_selected_engine_version()

Variable Documentation

◆ kReturnBlocksContract

◆ kReturnStatisticCount

◆ kReturnStatsContract

◆ kReturnStatsMetricCount

◆ kReturnStatsRiskFreeAnnual

◆ kReturnStatsUtcMaxMs

◆ kReturnStatsUtcMinMs