Overview

FHOPS (Forest Harvesting Operations Planning System) provides a Python API and CLI for constructing, solving, and evaluating harvesting schedules. At its core FHOPS supplies:

  • A typed data contract describing blocks, machines, landings, and calendar information.

  • A deterministic MIP builder (Pyomo + HiGHS) for exact optimisation.

  • Metaheuristic solvers for larger instances where MIP alone is insufficient.

  • Evaluation routines to replay schedules, collect KPIs, and explore robustness.

  • Scheduling extensions for shift timelines, mobilisation parameters, and synthetic scenario generation scaffolding.

The roadmap in Roadmap Summary and the notes under notes/ guide ongoing development. Refer to Quickstart for a hands-on example.

Motivation

Forest harvest-planning software still leans on bespoke, closed toolchains that make it hard for regulators, Indigenous governments, and researchers to audit models or extend them for emerging policy questions. Jaffray et al. (2025, submitted to the International Journal of Forest Engineering) catalogue the recurring pain points: one-off solver integrations, weak telemetry, limited robustness testing, and siloed datasets that rarely ship with reproducible scripts. FHOPS exists to close those gaps for B.C. operations and comparable jurisdictions.

This paper highlights three gaps we actively address:

  1. Open, reusable tooling. FHOPS publishes its data contract, CLI, and solver implementations under MIT so other teams can ingest the same scenarios, swap heuristics, and contribute modules without vendor lock-in. The scenario schema mirrors what forestry engineers already use in practice (blocks, machines, landings, shifts), but the implementation is scriptable and version-controlled.

  2. Integrated workflow + automation. Instead of the ad hoc “optimizer + spreadsheet” pattern flagged in the review, FHOPS provides deterministic solvers (Pyomo+HiGHS), SA/ILS/Tabu heuristics, a turnkey tuning harness, and telemetry/playback tooling that run from the same CLI pipeline. Every figure/table in the manuscript will be regenerated from the exact scripts users run locally.

  3. Robust evaluation + extensibility. FHOPS layers stochastic playback, stress testing, and cost models over the base scheduler so we can quantify solution stability before fielding new policies. Those evaluation hooks also pave the way for forthcoming BC case-study validations (two–three tenures) that will reuse the platform documented here while reporting context-specific findings in separate publications.

Reuse plan: exporter script will render this Markdown into sections/includes/motivation_story.tex for the manuscript and docs/overview_shared_motivation.rst for Sphinx so the same paragraphs stay synchronized.

Automation pipeline

FHOPS SoftwareX automation pipeline

FHOPS automation pipeline generated from the manuscript TikZ source (auto-regenerated via make assets).

FHOPS uses the same PRISMA-inspired workflow diagram in both the SoftwareX manuscript and the user guide. The LaTeX source lives at docs/softwarex/manuscript/sections/includes/prisma_overview.tex and is rendered whenever make assets runs. Until we add an auto-exported PNG, the Sphinx docs reuse the narrative from that figure instead of embedding the raw TikZ diagram.

Pipeline summary

  1. Inputs: Scenario contract artefacts (blocks, machines, landings, calendars) plus curated reference datasets and automation configs.

  2. FHOPS core: Data-ingest validators, solver stack (MIP + SA/ILS/Tabu with tuner harness), and evaluation/telemetry modules.

  3. Shared artefacts: Benchmark tables, tuning leaderboards, playback + robustness summaries, costing demos, scaling sweeps, and Markdown/CSV snippets rendered via export_docs_assets.py.

  4. Outputs: SoftwareX manuscript assets, the reproducible submission bundle, and the mirrored Sphinx documentation sections that highlight FHOPS’ differentiators.

Note

Once the PNG export workflow lands we will replace this textual summary with a direct .. figure:: reference so the documentation shows the exact same visual as the manuscript.

Installation

FHOPS publishes wheels/sdists via Hatch. Install the current v1.1.0a1 tactical alpha with:

pip install fhops==1.1.0a1

The wheel contains the FHOPS package, CLI, solver dependencies, and runtime reference data. The worked examples under examples/ and developer notes under notes/ live in the source repository, so clone the repository when following documentation that references those paths.

For development or release verification, install Hatch and run the full suite locally:

pip install hatch
hatch run dev:suite

Quick demo

Demonstrate the tuning harness on synthetic scenarios from the CLI:

python scripts/run_tuning_benchmarks.py \
    --bundle synthetic-small \
    --out-dir tmp/demo-synth \
    --random-runs 1 --random-iters 400 \
    --grid-iters 400 --grid-preset explore \
    --bayes-trials 2 --bayes-iters 400 \
    --max-workers 8 \
&& column -t -s'|' tmp/demo-synth/tuner_report.md | sed 's/^/  /'

See Telemetry-Driven Tuning for more recipes (including tuned presets used for the release).

Baseline Workflows

Two canonical scenarios ship with the source repository:

  • examples/tiny7 — minimal CSV/YAML inputs illustrating the scenario contract.

  • tests/fixtures/regression — deterministic fixture covering mobilisation, machine blackouts, and harvest-system sequencing with baseline KPI/objective values.

Use the quickstart to validate both scenarios locally and compare CLI output against the documented baselines before extending the solvers or data contract.

For exhaustive schema details, see Data Contract Guide.