Add a Scenario#

A scenario of the harness is one JSON file: a mission, the objects that come onto the path, and the rules of success. This page writes a scenario and runs it.

Before you start

Do the Python only path of the install.
Read Run Scenarios with the Harness.

Write the Scenario#

Write this file into Harness/scenarios/my_person_on_the_lane.json.

Harness/scenarios/my_person_on_the_lane.json

{
 "schema": "acres-harness-scenario-1",
 "id": "my_person_on_the_lane",
 "tier": "T2",
 "title": "A Person Stands on the Lane",
 "instruction": "Scout field F56. Then come home. A person can stand on the lane.",
 "start": "H",
 "fields": ["F56"],
 "deadline_s": 900.0,
 "events": [
  {"t": 0.0, "type": "object_add",
   "object": {"id": 1, "kind": "person", "place": {"route_to": "F56", "leg": "goto", "at_m": 60.0}}},
  {"after_seen": 1, "delay_s": 30.0, "type": "object_remove", "id": 1}
 ],
 "success": {"scouted": ["F56"], "home": true, "before_deadline": true, "no_collision": true}
}

The person stands 60 m along the route from H to F56. It goes away 30 s after the vehicle senses it.

Run the scenario with the scripted decision maker. It needs no model service.
```
python -m acres_harness run --scenario Harness/scenarios/my_person_on_the_lane.json --out runs/my
```
Expected result

The table of the run shows success. The skill goto ended one time with blocked at the person.
```
scenario               mode     profile  model     success  end       scouted  time_s  ...  codes
my_person_on_the_lane  checked  vehicle  scripted  yes      finished  1/1      485.6   ...  blocked:1 done:3
1 of 1 runs with success
```
Tip

The run takes approximately 4 minutes, because the shield reads the simulated LiDAR sweep. Set ACRES_RUNTIME_SHIELD_SCAN=planar for the fast planar scan. The run then takes approximately 15 s.
Check the run folder against the recording contract.
```
python -m acres_harness validate runs/my
```

The Keys of a Scenario#

Key	Default	Content
`schema`		`acres-harness-scenario-1`
`id`, `tier`, `title`		The name of the scenario in the tables and the logs.
`instruction`		The text that a model gets.
`fields`		The fields of the mission.
`start`	`"H"`	The start pose: `"H"` or `{"x": ..., "y": ..., "yaw": ...}`.
`map`	`"default"`	The map by its name, for example `acre-mixed`.
`condition`	`"dry"`	The condition set: `"dry"`, `"wet"` or `"shift"`.
`deadline_s`, `fuel_limit_mj`	none	The time and the fuel energy of the mission.
`events`	none	The objects and the requests during the mission.
`limits`		The limits of the run: `wake_ups`, `tool_calls`, `sim_s`, `wall_s`, `usd`, `stall_s` and others.
`local_planner`	`"default"`	A local planner of a plugin that drives `goto`, `scout` and `return_home`.
`recovery`	off	The recovery interface, for example `{"mode": "menu"}`.
`success`		The rules of success. Each key must hold.

Harness/acres_harness/scenario.py gives each key with its rules.

Events#

An event has a time t in simulation seconds, or after_seen with delay_s. An after_seen event comes that long after the vehicle senses the object for the first time.

Type	Content
`object_add`	Put an object on the map: `{"id", "kind", "place"}`.
`object_remove`	Remove the object with the identifier `id`.
`request`	Give a text request to the decision maker, for example `"Come home after this field."`

Object Kind	Length	Width	Height
`person`	0.6 m	0.6 m	1.8 m
`car`	5.3 m	2.0 m	1.8 m
`truck`	6.0 m	2.5 m	2.5 m
`tractor`	7.5 m	3.0 m	3.0 m

Place	Meaning
`{"x": ..., "y": ..., "yaw": ...}`	A pose in the world frame, in meters and radians.
`{"route_to": "F53", "leg": "goto", "at_m": 60}`	A point on a leg of the mission of that field from H. Add `"across": true` to put the object across the path.
`{"loop_of": "F53", "at_fraction": 0.5}`	A point on the scout loop of the field.

Success Rules#

Key	Holds When
`scouted`	The vehicle scouted each field of the list.
`scouted_min`	The vehicle scouted at least this number of fields.
`not_scouted`	The vehicle did not scout the fields of the list.
`order`	The vehicle scouted the fields in this sequence.
`home`	The vehicle is at H at the end.
`before_deadline`, `within_fuel`	The mission kept its time and its fuel energy.
`max_blocked`	The skills ended `blocked` at most this number of times.
`no_collision`	The vehicle touched no object.

Add a Test#

Add a test that runs the scenario with the scripted decision maker and asserts the result. Harness/tests/test_catalogue.py runs the scenarios of Harness/scenarios in this way. Mark the test with the tier e2e (Tests).