Add a Task

This page gives the procedure to add a benchmark task to ACRES. The scouting task is the model for a new task.

Tasks describes the tasks that exist. Framework describes the learning stack that runs them.

Before You Start

• Build ACRES Core. Refer to Build ACRES Core.
• Run the tests of the learning stack one time. Refer to Tests and Regression Checklist.
• Read the definition of the scouting task in Learning/acres_learn/tasks/scouting.

What a Task Contains

A task is a Python package below Learning/acres_learn/tasks. One definition applies to ACRES Core and to the game.

Part	File in the Scouting Task	Content
Constants	spec.py, configs/scouting_v1.json	The action map, the observation layout, the reward weights.
Rewards	rewards.py	Each reward term as a pure function.
Terminations	termination.py	The tests for success, failure and time limit on a state.
Observations	observations.py	The observation groups of a policy.
Mission	mission.py	The legs of one episode and its bookkeeping.
Conditions	conditions.py	The sets of soil water and hardware shifts.
Instructions	instructions.py	The text instruction of a plan.
Map products	map_products.py, build_map.py	The task data on the map and the tool that builds it.
Reference driver	reference_driver.py, routes.py	A driver without learning that completes the task.
Environment	envs/scouting.py	A vector environment over the batch of ACRES Core.
Evaluation	eval/	The suite, the scorers and the comparison with the game.
Tests	Learning/tests/test_scouting_*.py	Tests of each part.

Procedure

1. Write the task definition as a page in Documentation/Tasks.

   State the goal, the start, the end, the actions, the observations, the rewards and the failure conditions.

2. Make the package Learning/acres_learn/tasks/<task>.

3. Put each constant of the task into a JSON file in Learning/acres_learn/configs.

4. Write the reward terms and the termination tests as pure functions of a state dictionary.

   Pure functions permit tests without a simulator.

5. Build the map products of the task from the map products of the simulator.

   Put the output into Acres/Content/Simulation/ACRE/<Task>. Record the hash of the inputs in the output. Map Products gives the input files.

6. Write a reference driver that completes the task without learning.

   The reference driver proves that the task is possible. It also gives the reference quantities for the scores.

7. Write the environment over ACRES Core.

   Use the batch of acres_core. Python API gives the state arrays and the command rows.

8. Add the evaluation suite with a frozen split of the fields or cases.

9. Compare ACRES Core with the game on some episodes of the task.

   Record an episode log in Core. Replay it in the game. Headless Core Runs shows the method.

10. Add tests for each part and add them to Learning/tests/run_all.py.

11. Add the pages of the task to the section "Tasks" in mkdocs.yml.

    Expected Result

    python Learning/tests/run_all.py reports no failure. The reference driver completes each case of the suite.

Rules for a Task

• Use the drive-by-wire commands of the real vehicle as the actions. A policy then runs on the vehicle without a new interface.
• Do not give a policy an input that the real vehicle does not have, unless the task states it.
• Define the failure conditions before the rewards.
• Keep one definition for all simulators. Do not copy constants into a second file.
• Give each stochastic element a seed.

What the Simulator Supplies

Need of the Task	Interface
Fast steps for many environments	The batch of ACRES Core.
Soil water, weather and hardware shifts	The conditions of the batch, or the services /acres/set_conditions and /acres/set_vehicle_shift.
Ground truth of the farm	The episode log, the services /acres/farm_state and /acres/field_query.
Deterministic steps in the game	Lockstep. Refer to Lockstep Stepping.
Images of an episode	Episode replay. Refer to Replay.
The same interface on the vehicle	The ROS 2 topics. Refer to Topics.