Code Map#

This page is a map of the ACRES code for a person who starts to read it. It gives the parts, the files of each area and the path of one control step. Each row names a file, its function, its data and the page that explains it.

The Parts and How They Connect#

Part	Folder	Language	Lines
The game	`Acres/Source/Acres/`	C++ (Unreal Engine 5.8)	64 400
ACRES Core	`Core/`	C++ and Python	17 200
The run-time library	`Runtime/`	C++	63 500
The Python packages	`Simulator/`, `Harness/`, `Learning/`, `Data/`	Python	31 900
The ROS 2 workspace	`ROS/`	C++ and Python	19 000
Verification	`Verification/`	Lean 4, Python, C++	16 400
Calibration	`Calibration/`	Python	44 200
Tools	`Tools/`	Python, C++, shell	69 200

The counts are of the source files (git ls-files), without the documentation and the data. The engine-free model files of the game (*Model.h, *Model.cpp) have 13 300 lines. They contain the mathematics. More than one third of the code is tools and calibration. A first reading does not need them.

The parts connect in these ways.

ACRES Core compiles the engine-free model files of the game. The two simulators thus have the same dynamics.
The run-time library contains ACRES Core and adds the vehicle program. acres_simulator calls it from Python.
The game and the Core server acres_core_sim open the same three sockets. One ROS 2 bridge operates with the two.
The Lean models give the formulas. Differential tests and golden vectors compare the code with the models.
The map tools write the map products. The game, ACRES Core and the run-time library read the same files.

Where to Start Reading#

Read these files in this sequence. Each one is short, or has a long header comment that explains its area.

Architecture: the parts, the layers of the game, the threads and the sockets.
Acres/Source/Acres/AcresVehicle.h: the vehicle pawn, the hub of a session in the game.
Acres/Source/Acres/AcresUtvModel.h: the Polaris dynamics and its drive-by-wire layer, in engine-free C++.
Core/Source/AcresCoreBatch.h: N Polaris environments on one shared world.
Runtime/Include/acres_runtime/api.h: the rules of the run-time library and the fleet.
Runtime/Include/acres_runtime/routes.h and planner.h: from the map and a plan to the prepared path of a mission.
Runtime/Source/command_chain.cpp: the launch hold, the gear logic and the command row. Read this file with care.
Runtime/Source/shield.cpp: the shield, one pure function that follows its Lean model.
Simulator/acres_simulator/__init__.py: the Python package where your code connects.
Vehicle Software: the specification of the chain.

The Game#

All files of this section are in Acres/Source/Acres/. A name without an extension is the .h file and the .cpp file. A model file uses standard C++ and SI units and has no Unreal types. ACRES Core and the model tests compile these files.

Vehicle and Physics Models#

File	What It Does	Reads and Writes	Page
`AcresVehicle`	The vehicle pawn: the glue between the SI vehicle model and Chaos. `AsyncPhysicsTickActor` is the physics step at 120 Hz.	Reads the session files. Gives Chaos the total force and torque.	Architecture, Time Stepping
`AcresPolaris.cpp`	The Polaris branch of the pawn: its parameters, its drive-by-wire command path (`StepPolarisControls`), its rig, its keyboard driver and its reports.	Reads the commands of the queue. Writes the drive-by-wire reports.	Polaris Ranger Dynamics
`AcresVehicleControl.cpp`	What the simulator control needs from a vehicle: teleports, resets, hardware shifts and the replay of a logged episode.	Reads and writes the episode-log state.	Simulator Control Channel
`AcresVehicleModel`	The tractor dynamics: tires, soil contact, suspension, drivetrain and steering.	Model inputs and outputs only.	Maxxum 150 Dynamics
`AcresUtvModel`	The Polaris dynamics and its Dataspeed drive-by-wire layer (`StepDbw`), with the watchdog.	Model inputs and outputs only.	Polaris, Drive-by-Wire and ULC
`AcresSimModel`	Small helpers: the engine torque curve, the wheel slip ratio and the Ackermann steering.	Model inputs and outputs only.	Maxxum 150 Dynamics
`AcresPowerModel`	The engine fuel map and the energy ledger of a vehicle.	Model inputs and outputs only.	Energy and Fuel
`AcresSoilModel`	The soil library and the tire and soil forces.	Model inputs and outputs only.	Tire and Soil
`AcresSurfaceMap`	The ground surface class at a point, from vector polygons.	Reads `Acres/Content/Simulation/ACRE/surface_polygons.json`.	Crops and Ground Classes
`AcresImplementModel`	The implement and soil interaction of the attachments of the Maxxum.	Data: one file for each implement in `Acres/Content/Simulation/implements/`.	Implement Mechanics
`AcresImplementCoupling`	The glue between the soil library, the implement model, the pawn, the menu and the optimizer.	Model inputs and outputs only.	Implement Mechanics
`AcresFieldWorkModel`	What field work leaves on the ground: the surface after tillage, drilling, spraying, tires and the backhoe.	Model inputs and outputs only.	Implement Mechanics
`AcresCommandTiming.h`	The timestamped command queue: each message applies at the physics step of its arrival time. Lean has a model of it.	Reads commands with arrival times.	Formal Verification
`AcresRig`	The skeletal meshes of the vehicles and implements that follow the physics state.	Reads the rig maps in `Acres/Content/Simulation/rigs/`.	Add a Vehicle

