Single-Machine Tree Simulation ============================== P17.4 adds a deterministic single-machine spatial simulation over a pinned tree inventory. It moves one machine through one block, selects trees by reach, rejects trees blocked by terrain or circular obstacles, and emits per-tree processing events. It is a reference execution layer, not a calibrated machine-routing or physics model. The phase plan is `notes/tree_scale_simulation_plan.md`. Model ----- The simulator: - starts at an explicit ``(x, y, z)`` point, or at the first tree when no start is supplied; - processes the nearest feasible tree within ``reach_radius_m``; - when no tree is in reach, moves to an approach point within reach of the nearest feasible tree; - rejects a tree when a circular obstacle contains it or when the absolute terrain slope between the current position and the tree exceeds ``max_slope_percent``; - uses the ADV6N10 harvester regression for processing time, with the tree's merchantable volume, log count, one stem per cycle, and mean log length; - uses a constant ``travel_speed_m_per_s`` for moves. The default values are reach ``10 m``, travel speed ``0.5 m/s``, and maximum slope ``35%``. They are reference parameters, not field-calibrated settings. A start point can represent a landing. Automatic landing-geometry lookup is not part of P17.4; pass the landing coordinates explicitly when that matters. CLI --- .. code-block:: bash fhops tree simulate scenarios/example/scenario.yaml \ --block B01 \ --machine H1 \ --start-x 881700 --start-y 627500 --start-z 412 \ --reach-radius 10 \ --max-slope 35 \ --out build/tree_machine Optional circular obstacles use ``--obstacle x,y,radius_m`` and may be repeated. Outputs: - ``tree_machine_events.csv`` — one row per visit or unreachable tree; - ``tree_machine_simulation.json`` — manifest with parameters, events, totals, volume reconciliation, warnings, and caveats. ``--dry-run`` prints the manifest without writing files. Limits ------ - One machine, one block. Multi-machine traffic, forwarding/landing logistics, and whole-landscape routing are out of scope. - Tree positions and elevations come from the inventory; terrain is not a DEM. - Obstacles are circular exclusions supplied explicitly; FHOPS does not infer them from geometry or point clouds. - Travel is constant speed, not a machine dynamics model. - Processing time uses an existing harvester regression and the reference stem model; it is not a field-validated productivity claim. - No 3D scene or video is produced in this task. See :doc:`tree_replay` for the schedule-coupled replay.