Skip to content

Build ACRES Core#

This page builds ACRES Core, runs its tests and steps one Polaris from Python. The build does not use Unreal Engine or ROS 2.

ACRES Core and the game side by side: the two simulators compile the same engine-free model sources and read the same data. The game adds the Chaos body, the renderer, the GPU sensors, the weather and the Maxxum. ACRES Core adds its own rigid body, terrain, obstacle scene, ray-cast LiDAR and batch. The Python module and core_sim use ACRES Core. Two simulators, one set of model sources THE GAME ADDS SHARED BY THE TWO SIMULATORS ACRES CORE ADDS The game (Unreal Engine) Chaos rigid body chassis integration, collisions Collision mesh ray casts for the wheel contacts Renderer and GPU sensors camera, GPU LiDAR, GNSS, INS Weather and water grid sky, rain, soil-water thread Traffic and workers farm vehicles, persons Maxxum and implements tractor, hitch, PTO Engine-free sources Vehicle and drive-by-wire AcresUtvModel AcresVehicleModel AcresSimModel Soil, tyre and energy AcresSoilModel AcresPowerModel Farm, surface and weather AcresFarmModel AcresSurfaceMap AcresEnvironmentModel Episode log writer Configuration and ACRE map compiles compiles reads reads ACRES Core (libacres_core) Rigid body of the Polaris semi-implicit Euler, 1/120 s Terrain survey triangles, exact ray casts Obstacle scene buildings, bins, trees, collisions Ray-cast LiDAR Helios pattern, planar pattern Farm state crushed crop, ruts, soil-water scenario Batch N environments, thread pool INTERFACES AND USERS Three local sockets bridge, control channel, sensor stream ROS 2 bridge sim_bridge same topics for the two simulators core_sim same sockets acres_core Python module Learners A ROS 2 node sees the same interfaces from the game and from core_sim. A learner steps thousands of Core environments from Python.
ACRES Core and the game compile the same model sources. Each simulator adds its own world layer. Open the diagram

Before You Start#

Make sure that you have the repository. Install gives the procedure. The build needs the items of this table.

Item Requirement Source
Compiler A C++20 compiler The system package of GCC or clang. The test workstation uses GCC 15.3.1.
CMake Version 3.20 or later The PATH, or the package cmake of the Python environment.
Ninja A current version The PATH, or the package ninja of the Python environment.
Python Python 3 with its header files A conda environment. The test record uses Python 3.12 and Python 3.13.
pybind11 A current version The Python environment. The build of the Python module uses it.
numpy A current version The Python environment. The Python module uses it at run time.
mcap, mcap-ros2-support A current version The Python environment. Only the Python test of the episode log uses them.

The build compiles the model sources of Acres/Source/Acres and the sources of Core/Source. It reads no asset of the game. The tests read the map products in Acres/Content/Simulation.

Note

The Python module is valid only for the Python version of the build. Build ACRES Core again when you change the Python environment.

Build and Test#

  1. Activate the Python environment.

    conda activate torchenv

  2. Install the Python packages of the build.

    python -m pip install pybind11 numpy mcap mcap-ros2-support cmake ninja

    Expected Result

    The command python -m pip list shows the six packages. The test record uses pybind11 3.1.0, numpy 2.4.4, mcap 1.5.0, cmake 4.4.3 and ninja 1.13.

  3. Build ACRES Core and run the tests. Do this step in the repository root.

    Core/build.sh

    Expected Result

    The build has 49 steps. Each test program prints its results and a summary line.

    [48/49] Linking CXX shared module acres_core.cpython-313-x86_64-linux-gnu.so
built /home/user/ACRES/Core/Build
ACRES Core world, farm, vehicle and batch tests (/home/user/ACRES)

== 1. World load (ACRE content) ==
  [PASS] world counts: 521 surface polygons, 706104 crop patches, 59 fields (47 planted), 7 places, 7073 obstacles; loaded in 0.49 s
...
35 passed, 0 failed
ACRES Core LiDAR and scene tests
...
13 passed, 0 failed
acres_core Python API tests
...
13 passed, 0 failed
PASS selftest: Core against itself through a session: speed RMSE 0.0001 m/s, end error 0.0087 m, 10 s windows p90 0.0636 m (5 windows)
PASS selftest: 585 of 585 messages after 22 hold messages, send lag max 36 ms, reset handshake seen
2 passed, 0 failed

    On the test workstation (AMD Ryzen 7 9700X, 16 threads) the build takes 6 s and the tests take 23 s.

  4. Examine the build folder.

    ls Core/Build

    Expected Result

    The folder contains the files of the table Build Products.

