FHOPS Documentation

Welcome to the Forest Harvesting Operations Planning System (FHOPS) docs. These pages explain the platform architecture, data contract, optimisation stack, heuristics, and evaluation workflows. The structure mirrors our roadmap so that implementation status stays transparent.

The executed analytics notebook suite (Analytics Notebooks) demonstrates end-to-end playback, stochastic robustness, and benchmarking stories. The notebooks run in CI with the FHOPS_ANALYTICS_LIGHT=1 flag to keep stochastic samples lightweight; unset it locally for full ensembles.

Getting Started

• Overview
  • Motivation
  • Automation pipeline
  • Installation
  • Quick demo
  • Baseline Workflows
• Quickstart
  • Bootstrap Environment
  • Workbench: examples/tiny7
  • Regression Fixture (Phase 1 Baseline)
  • Rolling horizon loop (playback + KPIs)
  • Shift-enabled scenarios
• Tree-Scale Workflow
  • Synthetic fixture
  • Run the complete path
  • Outputs
  • Fail-closed behavior
  • Limits
• Nemora Tree-Inventory Handoff
  • Fixture
  • Boundary
• Data Contract Guide
  • Reference dataset generator
  • Core Tables (CSV)
  • Cross References & Validators
  • Optional Extras
  • Timeline Example
  • Shift Calendars & Defaults
  • Schedule Locking
  • Initial State (Resuming Mid-Operation)
  • Compatibility with FHOPS 1.0.0
  • GeoJSON Ingestion & Distances
  • Machine-Rate Defaults & Costing Helper
  • Road Construction Tables & Validation
  • Skyline Stand Profiles
  • Log Hauling Extension
  • LidarBC Products
  • Tree Inventories
  • Authoring Checklist
  • Fixture Gallery
• Benchmarking Harness
  • Quick Start
  • CLI Options
  • Watching heuristic progress
  • FAQ – Watch Mode
  • Standard Manuscript Pipeline
  • Optional Gurobi backend (Linux)
  • Interpreting Outputs
  • Comparing MIP and heuristic objectives
  • Shared KPI roll-up
  • Operator Telemetry
  • Visual Comparisons
  • Regression Fixture
  • Future Work
• Heuristic Presets & Registry Guide
  • Shared Solver Cheat Sheet
  • Preset Overview
  • Applying Presets
  • Explicit Overrides
  • Solver-Specific Parameters
  • Parallel & Advanced Features
  • Operator Catalogue
  • Telemetry & Benchmarking
  • Objective Weights, Automatic Overrides, and Hard Violations
  • Next Steps
• Operational MILP Warm Starts
  • Workflow
  • Solver support
  • Solve outcomes
  • Current limitations
  • Practical guidance
  • Future work
• Operational MILP Formulation
• Parallel Heuristic Workflows
  • Multi-start Runs
  • Batched Neighbour Evaluation
  • API Reference
  • Profiling Notes
• Evaluation Workflows
  • Running deterministic playback
  • Optional flags
  • Reporting templates
  • Quickstart example
  • Aggregation helper reference
  • KPI formulas & required signals
  • Relationship to KPI evaluation
• Thesis Evaluation Workflow (Chapter 2)
  • Context & Goals
  • Pipeline Overview
  • Worked Example (med42 Template)
  • Tips & References
• Telemetry-Driven Tuning
  • Prerequisites
  • Step 1 – Collect Telemetry
  • Step 2 – Generate a Comparison Report
  • Sample Output
  • Step 3 – Iterate
  • Step 4 – Compare Multiple Reports
  • Historical Trends
  • Delta Snapshot Summary
  • Interpreting Dashboards
  • Automated Sweeps
  • Notebook execution cadence
  • Heuristic parameter catalogue
  • Convergence metrics
  • Bundle Aliases
  • CI Automation
  • Downloading CI Reports
• Telemetry Ops Runbook
  • Weekly Notebook Pipeline
  • Telemetry Store Maintenance
  • Automation Checklist
  • Runbook Template (per week)
  • References
• Release & Contribution Playbook
  • Release Preparation
  • Contribution Checklist
  • Where to Update Next
• Synthetic Datasets
  • Reference bundles
  • Fleet roles and harvest systems
  • Block enrichment, crews, and blackouts
  • CLI walkthrough
  • Regenerating bundles
  • Where to go next
• Harvest System Sequencing How-to
  • Configuring Scenarios
  • Sequencing Semantics
  • Running the Solvers
  • Inspection & KPIs
  • Benchmarking with Sequencing
  • Troubleshooting
• Iterated Local Search How-to
  • Basic Usage
  • Telemetry
  • Benchmarks
• Tabu Search How-to
  • Basic Usage
  • Telemetry
  • Benchmarks
• Rolling-Horizon Planning
  • When to use
  • Key parameters
  • How state carries between windows
  • MILP windows: earliness tie-break
  • Windows without a plan
  • CLI usage
  • Worked example (tiny7)
  • Outputs
  • MILP example with solver options
  • Evaluating rolling plans
  • Rolling comparison helper
  • MASc experiments & plots
  • Sample artefacts
  • Artefact provenance & regeneration
  • Gotchas
  • Notes
  • Limitations
