Skip to content

What Is ACRES#

ACRES is a simulator of farm vehicles on a surveyed part of the Purdue ACRE farm. It has two simulators, a run-time library and Python packages that you use from your own code.

The parts of ACRES: your code calls the Python packages; acres_harness and acres_simulator use the run-time library, which contains ACRES Core; acres_core is one physics world in Python; the Unreal game connects to ROS 2 through acres_sim; the two simulators share the model sources, the map products and the configuration files. The parts of ACRES and how they connect YOUR CODE Python scripts and notebooks drive, record, evaluate Planners and learned models propose paths and commands ROS 2 nodes the topics of the real vehicle PYTHON PACKAGES acres_harness scenarios and missions runner, scores, replay recovery and plugins acres_simulator Core, Fleet, Skills plans, routes, maps scan of the shield acres_core one physics world in Python: step, LiDAR, episode log acres_learn configuration files map products, builder readers of recordings SIMULATORS Run-time library libacres_runtime: missions, routes, planner, shield, checker, skills ACRES Core inside, many slots ACRES Core C++ physics without Unreal Polaris, terrain, soil, crops ray-cast LiDAR, INS, wheels Unreal game Unreal Engine 5.8, 120 Hz physics Maxxum, implements, weather, camera and GPU LiDAR SHARED BY THE SIMULATORS Engine-free model sources Acres/Source/Acres: one set of equations Map products and configuration files Acres/Content/Simulation, SimulationMaps, acres_learn configs acres_sim
Your code calls the Python packages. acres_harness and acres_simulator use the run-time library, which contains ACRES Core. The Unreal game connects to ROS 2. Open the diagram

The Parts#

Part Location Use
Unreal game Acres/ The full simulator with a window: the Maxxum tractor, the eight implements, the Polaris Ranger, the weather, the camera and the GPU LiDAR.
ACRES Core Core/ The simulator without Unreal Engine. It steps many Polaris worlds in parallel on the CPU.
Run-time library Runtime/ The missions, the routes, the planner, the shield, the trajectory checker and the skills. It contains ACRES Core.
acres_core Core/Build The Python module of one ACRES Core world: step, LiDAR, episode log.
acres_simulator Simulator/ The Python package of the run-time library: fleets of vehicles, missions, skills and routes.
acres_harness Harness/ Scenarios, the mission runner, the scores, the replay and the recovery modes.
acres_learn Learning/ The configuration files, the map products with their builder, and the readers of recordings.
ROS 2 workspace ROS/ The bridges acres_sim (the game) and acres_core_sim (ACRES Core) with the topics of the real vehicle.

The game and ACRES Core compile the same model sources in Acres/Source/Acres. Thus the two simulators use one set of equations. Architecture gives the threads, the layers and the data flow.

What You Can Do#

  • Drive a vehicle

    Drive the Polaris or the Maxxum with the keyboard, or command them from code.

  • Collect data

    Record the camera, the LiDAR, the GNSS, the IMU and the CAN bus, with the ground truth.

  • Replay a drive

    Drive a recorded session again, or show an episode log in the game.

  • Run thousands of missions

    Step many vehicles in parallel from Python with ACRES Core and the run-time library.

Two Ways to Use ACRES#

Path You Get You Need
Python only ACRES Core, the run-time library, acres_simulator, acres_harness. No window, many vehicles in parallel. Linux, a C++20 compiler, Python 3.12 or 3.13, Git LFS. No GPU.
Full game The Unreal game with all vehicles, implements and sensors, and a window or offscreen rendering. The Python path, plus Unreal Engine 5.8 and an NVIDIA GPU with Vulkan.

Install gives the procedure for each path.

Platforms#

Platform Graphics Status
Linux, 64 bit Vulkan, shader model 6 Built, packaged and tested. All commands of this documentation are Linux commands.
Windows DirectX 12, shader model 6 The project has the settings. This documentation has no Windows procedure.
macOS Metal, shader model 6 The project has the settings. No build exists.