First Run from Python#

The Python module is the file acres_core.*.so in the build folder. Python finds it through PYTHONPATH.

  1. Write this script into the file first_core.py in the repository root.

    import numpy as np
import acres_core as ac

b = ac.Batch(".")
b.reset(None, np.array([[-38.71, -140.513, np.pi / 2, 0.0]]))   # the ICSC garage, heading north
for _ in range(50):                                               # 5 s at 0.1 s for each call
    state = b.step_curvature_speed(np.array([0.0]), np.array([3.0]))
print({name: round(float(value), 3) for name, value in zip(ac.STATE_COLUMNS[:4], state[0])})
print("speed", round(float(state[0, ac.STATE_COLUMNS.index("speed")]), 2), "m/s")

  2. Run the script with the build folder on the module path.

    PYTHONPATH=Core/Build python first_core.py

    Expected Result

    The Polaris moved 9 m to the north in 5 s.

    {'time_s': 5.0, 'x': -38.499, 'y': -131.542, 'z': 0.364}
speed 3.17 m/s

The script loads the ACRE tile, puts one Polaris at the ICSC garage and commands a speed of 3 m/s. Each call of step_curvature_speed advances the simulation by 0.1 s, that is 12 physics steps. The first argument of Batch is the repository root. The module reads the configuration and the map from this folder. Python API gives all functions and all array columns.

Options of the Build#

Name Type Unit Default Description
--no-tests flag off Builds only. The script does not run the tests.
BUILD_DIR environment variable Core/Build The folder of the build products.
PYTHON environment variable python3 on the PATH The interpreter of the Python module and of the Python tests.
ACRES_CORE_PYTHON CMake option ON OFF builds the libraries, the tests and the tools without the Python module.
CMAKE_BUILD_TYPE CMake variable Release The build type. The sources compile with -O2.

The script uses cmake and ninja from the PATH. When the PATH does not contain them, the script uses the programs in the folder of the Python interpreter.

BUILD_DIR=/tmp/core-build PYTHON=$HOME/miniconda3/envs/torchenv/bin/python Core/build.sh --no-tests

Build Products#

File Function
libacres_core.so The shared library for C++ programs.
libacres_core_static.a The static library. The tests, the tools and the Python module link it.
acres_core.cpython-<version>-x86_64-linux-gnu.so The Python module acres_core.
core_tests The tests of the world, the farm, the Polaris, the batch and the episode log.
lidar_tests The tests of the terrain ray casts, the obstacle scene and the LiDAR.
core_replay A tool that replays a recorded drive-by-wire log through ACRES Core.
lidar_compare A tool that makes LiDAR scans at a list of poses.

C++ API gives the libraries, the tools and the scripts in Core/Scripts.

Tests#

Core/build.sh runs four test programs. A failed check makes the exit code of the script 1.

Program Checks Scope
Core/Build/core_tests 35 The world, the terrain, the surfaces, the soil water, the crop marks, the Polaris, the energy ledger, the batch, the collisions and the episode log.
Core/Build/lidar_tests 13 The terrain ray casts, the obstacle scene, the Helios pattern, the planar pattern and the scan rate.
Core/Tests/test_core.py 13 The Python module: the array shapes, the commands, the LiDAR, the soil water, the parameters, the zones and the episode log.
Core/Tests/test_harness.py 2 The scripts that compare ACRES Core with the game. The test uses a substitute for the game.

Run one test program alone with the repository root as its argument.

Core/Build/core_tests --root .
PYTHONPATH=Core/Build python Core/Tests/test_core.py --root .

Problems#

Message Cause Correction
pybind11 not found for <python>: pip install pybind11 The Python environment has no pybind11. Do step 2 of the build again in the environment of PYTHON.
Could NOT find Python3 (missing: Python3_INCLUDE_DIRS Development.Module) The Python interpreter has no header files. A system Python without its development package gives this error. Use the Python of a conda environment.
Core/build.sh: line 22: .../cmake: No such file or directory CMake is not on the PATH and not in the Python environment. Install the packages cmake and ninja into the Python environment.
ModuleNotFoundError: No module named 'acres_core' PYTHONPATH does not contain the build folder, or the Python version is different from the build. Set PYTHONPATH=Core/Build. Use the interpreter of the build.
RuntimeError: acres_core: cannot read .../Acres/Content/Simulation/tractor.json The first argument of Batch is not the repository root. Give the path of the repository root.

Next Steps#