NVIDIA Holoscan SDK v2.5.0
Holoscan v2.5.0

Behavior Trees

Behavior tree codelets are one of the mechanisms to control the flow of tasks in GXF. They follow the same general behavior as classical behavior trees, with some useful additions for robotics applications. This document gives an overview of the general concept, the available behavior tree node types, and some examples of how to use them individually or in conjunction with each other.

Behavior trees consist of n-ary trees of entities that can have zero or more children. The conditional execution of parent entity is based on the status of execution of the children. A behavior tree is graphically represented as a directed tree in which the nodes are classified as root, control flow nodes, or execution nodes (tasks). For each pair of connected nodes, the outgoing node is called parent and the incoming node is called child.

The execution of a behavior tree starts from the root which sends ticks with a certain frequency to its child. When the execution of a node in the behavior tree is allowed, it returns to the parent a status running if its execution has not finished yet, success if it has achieved its goal, or failure otherwise. The behavior tree also uses a controller component for controlling the entity’s termination policy and the execution status. One of the controller behaviors currently implemented for Behavior Tree is EntityCountFailureRepeatController, which repeats the entity on failure up to repeat_count times before deactivating it.

GXF supports several behavior tree codelets which are explained in the following section.

Each behavior tree codelet can have a set of parameters defining how it should behave. Note that in all the examples given below, the naming convention for configuring the children parameter for root codelets is [child_codelet_name\child_codelet_scheduling_term].

Constant Behavior

After each tick period, switches its own status to the configured desired constant status.

Parameter

Description

s_term scheduling term used for scheduling the entity itself
constant_status The desired status to switch to during each tick time.

An example diagram depicting Constant behavior used in conjunction with a Sequence behavior defined for root entity is shown below:

constant_behavior.png

Here, the child1 is configured to return a constant status of success (GXF\_BEHAVIOR\_SUCCESS) and child2 returns failure (GXF\_BEHAVIOR\_FAILURE), resulting into the root node (configured to exhibit sequence behavior) returning GXF\_BEHAVIOR\_FAILURE.

The controller for each child can be configured to repeat the execution on failure. A code snippet of configuring the example described is shown below.

Copy
Copied!
            

name: root components: - name: root_controller type: nvidia::gxf::EntityCountFailureRepeatController parameters: max_repeat_count: 0 - name: root_st type: nvidia::gxf::BTSchedulingTerm parameters: is_root: true - name: root_codelet type: nvidia::gxf::SequenceBehavior parameters: children: [ child1/child1_st, child2/child2_st ] s_term: root_st --- name: child2 components: - name: child2_controller type: nvidia::gxf::EntityCountFailureRepeatController parameters: max_repeat_count: 3 return_behavior_running_if_failure_repeat: true - name: child2_st type: nvidia::gxf::BTSchedulingTerm parameters: is_root: false - name: child2_codelet type: nvidia::gxf::ConstantBehavior parameters: s_term: child2_st constant_status: 1

Parallel Behavior

Runs its child nodes in parallel. By default, succeeds when all child nodes succeed, and fails when all child nodes fail. This behavior can be customized using the parameters below.

Parameter

Description

s_term scheduling term used for scheduling the entity itself
children Child entities
success_threshold Number of successful children required for success. A value of -1 means all children must succeed for this node to succeed.
failure_threshold Number of failed children required for failure. A value of -1 means all children must fail for this node to fail.

The diagram below shows a graphical representation of a parallel behavior configured with failure\_threshold configured as -1. Hence, the root node returns GXF\_BEHAVIOR\_SUCCESS even if one child returns a failure status.

parallel_behavior.png

A code snippet to configure the example described is shown below.

Copy
Copied!
            

name: root components: - name: root_controller type: nvidia::gxf::EntityCountFailureRepeatController parameters: max_repeat_count: 0 - name: root_st type: nvidia::gxf::BTSchedulingTerm parameters: is_root: true - name: root_codelet type: nvidia::gxf::ParallelBehavior parameters: children: [ child1/child1_st, child2/child2_st ] s_term: root_st success_threshold: 1 failure_threshold: -1

Repeat Behavior

Repeats its only child entity. By default, won’t repeat when the child entity fails. This can be customized using the parameters below.

Parameter

Description

s_term scheduling term used for scheduling the entity itself
repeat_after_failure Denotes whether to repeat the child after it has failed.

The diagram below shows a graphical representation of a repeat behavior. The root entity can be configured to repeat the only child to repeat after failure. It succeeds when the child entity succeeds.

repeat_behavior.png

A code snippet to configure a repeat behavior is as shown below -

Copy
Copied!
            