Farm and Crop State#

File	What It Does	Reads and Writes	Page
`AcresFarmModel`	The crop and soil-water mathematics. It has no Unreal objects and no wall-clock time.	Model inputs and outputs only.	Soil Water, Crops and Ground Classes
`AcresFarmRuntime`	The live farm: crops, soil water, ruts and the harvester. It connects the farm model to the ACRE map.	Reads `Acres/Content/Simulation/farm.json` and the map products. Writes the farm marks.	Soil Water
`AcresFieldSetup`	The field configuration of a session: crop type, soil, starting wetness and terrain edits.	Reads and writes `field-setup.json` of the session.	Configuration Files
`AcresFields.h`	The numeric field identifiers. The game and ACRES Core share them.	Identifiers of `Acres/Content/Simulation/ACRE/fields.json`.	Map Products
`AcresFieldMarks.h`	The marks of field work on the 25 cm cells of the farm. The game and ACRES Core share them.	Sparse maps with a world cell as the key.	Regional Field Work
`AcresCrops.h`	The crop kinds for the farm runtime, the menu, the optimizer and the sensors.	None.	Crops and Ground Classes
`AcresRegionalMap`	The surveyed extension of the terrain round the original tile: heights in world meters.	Reads the bytes of `DriveRegion/region.bin`.	The ACRE Scene
`AcresRegionCropData`	The baked occupancy of the standing crops outside the original tile. It holds no crush or growth state.	Reads `DriveRegion/crops.bin`, which `Tools/ACRE/Map/regional_crops.py` writes.	Scene Fidelity and Streaming Plan
`AcresPlaces`	The named places of the tile and the spawn places.	Reads `Acres/Content/Simulation/ACRE/places.json`.	Map Products
`AcresNpc`	The farm traffic: pickups, tractors, workers and the highway traffic on US 52.	Reads the car models of `Acres/Content/Simulation/npc_cars.json`.	Farm Traffic and Workers
`AcresPathObjects`	Objects on the path that are not in the map: a truck and a person, as in ACRES Core.	Writes the objects into the episode log.	Objects on the Path

Environment and Weather#

File	What It Does	Reads and Writes	Page
`AcresEnvironmentModel`	The weather, sky and clock model of the site, in engine-free C++.	Model inputs and outputs only.	Weather
`AcresEnvironment`	The Unreal adapter: it steps the model and drives the sky, the light, the fog and the rain.	Reads `Acres/Content/Simulation/environment.json`.	Weather, Set Soil and Weather

Sensors#

