Fleet, Skills and Routes

This page is the reference of three parts of the run-time library acres_runtime:

• The fleet drives many prepared missions on one batch of ACRES Core, with model chunks or with the default driver.
• The skill world drives vehicles through skills (goto, scout, return_home, wait) with objects on the path.
• The routes make the prepared path of a mission from the scouting map and a plan.

The Python interface of the three parts is acres_simulator. The rules of the C interface are in Run-Time Library Overview.

Fleet

A fleet has one batch of ACRES Core with N environments. One environment is one slot. A slot has a mission, the state of the command chain, the tracker of the mission and a ring of the last scans. The source is Runtime/Source/fleet.cpp.

Control Step

acres_runtime_fleet_step makes one control step of each slot in four parts:

Part	Work	Content
1	One task for each slot	The scan, the base command, the tracker projection, and the command chain or a recorded command
2	One task for each environment	The physics step of ACRES Core
3	One task for each slot	The step numbers, the energy floor and the tracker
4	Serial	The scores of the missions that ended, and the next missions of the queue

The launch hold, the shield and the gear logic run in this order inside the task of a slot. Part 4 is serial, thus the slot of a mission does not depend on the threads.

Queue

Function	Function
acres_runtime_fleet_load	Copies the missions and replaces the queue. A mission that runs is stopped and has no score.
acres_runtime_fleet_append	Adds missions to the end of the queue. A free slot takes a new mission at the next step.
acres_runtime_fleet_reset	Puts the first missions into the slots.
acres_runtime_fleet_set_order	ACRES_RT_ORDER_QUEUE, or ACRES_RT_ORDER_LONGEST_FIRST (by the reference time time_ref_s).
acres_runtime_fleet_missions	The mission of each slot.

The score of mission k of the queue has the index k for each order, each number of threads and each number of slots.

Conditions and Slots

Each environment can have its own condition set (dry, wet, shift). A mission start sets the soil water and the Polaris parameters of its slot, and resets the environment to the home pose.

The physics does not depend on the slot: a mission gives the same state rows in each slot. The planar scan of ACRES Core draws tree-crown returns from a hash of the environment. The fleet gives the seed (slot << 32) ^ mission seed to the scan, thus the scan of a mission depends on the mission only.

Command Source

acres_runtime_fleet_set_chain selects the command chain:

• ACRES_RT_CHAIN_FULL: the default driver, the launch hold, the shield and the gear logic.
• ACRES_RT_CHAIN_DRIVER: the default driver and the gear logic.

Chunks

A caller proposes chunks with acres_runtime_fleet_propose. A chunk (AcresRtChunk) is a side offset from the mission path and a speed at up to 64 stations of the path.

1. The chunks of one slot are checked in one task, in the order of the call.
2. The compiled Lean checker decides each chunk (acres_runtime_check_chunks). It reads the trajectory limits, the corridor of the active leg, the pose and the newest scan.
3. The first accepted chunk of a slot drives its next control step. Give your chunks in the order of your preference.
4. The command of the chunk goes through the command chain. The launch hold, the shield and the gear logic stay in their order.

The speed command is the chunk speed one sample ahead of the vehicle. The curvature command is the arc from the vehicle to the chunk point at the look-ahead distance of the default driver. A chunk drives one control step.

The default driver drives a slot in these cases:

• The checker accepts no chunk of the slot. The verdict gives the first failed rule with its index, point, value and limit.
• The answer is late (ACRES_RT_REASON_LATE): deadline_s is before the state time, or the wall time of acres_runtime_fleet_set_deadline ended.
• No checker is loaded (ACRES_RT_REASON_NO_CHECKER).

acres_runtime_fleet_default_chunk gives a start value: the chunk of the default driver from the vehicle pose. acres_runtime_fleet_observe gives the state rows, the scans, the projection, the base command, the ground limits and the corridor of the active leg.

Tracker

The tracker follows one vehicle through its mission and gives its score. It keeps the progress of each leg, the covered checkpoints and the milestones. It also keeps the stuck timer, the failure tests, the mission automaton and the totals. The source is Runtime/Source/tracker.cpp.

Function of api.h	Function
acres_runtime_tracker_create	Copies the legs, the field checkpoints, the home pose and the bounds, and starts an episode.
acres_runtime_tracker_project	The projection onto the active leg before the command.
acres_runtime_tracker_step	One control step after the physics step.
acres_runtime_tracker_score	The totals, the interventions, the rule counts, the phases and the cross-track statistics.