name: repeat_knock components: - name: repeat_knock_controller type: nvidia::gxf::EntityCountFailureRepeatController parameters: max_repeat_count: 0 - name: repeat_knock_st type: nvidia::gxf::BTSchedulingTerm parameters: is_root: false - name: repeat_codelet type: nvidia::gxf::RepeatBehavior parameters: s_term: repeat_knock_st children: [ knock_on_door/knock_on_door_st ] repeat_after_failure: true ---

Selector Behavior

Runs all child entities in sequence until one succeeds, then reports success. If all child entities fail (or no child entities are present), this codelet fails.

Parameter

Description

s_term scheduling term used for scheduling the entity itself
children Child entities

The diagram below shows a graphical representation of a Selector behavior. The root entity starts child\_1, child\_2, and child\_3 in a sequence. Although child\_1 and child\_2 fail, the root entity will return success since child\_3 returns successfully.

selector_behavior.png

A code snippet to configure a selector behavior is as shown below.

Copy
Copied!
            

name: root components: - name: root_controller type: nvidia::gxf::EntityCountFailureRepeatController parameters: max_repeat_count: 0 - name: root_st type: nvidia::gxf::BTSchedulingTerm parameters: is_root: true - name: root_sel_codelet type: nvidia::gxf::SelectorBehavior parameters: children: [ door_distance/door_distance_st, door_detected/door_detected_st, knock/knock_st ] s_term: root_st --- name: door_distance components: - name: door_distance_controller type: nvidia::gxf::EntityCountFailureRepeatController parameters: max_repeat_count: 0 - name: door_distance_st type: nvidia::gxf::BTSchedulingTerm parameters: is_root: false - name: door_dist type: nvidia::gxf::SequenceBehavior parameters: children: [] s_term: door_distance_st ---

Sequence Behavior

Runs its child entities in sequence, in the order in which they are defined. Succeeds when all child entities succeed or fails as soon as one child entity fails.

Parameter

Description

s_term scheduling term used for scheduling the entity itself
children Child entities

The diagram below shows a graphical representation of a Sequence behavior. The root entity starts child\_1, child\_2 and child\_3 in a sequence. Although child\_1 and child\_2 pass, the root entity will return failure since child\_3 returns failure.

sequence_behavior.png

A code snippet to configure a sequence behavior is as shown below.

Copy
Copied!
            

name: root components: - name: root_controller type: nvidia::gxf::EntityCountFailureRepeatController parameters: max_repeat_count: 0 - name: root_st type: nvidia::gxf::BTSchedulingTerm parameters: is_root: true - name: root_codelet type: nvidia::gxf::SequenceBehavior parameters: children: [ child1/child1_st, child2/child2_st ] s_term: root_st

Switch Behavior

Runs the child entity with the index defined as desired\_behavior.

Parameter

Description

s_term scheduling term used for scheduling the entity itself
children Child entities
desired_behavior The index of child entity to switch to when this entity runs

In the code snippet shown below, the desired behavior of the root entity is designated to be the the child at index 1 (scene). Hence, that is the entity that is run.

Copy
Copied!
            

name: root components: - name: root_controller type: nvidia::gxf::EntityCountFailureRepeatController parameters: max_repeat_count: 0 - name: root_st type: nvidia::gxf::BTSchedulingTerm parameters: is_root: true - name: root_switch_codelet type: nvidia::gxf::SwitchBehavior parameters: children: [ scene/scene_st, ref/ref_st ] s_term: root_st desired_behavior: 0 --- name: scene components: - name: scene_controller type: nvidia::gxf::EntityCountFailureRepeatController parameters: max_repeat_count: 0 - name: scene_st type: nvidia::gxf::BTSchedulingTerm parameters: is_root: false - name: scene_seq type: nvidia::gxf::SequenceBehavior parameters: children: [ pose/pose_st, det/det_st, seg/seg_st ] s_term: scene_st ---

Timer Behavior

Waits for a specified amount of time delay and switches to the configured result switch\_status afterwards.

Parameter

Description

s_term scheduling term used for scheduling the entity itself
clock Clock
switch_status Configured result to switch to after the specified delay
delay Configured delay

In the diagram shown below, the child entity switches to failure after a configured delay period. The root entity hence returns failure.

timer_behavior.png

A code snippet for the same shown below.

Copy
Copied!
            

name: knock_on_door components: - name: knock_on_door_controller type: nvidia::gxf::EntityCountFailureRepeatController parameters: max_repeat_count: 10 - name: knock_on_door_st type: nvidia::gxf::BTSchedulingTerm parameters: is_root: false - name: knock type: nvidia::gxf::TimerBehavior parameters: switch_status: 1 clock: sched/clock delay: 1 s_term: knock_on_door_st ---

Previous The GXF Scheduler
Next GXF Core C APIs
© Copyright 2022-2024, NVIDIA. Last updated on Oct 1, 2024.