File	What It Does	Reads and Writes	Page
`AcresSensors`	The sensor recorder: truth, actions, GNSS, IMU, LiDAR, camera and CAN. The physics step is its clock.	Reads the sensor files of the session. Writes the sensor episodes.	Sensors and Rigs
`AcresLidarModel`	The radiometric and multi-return LiDAR model for the CPU path and the GPU path.	Model inputs and outputs only.	LiDAR
`AcresLidarPhysics.h`	The parts of the LiDAR radiometry that the Helios calibration added.	Model inputs and outputs only.	LiDAR
`AcresLidarGpu`	The GPU LiDAR: it traces the scan rays against the ray-tracing scene of the renderer.	Shader: `Acres/Shaders/AcresLidar.usf`.	LiDAR
`AcresCameraModel`	The photometric and geometric model of an RGB camera, on the CPU, after the scene capture.	Reads the rendered image. Writes the sensor image.	Camera
`AcresGnssModel`	The GNSS receiver model in the position domain, with a synthetic constellation.	Model inputs and outputs only.	INS and GNSS
`AcresGeoUtm.h`	The Universal Transverse Mercator projection, header only.	None.	INS and GNSS
`AcresSensorStream`	The binary sensor stream: LiDAR clouds, camera images and INS epochs on a local TCP socket.	Writes frames to the ROS 2 bridge.	Sensor Stream

Rendering-Only Code#

These files change what a person and the camera see. They do not change the dynamics.

File	What It Does	Reads and Writes	Page
`AcresCropMarks`	The look of the crop patches that a machine changed, for each sample of a patch.	Reads the crushed and harvested bits of the farm.	Crops and Ground Classes
`AcresSoilVisuals`	Ground effects: rut tiles, field-work detail, standing water and particles.	Reads the 25 cm cells that the physics writes.	Soil Water
`AcresRegionStreaming`	The streaming policy of the regional scene: which mesh and collision chunks stay loaded.	Reads the positions of the vehicles, the sensors and the view.	Scene Fidelity and Streaming Plan
`AcresDriveRegion`	The regional ground actor: it loads the cooked chunks and shows the regional crops and their crushed state.	Reads `DriveRegion/crops.bin` and the cooked ground assets.	Scene Fidelity and Streaming Plan
`AcresBakeRegionCommandlet`	An offline builder of the regional ground, on the CPU. The game never runs it.	Writes the regional ground assets.	Tools and Scripts
`AcresRenderTier`	The two render tiers and the pinned render profile of the sensors.	Reads the GPU memory and the command-line options.	Platforms and GPU Tiers
`AcresSiteMap`	The drawn map of the site from the layers of the game. The HUD shows it in the minimap.	Reads the surfaces, the fields and `Scouting/obstacles.json`.	Map Products
`AcresVideoCapture`	The video recording of the game window to an MP4 file, also off-screen.	Sends frames to `ffmpeg`.	Command-Line Options

File	What It Does	Reads and Writes	Page
`AcresShell`	The game mode, the HUD class and the free-fly camera.	None.	Unreal for C++ Developers
`AcresMenu`	The full-screen menu, the terrain-brush editor and the pause menu, in Slate.	Writes a session folder with configuration copies.	Run the Packaged Game
`AcresSession`	A session as the menu configures it. One parameter table describes each value that the menu can edit.	Reads and writes the session files.	Configuration Files
`AcresAgents`	The vehicles of a session and the settings of each one.	Reads the agent list of the session.	Run Several Vehicles
`AcresHud.cpp`	The driving overlay, the engineering panel and the help panel of the camera.	Reads the telemetry of the pawn.	First Drive
`AcresRouteGuide`	The route guide of a piloted session: the shortest route on the lane graph. It sends no command.	Reads `Acres/Content/Simulation/ACRE/Scouting/scouting_map.json`.	Drive the Polaris Ranger
`AcresOptimizer`	Three planning tools for field work that the menu runs.	Reads the fields, the tractor and the weather of the session.	Optimizer
`AcresSessionLog`	The 120 Hz log of a menu session: `tractor.csv` and `session-summary.json`.	Writes into the session folder.	Session Log
`AcresEpisodeLog`	The episode log: an MCAP file of ROS 2 messages with the state of each agent at the physics rate.	Writes and reads the MCAP file. ACRES Core compiles the same file.	Episode Log
`AcresEpisodeSchemas.h`	The message schemas of the episode log. `Tools/EpisodeLog/gen_schemas.py` generates this file.	None.	Episode Log
`AcresReplay`	The replay input: a recorded drive that the tractor follows again.	Reads a recorded drive.	Replay

