- Generated by
1.9.8
|
PineForge HPO 0.1.0
Native hyperparameter optimization for PineForge strategies
|
Native hyperparameter optimization for PineForge strategies.
pineforge-hpo compiles a PineScript strategy once, then runs parameter trials in a parallel C++ hot loop. It supports exhaustive search, reproducible random search, dlib global optimization, and a native Tree-structured Parzen Estimator (TPE). Objective functions can combine PineForge backtest metrics with arithmetic expressions and constraints.
Project status: alpha. The single-strategy path supports Linux and macOS. The public C++ model includes portfolio observations and custom-objective contracts, but multiple-strategy shared-account execution is not implemented yet.
strategy_set_input() and supported strategy(...) settings use strategy_set_override().+, -, *, /, comparisons, min, max, and abs.The HPO layer consumes the public PineForge C ABI. It is not a BacktestEngine subclass, and it does not move transpiler or optimizer behavior into pineforge-engine.
Clone the repository, then initialize the two pinned integration dependencies:
The Python distribution exported by pineforge-codegen-oss is named pineforge-codegen; its import module is pineforge_codegen.
The gitlinks are the compatibility baseline tested for the current HPO revision. Do not replace them with each dependency's moving main branch in a release build. Updating a gitlink requires the same native tests and nine-trial end-to-end study used by CI. The submodules remain separate projects under their own licenses; nested engine corpus and benchmark-asset submodules are not required by this quick start.
The first engine configure downloads Eigen when it is not installed. The first HPO configure downloads the pinned dlib 20.0.1 archive and verifies its SHA-256; pass -DPINEFORGE_HPO_USE_SYSTEM_DLIB=ON only when an exact 20.0.1 CMake package is already installed.
From the pineforge-hpo repository root, the following block builds the engine and HPO runner, installs both local Python packages, runs the test suite, and executes the bundled nine-trial example:
The command prints the complete JSON result. Check the compact summary with:
You should see ok: True, trials_completed: 9, and full_parameter_coverage: True. The first run transpiles and builds the strategy plugin; later runs reuse its content-addressed cache when the Pine source, engine ABI, codegen, compiler, flags, and dependencies have not changed.
To compile a Pine strategy without starting a study:
This returns the plugin, manifest, provenance, artifact key, and cache-hit state as JSON. An existing validated plugin can also be referenced from a StudySpec, allowing the native runner to be used without installing the transpiler. See the complete StudySpec reference.
Studies are strict JSON documents. Paths are resolved relative to the StudySpec file, not the shell's current directory. The bundled example is examples/single_strategy/study.json.
The three fields most commonly changed are the strategy search space, objective, and sampler:
This is an excerpt rather than a complete StudySpec. Strategy, dataset, and execution objects are shown in the schema documentation.
| Sampler | Best fit | Important behavior |
|---|---|---|
grid | Small finite spaces and coverage baselines | Deterministically enumerates the Cartesian product. |
random | Broad, inexpensive exploration | Seeded std::mt19937_64; supports continuous and log dimensions. |
dlib_global | Model-based search over mixed numeric spaces | Native batched ask/tell through dlib global function search. |
tpe | Adaptive refinement over mixed spaces | Native Parzen marginals, categorical probabilities, and constant-liar batches. |
TPE and dlib are adaptive: proposal order depends on both the seed and worker-sized batch schedule. Compare optimizers under the same objective-evaluation budget and across multiple seeds. For large 10^6-10^8 candidate domains, do not ask one TPE study to enumerate the domain. Use an external coordinator to shard a finite grid or broad search, then reserve TPE for bounded refinement. This runner does not currently provide distributed partitioning, and its TPE deliberately retains its complete usable history.
| Policy | Guarantee |
|---|---|
sampler_default | Preserves the sampler's native behavior. Continuous real dimensions are allowed and TPE may repeat a vector. |
without_replacement | Every complete vector is reserved at most once. The trial budget cannot exceed the finite-space cardinality. |
exhaustive | Adds trials == cardinality, so every declared vector is attempted exactly once. |
Finite policies are implemented for grid and tpe. Every varying real dimension must declare a positive step; low == high is a one-value dimension and needs no step. Pending, completed, infeasible, failed, and abandoned candidates remain reserved, so parallel workers cannot repeat them. A non-constant log-real dimension is continuous and therefore cannot use a finite policy in StudySpec v1.
exhaustive guarantees parameter coverage. Equality with a successful grid-search optimum also requires deterministic data and execution, plus a comparable result at every point. See ADR 0003 for the exact lattice and floating-point contract.
Expression objectives can read metrics.all.*, metrics.longs.*, metrics.shorts.*, metrics.equity.*, and selected report counters such as report.total_trades. Expressions are parsed once before trials begin. Unknown metric paths, non-finite final values, and configured division-by-zero failures cannot silently become a winning trial.
Applications embedding the C++ library can instead implement ObjectiveFn<Observation>. The generic objective contract is independent of a PineForge report; the executable CLI currently resolves expression objectives only.
pineforge-hpo compile and pineforge-hpo run initialize artifacts and studies.build/bin/pineforge-hpo-native runs a compiled plugin and normalized OHLCV directly. Use --help for its lower-level flags.ArtifactBuilder, StudySpec, validation models, and transpiler bridge are exported from pineforge_hpo.include/pineforge/hpo/. Build-tree consumers can link PineForgeHPO::core or PineForgeHPO::engine_adapter.For an optimizer-only embedding with no PineForge engine checkout, configure with PINEFORGE_HPO_BUILD_ENGINE_ADAPTER=OFF and PINEFORGE_HPO_BUILD_NATIVE_CLI=OFF. PineForge HPO 0.1.x currently exposes CMake build-tree targets; an installed CMake package is not published yet. Both adapter targets default to off when PineForge HPO is included with add_subdirectory(). Core-only users may leave both external/ submodules uninitialized.
After GitHub Pages is enabled, the workflow publishes the C++ and Python API reference. Until then, build the same site locally. The reference is generated from the public headers and Python facade on the repository's default branch.
Initialization and execution are deliberately separated:
pineforge_codegen.transpile_full() emits generated C++, input metadata, and strategy(...) parameters once.ArtifactBuilder compiles and validates a content-addressed strategy plugin once.StrategyPlugin and immutable OHLCV data are loaded once for the study.The component boundaries, plugin lifecycle, objective abstraction, finite-space codec, and future account-level execution model are documented in `docs/architecture.md`.
The benchmark suite separates optimizer quality from proposal/feedback API overhead and records raw per-seed results. It includes standard nonlinear functions, a mixed-type interaction problem, and an independently exhaustively verified one-million-candidate discrete problem. The native TPE comparison pins official Optuna in an isolated benchmark-only environment; Optuna is not a runtime dependency.
Start with `benchmarks/README.md` for the benchmark protocol, smoke/full commands, output schema, fairness rules, and guidance for contributing results. The detailed native-versus-Optuna methodology lives in `benchmarks/optuna/README.md`, with the checked-in reference run in `results-2026-07-18.md`.
Published numbers are evidence for the tested problems, budgets, seeds, and machine—not a claim that one sampler dominates every backtest surface.
For a reproducible study, keep all of the following fixed:
pineforge-codegen-oss, compiler target, and exact compile flags;Generated strategies are compiled with the parity-critical -std=c++17 -O2 -ffp-contract=off -fPIC -shared flags. Result JSON includes the HPO version, sampler implementation identity, artifact key, complete trials, cardinality, and coverage diagnostics. Preserve the result and artifact provenance together when reporting a benchmark or bug.
Implemented today:
Not implemented yet:
Independent strategy reports must not be described as a shared-account simulation. See `docs/plan.md` for the staged roadmap.
See CONTRIBUTING.md for the complete native/Python checks, architecture boundaries, benchmark contribution rules, and pull-request checklist. Repository administrators should also complete the one-time GitHub setup checklist after the initial public push.
Run the required local checks from the repository root:
Please report bugs and propose features in the GitHub issue tracker. Include a minimal StudySpec, the complete result/provenance JSON, platform and compiler information, and whether the behavior reproduces with one worker. Report suspected vulnerabilities privately according to SECURITY.md.
Additional design and validation material:
Original code in this repository is licensed under the [Apache License 2.0](LICENSE). dlib 20.0.1 is used under the Boost Software License 1.0; notices are recorded in LEGAL.md and THIRD_PARTY_LICENSES.
The optional PineScript bridge invokes the pineforge-codegen distribution from the pineforge-codegen-oss repository. That separately distributed project has its own source-available license and commercial-use terms; it is not relicensed under Apache-2.0. Running pineforge-hpo-native with an already compiled strategy plugin does not require the transpiler. See LEGAL.md for the dependency boundary.
1.9.8