The tracker reads four map quantities from ACRES Core (Runtime/Source/scouting_world.cpp):

Input	Source in ACRES Core
mean_slip	The mean slip of the driven wheels (FAcresBatch::Wheels)
nearest_m	FAcresScene::NearestObstacleM(x, y, 30)
depth_in_crop_m	FAcresWorld::ZoneAt at the cell centres of a disc
crop_on_share	FAcresWorld::ZoneAt at 45 points of the plan box

Fleet Functions

Function of api.h	Function
acres_runtime_fleet_create, _destroy, _configure	The world, the batch with its thread pool, the configuration
acres_runtime_fleet_set_chain, _set_order, _set_condition, _set_grip	The command chain, the order, the condition set and the grip level
acres_runtime_fleet_load, _append, _reset	The queue
acres_runtime_fleet_observe, _state, _missions	Read-only views of the library memory
acres_runtime_fleet_default_chunk, _propose, _set_deadline	The chunks
acres_runtime_fleet_step, _run, _running	The control steps
acres_runtime_fleet_scores, _timing, _content_dir	The scores, the timing and the content folder

Runtime/Source/package_b.h is a test interface (recorded commands, the tap of each step). Do not use it outside Runtime/.

Skills

A skill world is one batch of ACRES Core with its slots. One slot is one vehicle with its own clock, objects, mission plan, events and results. The sources are Runtime/Source/skills.cpp, skill_slot.h and object_scripts.cpp.

• Clock. The mission time of a slot is the number of its control steps since its reset, times 0.1 s.
• One pool. A skill world owns the thread pool of the process. A process has one fleet or one skill world at a time.
• Equal results. One task writes one slot, thus 1 thread and 8 threads give the same bits.

Control Step

acres_runtime_skills_step makes these parts in each control step:

1. One task for each slot makes its command. A driving skill makes the control step of the mission. Each other step sends a stop.
2. ACRES Core steps the physics of all environments.
3. One task for each slot adds the truth values and runs the scripts of its objects.

A driving skill makes its command in this order:

1. The tracker goes to the pose that the last command gave.
2. The default driver gives the base command.
3. The tracker projects the pose onto the path.
4. The command chain applies the launch hold, the shield with the scan, and the gear logic.
5. The speed cap of the run decreases the speed command.
6. The skill server examines the shield hold, the end of the leg and the end of the mission.

Each command of a driving skill comes from the command chain. The code after it can only decrease the speed or send a stop.

Scan of the Shield

The shield reads a planar scan of 360 beams (AcresRtScan). corridor.scan_source of control_v1.json sets how the simulator makes it. The skill world and the fleet use the same code (Runtime/Source/shield_sweep.h).

scan_source	Scan	Time of a Control Step
sweep (default)	The simulated Helios sweep (1800 columns x 32 rings, with the vehicle motion) through the scan filter of the vehicle (scan_filter_v1.json: local ground, height band 0.3 m to 2.5 m, body mask).	20 ms to 30 ms for each slot
planar	The planar ring of ACRES Core at the LiDAR mount height (2.05 m). A thing lower than the mount gives no return: a parked car, a wall, a bin, a post.	below 1 ms

corridor.scan_crops adds the crops and the ground cover of ACRES Core to the sweep. The default is off, because the simulated crop is not calibrated against the vehicle. With it on, a crop row in the corridor holds the vehicle.

The option shield_scan selects the source for one world: world.shield_scan of AcresRtSkillsOptions, shield_scan of AcresRtFleetOptions, and shield_scan="config" | "planar" | "sweep" in Python. With no choice of the caller, the variable ACRES_RUNTIME_SHIELD_SCAN (planar or sweep) selects it, else the file.

At 2,468 poses of a recorded drive, the simulator missed this share of the near beams ahead where the vehicle saw a thing:

Beams Ahead within 10 m	planar	sweep
All	84 %	71 %
In yards and lots	90 %	2 %

The rest are things that the map does not have: signs on posts, vegetation and the crops of the day. The comparison tool is Calibration/Polaris/shield_sim2real.py.

Skills and Result Codes