Control Channel and Vehicle Bridge#

An outside program talks to the game through three sockets on 127.0.0.1. Interfaces and Ports lists the ports.

File	What It Does	Reads and Writes	Page
`AcresRlBridge`	The vehicle bridge: an outside program drives a vehicle with JSON messages on TCP, or with CAN frames.	Reads commands. Writes reports.	Vehicle Bridge
`AcresSimControl`	The simulator control channel: pause, lockstep steps, resets, entities, conditions, hardware shifts, recording and replay.	Reads and writes JSON lines. Writes the episode log.	Simulator Control Channel
`AcresSensorStream`	The sensor stream, out only. The ROS 2 bridge makes ROS 2 messages from it.	Writes binary frames.	Sensor Stream
`AcresCommandTiming.h`	The queue between the bridge thread and the physics step.	Reads timed commands.	Time Stepping

The Python client of the control channel is Tools/SimControl/sim_control.py. The client of the vehicle bridge is in the library acres_runtime (Runtime/Include/acres_runtime/game.h).

ACRES Core#

The library is in Core/Source/. It adds a world layer round the model files of the game.

File	What It Does	Reads and Writes	Page
`Core/Source/AcresCoreBatch.h`	The batch: N independent Polaris environments on one shared world, with `Step` for 0.1 s.	Reads one command row for each environment. Writes the state arrays.	C++ API
`Core/Source/AcresCoreWorld.h`	The static world that all environments share: terrain, surface map, soil, field raster, crop patches, places.	Reads the files of `Acres/Content/Simulation/`.	C++ API
`Core/Source/AcresCorePolaris.h`	The Polaris on a rigid chassis. It compiles `AcresUtvModel` without a change and does the work of Chaos itself.	Reads a drive-by-wire command. Writes the chassis state.	Polaris Ranger Dynamics
`Core/Source/AcresCoreTerrain.h`	The survey terrain as the wheels of the game see it: the same triangles.	Reads the survey heights and `site.json`.	The ACRE Scene
`Core/Source/AcresCoreScene.h`	The static obstacles: buildings, grain bins and trees as simple shapes.	Reads `Core/Data/acre_scene.json`, which `Core/Scripts/build_scene.py` writes.	The ACRE Scene
`Core/Source/AcresCoreLidar.h`	The ray-cast LiDAR: the Helios pattern and the planar scan of 360 beams.	Reads the terrain, the scene and the objects.	LiDAR
`Core/Source/AcresCoreFarm.h`	What the machines of one environment leave on the farm: crushed crop, ruts, work flags.	Sparse changes for each episode.	Crops and Ground Classes
`Core/Source/AcresCoreEpisodeLog.h`	The episode log of the Core. It uses the writer of the game, thus the game replays the file.	Writes an MCAP file.	Episode Log

The Map Products#

The files of this section are in Learning/acres_learn/tasks/scouting/. The build parameters are in Learning/acres_learn/configs/scouting_v1.json.

File	What It Does	Reads and Writes	Page
`build_map.py`	Builds the map products for the 159 fields.	Writes `Acres/Content/Simulation/ACRE/Scouting/`.	Build the Map Products
`obstacles.py`	Makes the obstacle layer: the collision geometry that a vehicle can hit.	Writes `obstacles.json` in the same folder.	Build the Map Products
`map_products.py`	The loader of the map products (`ScoutingMap.load`).	Reads `scouting_map.json` and the ground classes.	Map Products

The Run-Time Library#

The chain of one control step is: default driver, launch hold, shield, gear logic, actuator clip. A model can propose a path chunk. The trajectory checker accepts or refuses it before the chain uses it.

Mission Plan#

