Skip to content

Planner and Cost Tables#

The planner of the run-time library makes the plan of a mission. A plan gives the order of the fields, and the entry and direction of each Scout loop. It reads cost tables that the fleet drives on the map. The header is Runtime/Include/acres_runtime/planner.h.

Before you start

Parts#

Source in Runtime/ Content
Source/cost_table.cpp, cost_table_npz.cpp The table file, its .npz reader and writer, and all drives of a map as one queue
Source/fleet.cpp (last section) The drive of path segments in the slots of a fleet
Source/segment_paths.cpp The paths of the drives, the map of the planner, and the paths from H and to H
Source/option_graph.cpp The route search and the option graph
Source/planner.cpp The exact dynamic program, and the plans of many missions
Source/plan_check.cpp The plan checker
Runtime/Tools/planner.cpp The program acres_runtime_planner
Tests/planner_tests.cpp, Tests/planner_map_tests.cpp The tests

Cost Tables#

A table file is one .npz file for each condition set (dry, wet, shift). It has 12 metrics for each directed edge of the transit graph and for each direction of each Scout loop. The object meta of the file states the map hash and the simulation version.

The fleet drives the tables. acres_runtime_cost_tables_drive_segments puts all drives of the condition sets into one queue: each directed edge, each loop direction and one turn for each set.

Segment Drive#

acres_runtime_fleet_drive_segments drives path segments in the slots of a fleet. A segment is a path with a lead-in and a lead-out.

Property Content
Start at speed The vehicle starts on the first point of the path at the speed of the lead-in.
No stop at the end The speed profile has no stop. The drive ends when the driver projection passes the end of the segment.
Stuck detector The mean slip of the driven wheels stays above episode.stuck_slip for episode.stuck_time_s at a low speed.
Slip window The sustained slip is the mean slip of the last planner.sustained_slip_window_s. Its largest value is peak_slip.
Contact A contact on the segment ends the drive with the collision flag.
Three-point turn The gear logic acts, and each stretch ends with a stop.

The longest segment goes first. A slot gets the condition set of its segment at the start of the segment.

Path of an Edge Drive#

The path of an edge drive is the line of the map with one point for each metre. It has a straight lead-in of 15 m and a straight lead-out of 10 m.

  • limit_curvature_rate makes the path obey the curvature rules of the trajectory checker.
  • The speed profile obeys the steering-rate rule down to the launch speed (0.3 m/s).
  • Where a corner of the line is too tight, the drive uses the smoothed path of a GoTo leg on the edge (edge_drive of segment_paths.cpp).

Slow Edges#

The drive of an edge is slow when its mean speed is below 0.1 of the mean speed limit of its ground. An edge shorter than 3 m is not slow.

The table file lists each slow edge and each edge with a time-out in slow_edges of the object meta. The planner does not use an edge with a time-out. To print them, run python -m acres_simulator.tables or python -m acres_simulator.maps --tables <name>.

Warning

Find the cause of a slow edge or a time-out before you use the tables. It is a defect of the drive path or of the map.

Option Graph and Exact Program#

The option graph of a mission has one option for each field, entry and direction.

  • The route search uses Dijkstra labels for the network pieces and the headings.
  • A graph has its own route trees. Thus the graph of a mission does not depend on the missions before it.
  • The exact program exact_dp uses the set of completed fields and the last option as its state. A tie goes to the option with the lower number.
  • acres_runtime_planner_plan plans many missions, one task for each mission.

The exact program takes 12 fields at most (planner.exact_max_fields). A mission with more fields gets the status ACRES_RT_ERROR_NOT_IMPLEMENTED.

Plan Check#

acres_runtime_plan_check applies the plan rules of the Lean model (checkProposal and Mission.checkWellFormed). The verdict gives the first rule that fails and the data of the counterexample.

Reason Data of the Counterexample
mission_not_well_formed The option, and the fields that the tables and the option list give it
malformed The index of the stop
not_home_to_home The index of a stop "home" between two visits
not_an_option The index of the stop and its visit
fields_not_each_once The first field with two visits, or the first field with no visit
removed_entry The table and the options of the removed entry

plan_check.cpp is C++, not code compiled from the Lean model. When the checker plug-in is in the process, the plug-in also decides each plan. A difference of the two verdicts is a refusal with the status ACRES_RT_ERROR_INTERNAL.

Program#

Runtime/Build/acres_runtime_planner tables --root . --segments <folder>/planner_segments.npz \
    --out <tables folder> --slots 24 --threads 8
Runtime/Build/acres_runtime_planner plans --root . --map <folder>/planner_map.npz --tables <tables folder> \
    --home <folder> --missions missions.txt --threads 8 --out plans.txt

The file of --missions has one line for each mission: the condition set, then the field names. The file of --out has one line for each plan.

Functions#

Function of planner.h Function
acres_runtime_cost_tables_load, _save, _destroy, _view, _field The table file and its arrays
acres_runtime_fleet_drive_segments The drive of path segments in the slots of a fleet
acres_runtime_cost_tables_drive, acres_runtime_cost_tables_drive_segments All drives of a map as one queue, and the tables of each condition set
acres_runtime_cost_segments_from_routes, _load, _view, _destroy The paths of the drives
acres_runtime_planner_map_from_routes, _load, _destroy, _fields, _field, _field_index The map of the planner
acres_runtime_home_legs_from_routes, _load, _create, _add, _count, _destroy The paths from H and to H
acres_runtime_planner_edge_costs The edge costs and the U-turn cost of a route request
acres_runtime_planner_solve, acres_runtime_planner_plan The exact program on given tables, and the plans of many missions
acres_runtime_option_graph_build, _view, _destroy, _best_options, _plan_order The option graph of one mission
acres_runtime_plan_check, acres_runtime_plan_check_mission, acres_runtime_plan_mission_of_graph The plan checker

Baseline of a Map#

acres_runtime_baseline_run (baseline.h) drives the tables, plans each single-field mission, prepares the routes and drives the missions, in one process with no Python. The program Runtime/Build/acres_runtime_baseline_all and the command python -m acres_simulator.baseline call it.

Runtime/Build/acres_runtime_baseline_all --root . --out <folder> --threads 8
Option Default Function
--threads 8 The threads of the pool
--slots 3 for each thread The slots of the fleet
--conditions dry,wet,shift The condition sets
--fields Each task field Only the missions of these fields
--tables Read the table files of a folder and drive no tables
--reference Compare each drive with the recorded reference. The last line is BASELINE_PASS or BASELINE_FAIL.

The output folder has costs/<condition>.npz, single/results.json, the reports, plans.txt, digest.txt and timings.json. Two runs with an equal digest.txt are equal bit for bit.