Skip to content

Run-Time Library Overview#

acres_runtime is the compiled library of the vehicle software of ACRES. It has the planner, the routes, the command chain, the shield, the checker and the skills. The same library runs in ACRES Core, in the game and in the ROS 2 vehicle node.

Before you start

Headers#

The public headers are in Runtime/Include/acres_runtime/. The page C++ Headers has the generated text of each declaration.

Header Content Page
api.h, types.h Status codes, versions, the fleet, the tracker, the chunks and the command records Fleet, Skills and Routes
skills.h, scenario.h, proposed.h, training.h The skill world, the other actors, learned skills and the training view Fleet, Skills and Routes
routes.h Prepared paths from the scouting map and a plan Fleet, Skills and Routes
planner.h, baseline.h Cost tables, the exact program, the plan checker and the batch baseline Planner and Cost Tables
vehicle.h, proposal.h, sensors.h One vehicle with inputs from outside, model proposals and the scan filter Vehicle Handle and Sensors
game.h The client of the game channels Game Link on this page
identity.h The map hash and the simulation version acres_simulator: Identity
tools.h Getters for the tools of the repository acres_simulator: Plans and Routes
parallel.h, rt_math.h The thread pool of the process and the math functions Rules on this page

Rules#

The C interface follows these rules:

  • Each function that can fail returns an AcresRtStatus. No function throws an exception.
  • After a status that is not ACRES_RT_OK, acres_runtime_last_error() gives a sentence for the thread of the call.
  • The structures are plain data. acres_runtime_struct_sizes gives the size of each structure, for a check of the caller.
  • acres_runtime_abi_version() gives ACRES_RT_ABI_VERSION of the library. Compare it with the value of your headers.
Status Value Meaning
ACRES_RT_OK 0 The call is complete.
ACRES_RT_ERROR_ARGUMENT 1 A null pointer, a size or an index that is not usable.
ACRES_RT_ERROR_NOT_IMPLEMENTED 2 The function or the option is not available.
ACRES_RT_ERROR_LOAD 3 A file of the world or of the configuration did not load.
ACRES_RT_ERROR_BUSY 4 The process has a fleet or a skill world already.
ACRES_RT_ERROR_STATE 5 The call is not permitted in the state of the handle.
ACRES_RT_ERROR_INTERNAL 6 An error of the library.

Threads and Equal Results#

A process has one thread pool. A fleet or a skill world owns it. A route handle with threads above 0 owns it when the process has no fleet. acres_runtime_thread_count() gives its size.

  • A parallel loop gives one task to each slot, mission or sweep. A task writes only its own values.
  • No sum crosses tasks. Thus a result has the same bits for each number of threads.
  • A step that needs the result of the step before it is serial.
  • The math functions that are not correctly rounded in each C library go through rt_math.h. Thus two builds give the same numbers.

Build Options#

Variable of Runtime/build.sh Default Function
BUILD_DIR Runtime/Build The build folder
PYTHON python3 on the PATH The interpreter of the Python module _acres_runtime. It needs pybind11.
ACRES_RUNTIME_JOBS 3 The compile jobs and the test jobs
ACRES_RUNTIME_LEAN 0 generated builds the checker plug-in from Runtime/Lean/Generated. 1 builds it with the Lean tool chain of Verification/.
ACRES_RUNTIME_STRICT 0 1 makes a skipped test a failure.

Runtime/build.sh --no-tests builds only. --all runs each test. --label <L> runs the tests of one label. The page Testing has the test tiers.

The library drives the packaged game, or the ACRES Core server core_sim, through two local channels on 127.0.0.1:

The vehicle handle drives a mission through this client in lockstep. One control step has this order:

  1. The client reads the pose (get_entity_state) and the last drive-by-wire report.
  2. The vehicle handle makes the control step: the default driver, the launch hold, the shield and the gear logic.
  3. The client sends SteeringCmd (curvature), UlcCmd (velocity) and, when the step has one, GearCmd.
  4. The client asks for 12 physics steps (0.1 s) and waits for the barrier of the bridge.

The client holds the simulator between the control steps. Thus one program drives the game and ACRES Core, and a run gives the same numbers each time.

Note

The control channel has no LiDAR scan. The shield then gets a free scan (40 m in each beam). A mission with objects needs the LiDAR scan. Use the ROS 2 bridge and the Vehicle Node for it.

Function of game.h Use
acres_runtime_game_connect, acres_runtime_game_close The client of one vehicle. It connects to 127.0.0.1 only.
acres_runtime_game_call One request of the control channel as a JSON object. The reply is a JSON line.
acres_runtime_game_send, acres_runtime_game_ok One message on the bridge, and the check of a reply.
acres_runtime_game_state The pose, the speed, the yaw rate and the report of the vehicle.
acres_runtime_game_advance, acres_runtime_game_barriers Physics steps in lockstep, to the barrier of the bridge.
acres_runtime_game_inputs, acres_runtime_game_command, acres_runtime_game_command_text The inputs of a control step from a state, and the commands of a step on the bridge.
acres_runtime_game_drive, acres_runtime_game_drive_options_default One mission from a world reset to its end, with the episode log and a trace.
acres_runtime_log_measures The fuel, the ground loss and the path length of an agent in an episode log.

The program acres_runtime_game_crosscheck uses these functions. These tools start it:

Tool Use
Tools/SimControl/game_crosscheck.py Drives single-field missions in core_sim and in the game, then compares the results.
Tools/SimControl/crosscheck_missions.py The same with the regional ground and the measures of the two episode logs.
Tools/SimControl/crosscheck_objects.py One mission with an object of a scenario file.
Tools/SimControl/check_reset_ruts.py Two drives in one game, with a reset between them.
Tools/SimControl/check_planner_support.py The skill list, the clock, the observation, the events and the episode log of the game. 
python Tools/SimControl/game_crosscheck.py --fields F53,F42 --out <folder>

The result is <folder>/crosscheck.json and a table. Two results are equal when the success, the stop findings and the order of the milestones are equal. The table gives the other measures as differences.