File	What It Does	Reads and Writes	Page
`Runtime/Source/cost_table.cpp`	The cost tables: the default driver drives each edge and loop one time in ACRES Core.	Writes tables that state their map hash and the simulation version.	Planner
`Runtime/Source/option_graph.cpp`	The planning problem as an option graph: for each field, its entry points and directions.	Reads the cost tables.	Planner
`Runtime/Source/planner.cpp`	The exact dynamic programme over subsets of fields.	Gives the field order, the entry and the direction.	Formal Verification
`Runtime/Source/plan_check.cpp`	The plan checker: the gate for a plan from a source that the chain does not trust.	Reads a proposal. Gives a verdict.	Framework

Trajectory Checker#

The trajectory checker is in the run-time library (Runtime/Source/checker.cpp), with the plug-in that the build compiles from the Lean model.

File	What It Does	Reads and Writes	Page
`Runtime/Source/checker.cpp`	The trajectory checker: the gate for a chunk of a model.	Reads a chunk, the pose and the corridor. Gives a verdict.	Corridor
`Runtime/Source/band_checker.cpp`	The checker in C++ with no Lean plug-in. It accepts no trajectory that the model refuses.	The same inputs.	Corridor
`Runtime/Source/corridor.cpp`, `corridor_query.h`	The corridor of a leg as rasters, and its queries.	Reads the ground classes of the scouting map.	Corridor

Command Chain#

File	What It Does	Reads and Writes	Page
`Runtime/Source/command_chain.cpp`	The command chain of one control step: the launch hold, the shield and the command.	Reads the base command and the proposal.	Framework
`Runtime/Source/shield.cpp`	The shield: a deterministic function without state that replaces an unsafe command.	Reads the proposal, the base command, the corridor widths and the obstacle distance.	Framework
`Runtime/Source/sweep.cpp`	The obstacle distance of the shield: the free distance along the arc of the output curvature.	Reads the planar scan.	Framework
`Runtime/Source/sensor_scan.cpp`	The planar scan of the shield from a real 3-D LiDAR scan.	Reads `configs/scan_filter_v1.json`.	Sensors
`Runtime/Source/parameters.cpp`	The loader of `configs/control_v1.json` and `configs/envelope_v1.json`: the parameters of the shield and the speed envelope.	Checks each value when it loads the file.	Speed Envelope

Skills and Identity#

The skill server gives a planner or an agent one interface for ACRES Core and the game.

File	What It Does	Reads and Writes	Page
`Runtime/Source/skills.cpp`, `skill_server.h`	The skill server: the skills, their results and their events.	Reads a request. Gives a result and events.	Skills

File	What It Does	Reads and Writes	Page
`Runtime/Source/identity.cpp`	The map hash of a tree and the simulation version of the build.	Reads the map file. The build reads `Runtime/Reference/sim_version.txt`.	Identity
`Simulator/acres_simulator/scenarios.py`, `actors.py`	The Python call of the scenario generator of the library (`scenario.h`): the actors of an episode from a seed.	Reads `configs/path_objects_v1.json`.	Farm Actors

Verification#

Lean proves properties of models. Four links connect a model to the code: differential tests, golden vectors, a constants check and an axiom audit. Formal Verification gives the full table of the subjects.

File	What It Does	Code That It Models	Page
`Verification/AcresVerification/CommandTiming.lean`, `Watchdog.lean`	The models of the command queue, the clock and the watchdog of the drive-by-wire.	`AcresCommandTiming.h`, `AcresUtvModel.cpp`, `AcresPolaris.cpp`	Formal Verification
`Verification/AcresVerification/GearManager.lean`, `ActionMap.lean`, `Interpolation.lean`	The models of the gear logic, of the clip of the command row and of the interpolation.	`Runtime/Source/command_chain.cpp`, `detail::interpolate`	Formal Verification
`Verification/AcresVerification/Shield/`	The models of the shield and of the speed envelope, and their proofs.	`Runtime/Source/shield.cpp`, `command_chain.cpp`	Formal Verification
`Verification/AcresVerification/Mission/`	The model of the mission automaton and its proofs.	`Runtime/Source/tracker.cpp`	Formal Verification
`Verification/AcresVerification/Planner/`	The model of the exact planner and of the plan checker.	`Runtime/Source/planner.cpp`, `plan_check.cpp`	Formal Verification
`Verification/AcresVerification/Trajectory/`	The model of the trajectory checker and of the tube test.	The checker plug-in `Runtime/Lean/` (the compiled model)	Formal Verification
`Verification/Differential/run_differential.py`, `cpp_differential.py`	Give the same inputs to a model and to the code and compare the outputs bit for bit.	The command path of the game. The functions of the run-time library.	Formal Verification
`Verification/Differential/dbw_harness.cpp`	The C++ side of the differential test. The check script compiles it from the files of the game.	`AcresCommandTiming.h`, `AcresUtvModel.cpp`	Formal Verification
`Verification/Differential/golden/`	The golden vectors: inputs and outputs that the Lean executable writes. The production code must give the same bits.	The run-time library `Runtime/`.	Formal Verification
`Verification/check.sh`	The check script: it builds the proofs, runs the audits and runs the differential tests.	All subjects.	Formal Verification