Skill	Arguments	Function
goto	place, speed_cap_mps	Go to the entry of a field, or to H.
scout	field, speed_cap_mps	Go to the entry of a field if necessary, then drive its Scout loop.
return_home	speed_cap_mps	Go to H and stop there.
wait	seconds	Stand for a mission time.
stop		Stop the vehicle. The skill that runs ends with stopped.
continue		Continue the skill that ended with stopped or blocked.

goto, scout and return_home are windows on the legs of one mission plan. The next skill continues the plan if it is the next leg. Else the library makes a new plan from the pose.

Code	Meaning
done	The skill is complete.
blocked	The shield held the vehicle at a stop for blocked_s (10 s).
refused_plan	The plan checker refused the plan.
refused_limit	A limit refused the mission or an option.
refused_request	The request is not valid.
stopped	The skill stop ended the skill.
failed	The task failed, or the driver gave an error.

The result of blocked has a counterexample. It gives the shield rules in the last step of the hold, the obstacle distance, the hold time and the stop pose.

The events are those of the schema Learning/acres_learn/interface/schemas/skills_v1.json: skill_started, skill_ended, plan_refused, limit_refused, shield_hold, blocked, object_seen and mission_complete.

After blocked, a planner has two answers:

• Wait. Send wait, then continue. When the object is gone, the command chain starts the vehicle again.
• A different route. Send a new driving skill. The plan from the pose can start with a straight reverse stretch of 1 m to 8 m. This occurs when the scan has a return nearer than 10 m ahead and the obstacle rule acts on the first command.

Objects on the Path

A slot has objects in one of two forms:

Form	Call	Function
Rows	acres_runtime_skills_set_objects	Each row has kind, x, y, yaw, length_m, width_m, height_m, vx, vy. The caller changes the rows.
Scenario	acres_runtime_skills_set_scenario	Objects with scripts (acres-path-scenario-1). The library runs the scripts after each control step.

Script	Motion
static	The object stands for the full episode.
temporary	A clock starts when the vehicle is near. After leave_s the object moves aside and goes after clear_m.
crossing	The object starts when the vehicle has trigger_m of path to the place. It goes across the path.
along	The object moves along its leg, with the vehicle or against it. Against the vehicle it stops at gap_m, waits and leaves.
walk, stand, emerge	A person walks along the lane, stands on the lane, or comes out from behind a parked machine.
headland, back_out, lead, pull_out	A tractor turns across the lane, a truck backs out of a yard, a vehicle drives ahead at a lower speed, a parked vehicle starts.

An object with reactive 1 gives way to the vehicle. ACRES Core tests the contact of the plan box with each object. A contact that starts during a driving skill ends the skill with failed, and the cause names the object.

Each contact has a class that tells who moved into whom: vehicle, actor, both or rest (acres_runtime_contact_class). The observation has contact_class, class_count and class_steps.

Skill Functions

Function of skills.h	Use
acres_runtime_skills_options_default, _create, _destroy	The skill world from AcresRtSkillsOptions: the world, the speed cap, blocked_s, shield_scan
acres_runtime_skills_reset	A new episode of one slot at a pose, in a condition set
acres_runtime_skills_set_objects, _set_scenario, _scenario	The objects of a slot
acres_runtime_skills_request, _route, _route_refused, _refuse	A request, its route, and a refusal
acres_runtime_skills_step, _run	Control steps of all slots. _run steps until a skill of a slot ends.
acres_runtime_skills_active, _result, _events, _observe	The skill, its result, the events and the observation of a slot
acres_runtime_skills_state, _scan	The state rows of ACRES Core and the scan of the shield
acres_runtime_skills_start_log, _stop_log, _flush_log	The episode log of a slot: an MCAP file that the game can replay
acres_runtime_back_off	The length of the reverse stretch from a scan

Header	Functions
proposed.h	Learned skills: acres_runtime_proposed_load, acres_runtime_proposer_vector, acres_runtime_proposer_chunk, acres_runtime_skills_request_proposed, acres_runtime_skills_propose, acres_runtime_skills_signal, acres_runtime_skills_proposed_stats, acres_runtime_skills_proposer_observe and the acres_runtime_vehicle_skill_* and acres_runtime_vehicle_proposed_* forms
training.h	The training view: acres_runtime_training_create, _destroy, _view, _reset, _observe, _propose, _step, _rows, _episode_default, _timing
scenario.h	Other actors: acres_runtime_scenario_generate, _view, _free, _run_create, _run_step, _run_objects, _run_rows, _run_destroy, the name functions, and acres_runtime_contact_class