• Tactical–Operational Scenario Contract
  • Canonical formulation
  • Loading and validation
  • Period templates
  • Core MILP formulation
  • Optional infrastructure modules
  • Scenario overlays, diffs, and batch reports
  • Tactical-to-operational handoff
  • Scale benchmarks and uncertainty envelopes
  • Practitioner-scale validation case
  • Guided tactical planner notebook
  • topm-mini acceptance fixture
• Salvage Shelf-Life and Wood Degradation
  • Sources and boundaries
  • Quick start
  • Output columns
  • Adding another curve
  • Python API
  • Limits
• Log Hauling
  • Schema version
  • Minimal example
  • Marine and barge legs
  • Entity rules
  • Contractor eligibility
  • Units and defaults
  • Phase I solve
  • Phase II schedule
  • Phase III simulated annealing
  • CLI
  • Stable artefacts
  • Operational and tactical handoff
  • Scale case
  • Limitations
  • See also
• Hydrology Quickstart — FEMIC to WS4 to FHOPS
  • Version Matrix
  • Build the Synthetic Workspace
  • WS4 Landscape Screening
  • FHOPS Consumer and Operational Check
  • What This Demonstrates
  • What This Does Not Prove
  • Docs Check
  • Troubleshooting
  • Further Reference
• FHOPS Web UI
  • Shell and navigation
  • Install and run
  • Run discovery
  • Run manifest
  • Service surface
  • Map and layers
  • Domain panels
  • Live runs
  • Scenario editing
  • Skins
  • Assistant
  • Security and limits
• FHOPS serious game
  • Levels
  • Prerequisites
  • Start the service
  • How a round works
  • Scoring
  • Optional agent
  • Regenerate assets
  • Caveats

Reference

• API Reference
  • fhops Package
  • fhops.scenario Package
  • fhops.scheduling Package
  • fhops.optimization Package
  • fhops.evaluation Package
  • fhops.planning Package
  • fhops.salvage Package
  • fhops.hauling Package
  • fhops.web Package
  • fhops.planning.tactical_operational Package
  • fhops.model.milp.tactical_operational Module
• CLI Reference
  • solve-mip (deprecated alias) outcomes and exit codes
  • Heuristic configuration reference
  • Dataset command cheat sheet
  • Log-hauling commands
  • Web commands
• Aggregation Helpers
  • API summary
• Harvest System Registry
  • Data Model
  • Default Systems
  • Using the Registry
  • Scenario Cross-Links
  • Extending Systems
  • Preset Usage Cheat Sheet
  • Forwarder Productivity Models
  • Roadside Processor Productivity Models
  • Optional Dataset Cookbook
  • Burned-Timber Salvage Guidance (ADV1N5)
  • Loader-Forwarder Productivity Models
  • Grapple Skidder Productivity Models
  • Grapple Yarder Productivity Models
  • Shovel Logger (Hoe-Chucker) Productivity
  • Skyline Productivity Models
  • Skyline cost matrix
  • Road & Subgrade Construction References
  • Handfalling Cost Reference
  • CTL Harvester Productivity Models
• fhops.hauling Package
  • Key models
  • Example
• Log-Hauling Formulation
  • Phase I: monthly daily flows
  • Phase II: daily truck and loader scheduling
  • Phase III: simulated annealing
  • Implementation notes and corrections
• fhops.web Package
  • Key objects
  • CLI
• Telemetry Logging
  • Schema
  • Usage Notes
  • CLI Reporting
  • Historical Trends
• Live Dashboards
  • Embedded previews
• Source Bibliography and Document Access
  • Public bibliography
  • Private full-text vault
• FEMIC LidarBC Products
  • Bundle Contract
  • Python Usage
  • Scenario Pin and Support
  • Operability Report
  • Operator Workflow
  • Shared Parity
  • Phase Close-Out
• TFL 6 LidarBC Fixture
  • What It Exercises
  • Terrain And Canopy Evidence
  • Files
  • Commands
  • Regeneration
  • Parity And Limits
• FEMIC Hydrology Response Bundles
  • Bundle Contract
  • Python Usage
  • Readiness
  • Scenario Pin
  • Support Mapping
  • Schedule-Bound Exposure
  • Screening
  • CLI
  • Limits
  • Operational Hazard Windows
  • Road and Culvert Assets
  • Operational Constraint Check
  • End-to-End Path
  • Solver Boundary
  • Operational End-to-End Path
• Hydrology Contract and Schema Index
  • Contract Layers
  • FEMIC Producer Contracts
  • WS4 Landscape Consumer Contracts
  • FHOPS Operational Consumer Contracts
  • Shared Exposure Contract
  • Failure Matrix
  • What Is Not a Contract
  • Version Compatibility
• Tree Inventory Contract
  • Inventory Format
  • Scenario Pin and Block Map
  • CLI
  • Fixture
  • Limits
• Stem Volume and Bucking
  • Reference Model
  • Python API
  • CLI
  • Limits
• Single-Machine Tree Simulation
  • Model
  • CLI
  • Limits
• Tree-Scale Schedule Replay
  • Input
  • CLI
  • Limits
• Tree Scene Export
  • What is exported
  • CLI
  • Limits
• Ground-Based System Simulation
  • Command
  • Outputs
  • Determinism and invariants
  • Limits
  • Committed example

Examples

• Stochastic Robustness Walkthrough
• Analytics Notebooks

Project Processes

• Contributing
• Roadmap Summary
• Mobilisation Geospatial Workflow
• Productivity Catalog Gaps