Lean proves the order of launch hold, shield and command. Do not change that order.

ROS 2 Packages#

File	What It Does	Reads and Writes	Page
`ROS/acres_interfaces/`	The messages, the services and the action `Skill` of the simulator.	None.	Services and Actions
`ROS/acres_sim/src/main.cpp`	The node `sim_bridge`: it hosts one vehicle bridge for each vehicle and the services of the simulator.	The three sockets of the game.	Nodes and Launch Files
`ROS/acres_sim/include/acres_sim/vehicle_bridge.hpp`	One vehicle of the game on the topics that the real vehicle uses.	Reads the sensor stream and the reports. Publishes topics.	Topics
`ROS/acres_sim/include/acres_sim/sim_control.hpp`, `stream.hpp`, `conversions.hpp`	The client of the control channel, the transports of the game without ROS, and the message conversions.	JSON lines and binary frames.	Nodes and Launch Files
`ROS/acres_sim/include/acres_sim/j1939.hpp`	The J1939 and ISOBUS encoding of the CAN protocol of the game.	CAN frames of the Maxxum.	Wheel and CAN Signals
`ROS/acres_core_sim/include/acres_core_sim/CoreSimServer.h`	The Core server `core_sim`: ACRES Core behind the local protocols of the game.	Opens the same sockets as the game.	Nodes and Launch Files
`ROS/acres_core_sim/include/acres_core_sim/CoreSimDbw.h`, `CoreSimIns.h`, `CoreSimGeo.h`	The drive-by-wire command path, the INS model and the georeference of the game, without Unreal.	None.	INS and GNSS
`ROS/acres_description/`	The Polaris description: URDF, meshes, RViz configuration and launch files.	None.	Nodes and Launch Files
`ROS/Env/`	The conda environment file and the scripts of the DDS loopback fence.	None.	Build the ROS 2 Workspace

Add a ROS 2 Interface gives the steps for a new topic or service.

Tools#

Tools and Scripts describes each tool. This table gives the entry points.

