Recorded Reference

The recorded reference is a record of the compiled command chain on a known commit. It has the inputs and outputs of each unit of the chain in each control step. The tests of Runtime/Tests and the regression read it. This page gives its format and the procedure after a change of the chain.

Before you start

• The record is not in Git. Its default folder is Acres/Saved/work/runtime-reference/.
• A test that needs the record skips (exit code 77) when the folder is not there.

Sets

Each mission is recorded in its own batch of ACRES Core with one environment and one thread.

Set	Missions	Content
S	12 missions of the acceptance run on the validation fields (configs/splits_v1.json)	Each control step with all unit inputs and outputs, the planar scan and the ACRES Core state row
F	The missions of the acceptance run (default driver, condition set dry, grip level unknown)	Each control step without the scan and the state row
R	The single-field missions in the condition sets dry, wet and shift	The summary, the trace and the path of each mission. The commands of 12 missions.

The acceptance run is the full command chain: the default driver, the launch hold, the shield and the gear logic. The missions of set R have the default driver and the gear logic.

Format

The file manifest.json has the schema acres-runtime-reference-1:

Key	Content
identity	The map hash, the simulation version, the scan of the shield (shield_scan: planar or sweep) and the reference identity
commit	The Git commit of the recorder
codes	The numbers of the failures, skills, phases and event bits, and the scan materials that are not obstacles
sets	For each set, the number of missions, control steps and bytes
files	One entry for each binary file

An entry of files has the keys set, mission, condition, fields, steps, plan, summary, sha256, bytes, arrays and columns. arrays gives the type, the shape and the byte offset of each array. columns gives the column names of a two-dimensional array.

One binary file has the arrays of one mission, one after the other:

• An array starts at a multiple of 64 bytes. The bytes between two arrays are zero.
• An array is in C order, little endian.
• The types are float64, float32, int64, int32, uint8 and bool.
• A file has no time and no machine name. Two records of one mission and one identity are equal byte for byte.

The Python reader is Runtime/Reference/reference_format.py (Reference). The C++ reader is Runtime/Tests/harness.h (FReference).

from reference_format import Reference

ref = Reference("Acres/Saved/work/runtime-reference")
f = ref.load("S/single-F56.bin")
f["state"].shape, f.entry["steps"], f.column("command", "ulc_mps")

Arrays of a Control Step

Row t of each array is control step t. Set F has the arrays with "Yes" in the last column.

Array	Shape	Content	F
pose	(T, 4)	x, y, yaw and forward speed before the step	Yes
state	(T, 49)	The ACRES Core state row before the step	No
state_after, wheels_after, energy_step, zone_step	(T, 49), (T, 4, 13), (T, 24), (T, 6)	The ACRES Core arrays after the step	No
scan_raw, scan_material, scan_ranges, shield_scan	(T, 360)	The planar scan and its hit codes, the scan after the range limit, and the scan of the shield	No
base_in, driver_before, driver_after, base	(T, 4), (T, 5), (T, 5), (T, 3)	The default driver: input, state before and after, and the base command	Yes
projection_in, projection	(T, 6), (T, 7)	The tracker projection before the command	Yes
gear_before, gear_after	(T, 4)	The state of the launch hold and of the gear logic	Yes
shield_limits, obstacle_m, shield_out	(T, 4), (T, 5), (T, 4)	The class limits, the obstacle distances, and the shield output	Yes
command, command_rows	(T, 13), (T, 18)	The command and the command row to ACRES Core	Yes
tracker_in, tracker_out, coverage	(T, 19), (T, 35), (T, fields)	The tracker arguments, its state after the step, and the coverage of each field	Yes
tracks, returned, scouted	(T, legs, 3), (T, fields)	The progress of each leg and the flags of each field	No

A distance of obstacle_m that the chain did not measure is NaN. A distance with no return is inf.

Arrays of a Mission

Array	Content
path_xy, path_s, path_v_max, path_direction, path_cls, path_leg, path_ends	The joined path
path_speeds, path_caps, path_limits, path_curvature, path_first	The prepared products of the path
leg_first_point, leg_skill, leg_field, leg_uturns	The legs. Leg k has the points leg_first_point[k] to leg_first_point[k + 1] - 1.
leg_xy, leg_s, leg_v_max, leg_direction, leg_cls, leg_corridor	The points of the legs, with the corridor half widths
field_first_checkpoint, checkpoints_xy, home, bounds	The map data of the tracker
covered_step	The control step in which each checkpoint was covered first, or -1

A file of set R has trace (T, 9): the time, x, y, yaw, speed, leg, cross-track error, crop and gear changes. Twelve missions also have commands (T, 3): the curvature, the ULC velocity and the gear.

Record the Reference

The program acres_runtime_record_reference (Runtime/Tools/record_reference.cpp) writes the record.

Runtime/Build/acres_runtime_record_reference --root . --out <folder> --threads 8 --commit $(git rev-parse HEAD)

Option	Function
--sets S,F,R	The sets to write. The default is each set.
--fields F56,F04	Only the missions of these fields
--tables <folder>	Read the cost tables there. By default the program drives the tables into <folder>/costs.
--commit <text>	The value of the key commit of the manifest

The program uses the plans and paths of acres_runtime_baseline_run. A mission of set S is written two times from one drive: with the scan in set S, and without it in set F. Two records of one tree are equal byte for byte, also with different numbers of threads.

After a Change of the Chain

A change of the chain changes the drives. The tests with the record and the regression then fail. One command makes each reference again and sets the simulation version.

1. Commit the change of the chain. The script refuses a working tree with changes that are not committed.

2. Run the refresh:

   PYTHON=<python> BUILD_DIR=<build folder> Runtime/Reference/refresh.sh
   

3. Commit the new golden file and the simulation version:

   git add Runtime/Tests/baseline_golden.json Runtime/Reference/sim_version.txt
   git commit
   

The script does these steps:

1. It writes the next number into Runtime/Reference/sim_version.txt and builds the library with it.
2. It records sets S, F and R into <reference>.new.
3. It prints the change against the old record (Runtime/Reference/compare_reference.py).
4. It drives a short baseline with the new cost tables and prints the regression against the old golden file.
5. It makes the references of the vehicle node (ROS/acres_vehicle/scripts/node_reference.sh). The option --no-node skips this step.
6. When a drive changed, it replaces the record and the golden file, and the cache gets the new cost tables. Else it writes the old number back and replaces nothing.

Line of the Report	Effect
A DRIVE OR SENSOR INPUT CHANGED: the simulation version 1 becomes 2	The new number is in the cost tables, the record, the golden file and the library. Commit sim_version.txt and the golden file.
NO DRIVE CHANGED: the simulation version stays 1	Nothing is replaced. The cost tables and each data set stay valid.

Option	Function
--report-only	Makes the new references and prints the reports. It replaces nothing and keeps the number.
--sensor-change	Use it after a change of the simulated sensor inputs when the drives stay inside the margins. It replaces the recorded scans and raises the simulation version.
--no-node	Skips the references of the vehicle node.

Warning

No hash of the sources protects a cost table or a data set. The regression test Runtime/Tests/baseline_regression.py is the guard. It fails when a drive changed and nobody ran the refresh.

Rules of the Interface

The C headers are in Runtime/Include/acres_runtime. The current ABI version is 3. It is separate from the release number and the simulation version.

• Keep the public function names, arguments and meanings compatible.
• Keep the structure layouts compatible with the declared ABI.
• A breaking change of the interface needs a new ABI version.
• The functions of Runtime/Source/internal.h are not a part of the interface. The library exports them for its tests.