The CAN transport of the vehicle bridge (SocketCAN) and the ROS 2 workspace operate only on Linux.

Render Tiers and the GPU#

The game selects a render tier from the GPU memory at the start of a session. The sensors use a fixed sensor profile, so a dataset does not change with the computer.

Render tiers: the dedicated GPU memory selects the low tier or the high tier, each tier sets the main view, and a recording camera or LiDAR pins the render state to a sensor profile, which the datasets name in the label sensor_profile. TIER SELECTION AT THE START OF A SESSION GPU memory dedicated memory from the RHI, in MiB Tier selection 11 776 MiB or more: high tier less than 11 776 MiB: low tier Option -RenderTier=low|high replaces the selection low high Low tier render state when no sensor records main view at 60 % resolution, TSR to the output size anti-aliasing, shadow, post-process, effects: level 2 global illumination and reflection: level 1 surface cache 2048, shadow pool 2048 pages Nanite 4 pixels for each edge, mesh LOD scale 2 cloud shadow map 128, leaf masks to 60 m High tier render state when no sensor records main view at 100 % resolution, TSR anti-aliasing all scalability groups: level 3 full Lumen global illumination and reflections surface cache 8192, shadow pool 4096 pages Nanite 1 pixel for each edge, mesh LOD scale 1 cloud shadow map 2048, authored leaf masks while a camera or a LiDAR records while a camera or a LiDAR records Sensor profile reduced-6gb the calibrated list with: surface cache 2048, texture pool 2048 MiB, shadow pool 2048 pages, radiance cache 16 texels for each probe also on the high tier with -SensorRenderProfile=reduced Sensor profile calibrated the render state of the Polaris camera and LiDAR validation, the same list as the high tier also on the low tier with -SensorRenderProfile=calibrated Label sensor_profile in episode.json and in the episode log polaris-calibrated · polaris-reduced-6gb · tractor-default · tractor-default-reduced-6gb · custom
The GPU memory selects the render tier. A recording camera or LiDAR pins the render state to a sensor profile. Open the diagram
GPU Memory Render Tier Sensor Profile
Less than 11 776 MiB low reduced-6gb
11 776 MiB or more high calibrated
  • The option -RenderTier=low or -RenderTier=high replaces the selection.
  • The option -SensorRenderProfile=calibrated or -SensorRenderProfile=reduced replaces the sensor profile.
  • Without hardware ray tracing, the LiDAR uses its CPU path. The option -SensorCpuLidar selects the CPU path on all computers.

Run the Game gives the settings of each tier and the dataset labels.

Speed#

ACRES Core has no renderer. Core/Scripts/bench.py measures its speed with 64 Polaris worlds on the ACRE tile.

PYTHONPATH=Core/Build python Core/Scripts/bench.py --envs 64 --seconds 20
Measurement Result on an 8-core CPU
Physics with soil and crops, 1 thread 547 times real time
Physics with soil and crops, 16 threads 3000 times real time
Polaris LiDAR scans (57 600 beams), 16 threads 687 scans each second

The game keeps a physics rate of 120 Hz. The frame rate depends on the tier and the sensors.

Tier Vehicle and Sensors Frame Rate Peak GPU Memory
Low Polaris, no sensors 82 Hz 4610 MiB
Low Polaris, camera and LiDAR 35 Hz 5708 MiB
High Polaris, no sensors 36 Hz 8237 MiB
High Polaris, camera and LiDAR 21 Hz 10 603 MiB

The frame rates come from Tools/Performance/benchmark_linux.py at 1920 x 1080 on an NVIDIA GeForce RTX 5060 Ti with 16 GB.

Next Steps#

  • Install

    Get the code and build the Python path or the full game.

  • Quickstart

    Drive a Polaris from Python in five minutes, then run a mission.

  • Keyboard and Mouse Controls

    All keys of the game: driving, implements, cameras, recording and replay.