File	What It Does	Reads and Writes	Page
`Tools/Terramechanics/`, `Tools/PolarisModel/`, `Tools/ImplementModel/`, `Tools/LidarModel/`	The tests of the engine-free models without Unreal.	Compile the model files of the game.	Tests and Regression Checklist
`Tools/EpisodeLog/`	The tests of the episode log and the schema generator.	Writes `AcresEpisodeSchemas.h`.	Tools and Scripts
`Tools/SimControl/sim_control.py`	The Python client of the control channel of the game. Each check of this folder uses it.	JSON lines on the control channel.	Simulator Control Channel
`Tools/SimControl/lockstep_determinism.py`	The check that the same seed and commands give the same result in lockstep.	Starts the packaged game.	Lockstep Stepping
`Tools/SimControl/render_check.py`	The check of the sensor camera, the GPU LiDAR and the main view at fixed poses.	Starts the packaged game.	Tools and Scripts
`Tools/SimControl/game_crosscheck.py`, `Tools/SimControl/check_planner_support.py`	The mission cross-check between ACRES Core and the packaged game, and the check of the planner support of the game, with the C++ chain.	Start `acres_runtime_game_crosscheck` (`Runtime/Tools`), `core_sim` and the game.	Game Link of the Run-Time Library
`Tools/SimControl/crosscheck_missions.py`	Scouting missions in ACRES Core and in the packaged game, with the measures of the two episode logs.	Starts the program of the library that drives. Reads two episode logs.	Tools and Scripts
`Tools/ACRE/Map/`	The map pipeline: sources, lanes, fields, crops, buildings, surfaces, places and the regional ground.	Writes the layers of `Calibration/Map/Layers/` and the map products.	Tools and Scripts
`Tools/ACRE/Map/game_layer.py`	Makes the ground-surface layer of the simulator as polygons.	Writes `surface_polygons.json`.	Map Products
`Tools/ACRE/Map/drive_routes.py`	Drives single-field missions in ACRES Core with the full command chain and the default driver.	Uses the fleet of the library `acres_runtime`.	Scouting Map
`Tools/Scene/rebuild_scene_and_map.sh`	Builds the Core scene and the scouting products again from a level export, and runs the route checks.	Writes `Core/Data/acre_scene.json` and the scouting products.	Scouting Map
`Tools/Scene/dump_level_state.py`, `Tools/Scene/level_fixes.py`	Reads each actor of the level, and brings the level in line with the map layers.	Read or change the level `V03ACRE`.	The ACRE Scene
`Tools/Performance/`	The frame-rate benchmarks.	Start the packaged game.	Tools and Scripts
`Tools/ui_text_check.py`	The check of the text style of each visible string of the game UI.	Reads the game source.	Tools and Scripts

The Harness#

The package Harness/acres_harness/ runs scenarios: a mission, objects on the path and a decision maker (scripted rules, a language model or a plugin). It uses the skills of the run-time library.

File	Function	Connection	Page
`Harness/acres_harness/loop.py`	The agent loop: wake-ups on events, the tool loop, the limits and the four modes.	Charges the time of each model call on the simulation clock.	Harness
`Harness/acres_harness/tools.py`	The tools of the model, each with a JSON schema, and the plan check with its counterexample.	Calls the plan checker and the option graph of the run-time library (`acres_simulator.plans`), and the skills.	Harness
`Harness/acres_harness/world.py`, `knowledge.py`	The world of a run on the skills of the run-time library (`acres_simulator.Skills`), and the store of what the vehicle sensed.	Reads the observation and the events of each control step.	Harness
`Harness/acres_harness/views.py`	The map pictures and the visual memory.	Reads the scouting map and the knowledge store.	Harness
`Harness/acres_harness/models/`	The session interface, the clients for OpenAI-compatible servers and for Claude, the scripted model and the replay model.	The SDKs `openai` and `anthropic` are optional.	Harness
`Harness/acres_harness/scenario.py`, `runner.py`, `log.py`, `score.py`	The scenario files, the parallel runs and the replay, the run log and the score table.	Read `Harness/scenarios/`.	Harness

Calibration#

File	What It Does	Reads and Writes	Page
`Calibration/Polaris/dynamics_replay.py`, `dynamics_fit.py`	Drive the simulated Polaris with the measured inputs of a recorded drive, and fit the model.	Read a recording. The fit gives the values of `polaris.json`.	Calibrate against Real Logs
`Calibration/Polaris/speed_envelope.py`	The stop distance, the lateral limits and the steering step of the simulated Polaris for each surface class. The envelope comes from them.	Uses ACRES Core. Writes the record of the envelope.	Speed Envelope
`Calibration/Polaris/lidar_model.py`, `lidar_compare.py`	A numpy copy of the LiDAR radiometry and its fit, and the real Helios against the simulated one.	Read real and simulated scan tables.	LiDAR
`Calibration/Polaris/camera_extrinsic.py`, `camera_evaluate.py`	The mount of the camera from a calibration bag, and the scores of the camera test.	Read real frames and renders.	Camera
`Calibration/Polaris/oxts_pose.py`, `time_base.py`, `alignment.py`	The pose of a recorded drive, one time base for its sensors, and the sensor mounts.	Read a recording, immutable.	Calibrate against Real Logs
`Calibration/Polaris/shield_scan.py`, `crop_mask_check.py`	The scan filter of the shield on a recorded drive, and the evidence for its crop mask.	Read the sensor bag of a recording.	Deployment
`Calibration/Weather/water_model_check.py`, `Calibration/Tractor/soil_weather_analysis.py`	The check of the soil-water model against public data, and the soil and weather study of the Maxxum.	Read public data and session logs.	Soil Water Check
`Calibration/Map/validate_game_layer.py`, `error_budget.py`	The validation of the surface layer, and the error budget between the real farm and the simulator.	Read the map layers.	The ACRE Scene