The tutorial Use acres_learn uses the learned skills and the training view.

Routes

The routes make the prepared path of a mission from the scouting map and a plan. The header is Runtime/Include/acres_runtime/routes.h.

AcresRtRouteOptions options;
acres_runtime_route_options_default(&options);
options.root = "/path/to/ACRES";
options.threads = 8;
AcresRtRoutes* routes = NULL;
acres_runtime_routes_create(&options, &routes);

AcresRtRouteRequest request = {0};
request.plan = &plan;                 /* AcresRtMissionPlan: field, entry, clockwise, access, exit */
request.edge_cost = cost;             /* one value for each directed edge; NULL: the lengths */
request.edge_cost_count = count;
request.uturn_penalty = uturn;        /* NaN: 500 */
request.reverse = 1;
AcresRtRouteResult* result = NULL;
acres_runtime_routes_plan(routes, &request, 1, &result);

AcresRtPreparedPath path;
AcresRtRouteInfo info;
acres_runtime_route_result(result, &path, &info);
acres_runtime_routes_destroy(routes);   /* before a fleet starts */
acres_runtime_route_result_destroy(result);

A result owns its arrays. It stays valid after you destroy the handle.

Function of routes.h	Function
acres_runtime_route_options_default, acres_runtime_routes_create	Reads the map and the configuration files and makes the network
acres_runtime_routes_size, _field, _home, _field_shape, _bounds	The map: edge and field counts, one field, the home pose, the field outline and Scout loop, the bounds
acres_runtime_routes_lanes, _lane, _scan_frame, _object_kinds, _object_kind	The transit graph, the frame of the shield scan, and the object kinds of path_objects_v1.json
acres_runtime_routes_plan	Makes the prepared path of each request of a batch
acres_runtime_route_result, _destroy, acres_runtime_routes_destroy	The prepared path of a result, and the release of a result and of the handle
acres_runtime_prepare (api.h)	The speed profile, the path caps and the curvature of a joined path

Field of AcresRtRouteRequest	Content
plan	The fields in visit order, each with its entry, direction, access and exit. A plan with no field is a Return alone from pose.
edge_cost, edge_cost_count	The cost of each directed edge of the transit graph. Null: the lengths.
uturn_penalty	The cost of one U-turn in the units of edge_cost. NaN: 500.
level	The grip level of the speed envelope. 0 is "unknown".
reverse	1 permits turns with the reverse gear.
has_pose, pose	A start away from home. A pose within 5 m and 45 degrees of the home pose is a start at home.
back_off_m, back_track_xy, back_track_count	A reverse stretch before the path, straight or along the driven track.

The result has two parts:

• AcresRtPreparedPath: the joined path (points, distance, speed limit, direction, ground class and leg of each point), the legs with their corridor sides, the speed profile with its caps, the curvature and time_ref_s.
• AcresRtRouteInfo: the status and error text, the length, the time, and the U-turn count of each leg.

The field identifier is that of ACRES Core: 1 to 59 for F01 to F59, and 101 to 200 for RF001 to RF100.

Pure Function and Threads

The route of a mission is a function of the map, the plan and the request. The handle keeps only what it read at its start, and no call changes it.

• The missions of a batch run as one task each.
• The legs of one mission run as one task each when the batch has one mission.
• The route searches of one mission are serial: each leg starts at the node and heading of the leg before it.

Warning

Destroy a route handle with threads above 0 before you create a fleet. Else acres_runtime_fleet_create returns ACRES_RT_ERROR_BUSY. A handle with threads 0 uses the pool that is there. Use it to plan a route while a fleet runs.

Path Shape

The route code smooths each driving stretch and keeps the turns of its manoeuvres (three-point turns and turnarounds) at the vehicle turn radius. A route from a pose joins its lane at 30 degrees. In the last 10 m of a Return leg, the speed limit is the cap of the stop rule for the path that is left.

Caution

A route from a pose with no reverse stretch can end a three-point turn 1 m to 2 m before a lane corner. The smoothed corner can then be tighter than the vehicle can steer. Limitations has the case.