One Control Step, End to End#

A control step is 0.1 s. The input is the pose, the speed and the scan. The output is a curvature, a signed speed and a gear.

Before the First Step#

The planner of the library makes the plan with the exact dynamic programme on the cost tables (Runtime/Source/planner.cpp).
The plan checker (Runtime/Source/plan_check.cpp) accepts or refuses the plan. A refused plan stops the start.
The route code (Runtime/Source/route_mission.cpp) makes the legs: GoTo, Scout for each field, Return. Each leg is a path with points 1 m apart.
Runtime/Source/prepare.cpp joins the legs and makes the speed profile, the path caps and the corridor widths.
The fleet, the skill world or the vehicle handle gives the path to the default driver. It resets the launch hold and the gear.

Routes and Planner give the functions.

A Step of a Fleet in ACRES Core#

The functions are those of Runtime/Source/fleet.cpp. Fleet gives the interface.

acres_runtime_fleet_observe makes the planar scan of 360 beams and the base command of each slot at the state now.
A model can give chunks (acres_runtime_fleet_propose). The compiled Lean checker accepts or refuses each chunk.
acres_runtime_fleet_step takes the accepted chunk of a slot, or the base command of the default driver.
The launch hold can hold the speed command while the vehicle stands (Runtime/Source/command_chain.cpp).
The shield replaces a command that is not safe (Runtime/Source/shield.cpp, with the obstacle distance of corridor.cpp).
The gear logic makes the stop, the GearCmd and the hold of a gear change.
acres_runtime_command_row makes the command row of ACRES Core with the actuator clip.
FAcresBatch::Step steps the physics for 0.1 s. FAcresPolaris::Step calls StepDbw of AcresUtvModel.cpp.
The tracker of each slot updates the progress, the events, the mission automaton and the score (Runtime/Source/tracker.cpp).

A Lean proof covers the order of the launch hold, the shield and the command. Do not change it.

The Files That Define the Simulation Identity#

A result of a simulated drive is valid for one map and one set of dynamics. Two values identify them. No value is a hash of a source.

Value	Function	What Changes It
Map hash	`acres_runtime_map_hash` in `Runtime/Source/identity.cpp`	The sources and parameters of `scouting_map.json`, and its loops, entry points, transit graph and home pose.
Simulation version	`acres_runtime_sim_version`: the number of `Runtime/Reference/sim_version.txt`	Only `Runtime/Reference/refresh.sh`, when its report says that a drive changed.

A change of one of the files below can change a drive. The regression test Runtime/Tests/baseline_regression.py finds such a change. Then refresh.sh adds 1 to the simulation version. This table gives the groups.

Group	Files
Model files of the game	`Acres/Source/Acres/Model.`, `AcresSurfaceMap.`, `AcresRegionalMap.`
ACRES Core	`Core/Source/`, `Core/Python/acres_core_module.cpp`, `Core/CMakeLists.txt`, `Core/Data/`
Simulation data	The JSON and grid files of `Acres/Content/Simulation/` and of its folders `ACRE/` and `ACRE/Scouting/`, and the crop and field files of `ACRE/DriveRegion/`
Chain code	The sources of the run-time library, `Runtime/`
Configuration	The files of `Learning/acres_learn/configs/` that the library reads: `scouting_v1.json`, `control_v1.json`, `envelope_v1.json`, `scan_filter_v1.json`, `trajectory_v1.json`

A change of one of these files makes the cost tables of the cache and the recorded reference old. The level Acres/Content/Maps/V03ACRE.umap is not in the list of patterns. The tools export the scene and the crop patches of the level into files that are in the list. Identity gives the functions.