Python API¶
import beehave
result = beehave.analyze("examples/mobile/navigate_to_goal.xml")
print(beehave.to_text(result.graph))
print(result.stats.to_text())
for action in result.graph.actions:
for edge in result.graph.outgoing(action.id):
print(action.label, edge.outcome, edge.target, [str(lit) for lit in edge.guard])
The pipeline, step by step¶
analyze is a shortcut for the four steps. You can run them yourself:
from beehave import Config, build_graph, flatten, parse_file, to_mermaid
document = parse_file(
"mission.xml", "subtrees.xml", config=Config(conditions=frozenset({"IsBatteryOK"}))
)
tree = flatten(document, "MainTree") # inline subtrees
graph = build_graph(tree) # the action graph
print(to_mermaid(graph))
Use parse_string(xml) to parse XML held in memory. Both detect whether the
XML is BT.CPP v3 or v4; document.format says which ("btcpp-v3" or
"btcpp-v4").
py_trees trees¶
Pass the root of a py_trees tree, or its BehaviourTree, to
analyze_py_trees. The tree is only read: no behaviour is set up or ticked.
import beehave
from my_robot.trees import create_root
config = beehave.Config(conditions=frozenset({"IsBatteryLow"}))
result = beehave.analyze_py_trees(create_root(), config=config)
print(beehave.to_mermaid(result.graph))
from_py_trees(root) gives the Document alone. load_py_trees(spec,
**kwargs) imports a factory by name and calls it, as --py-trees does on the
command line; it runs that code. py_trees itself is an optional
dependency: pip install 'beehave-bt[py-trees]', or use the py_trees of your
ROS 2 distribution.
Presets and bookkeeping actions¶
A Config built in Python takes presets and bookkeeping actions too
(Presets,
Bookkeeping actions):
config = beehave.Config(
nodes={
"KeepTrying": beehave.NodePreset("until_success"),
"RepeatUntilDone": beehave.NodePreset(
"loop_until_flag", {"flag_port": "done", "exit": "success"}
),
},
bookkeeping={"LogMessage": beehave.Bookkeeping(never_fails=True)},
)
beehave.PRESETS lists every preset, with its kind, number of children and
options.
Node ids¶
Every action and every condition in a guard records the node it comes from: its stable path and its runtime ids (Node ids and paths).
import beehave
result = beehave.analyze("examples/aerial/drone_mission.xml")
nodes = beehave.runtime_ids(result.tree, beehave.IdScheme.PREORDER) # every node, by id
arm = result.graph.vertex_for(6) # the action with BT.CPP v4 UID 6
same = result.graph.vertex_at("mission_with_failsafe/mission/Arm") # by stable path
Hashes¶
beehave.graph_hash(result.graph) # "sha256:…", the same for every equal graph
beehave.tree_hash(result.tree) # over beehave.canonical_xml(result.tree)
See Hashes.
Comparing two trees¶
result = beehave.diff_graphs(old.graph, new.graph)
result.changed # any added, removed or changed action, transition, guard or reachability
result.to_text(), result.to_markdown(), result.to_json()
result.score.precision, result.score.recall, result.score.f1
See Comparing two trees.
Main types¶
| Type | What it is |
|---|---|
Document |
Every tree loaded from the files, plus load diagnostics. |
FlatTree |
One tree with every subtree inlined. |
ActionGraph |
Vertices (START, actions, SUCCESS, FAILURE, and SKIPPED for v4 trees that can skip), edges and diagnostics. |
Vertex |
A box: id, kind, label, type, ports, notes, subtrees, location, and node for actions. |
Edge |
source, target, outcome (None from START) and guard, a tuple of Literals. |
Literal, Condition |
One term of a guard: a Condition (key, label, node) that must hold or not. |
NodeRef |
Where a vertex or a condition comes from: path, uid, index, runtime_path, runtime_id(scheme). |
IdScheme |
BTCPP_V4 (from 1) or PREORDER (from 0). |
RuntimeNode |
One node as runtime_ids() lists it: id, ref, parent, kind, type, name, subtree, location. |
Stats |
The Phase 1 metrics; to_text() and to_dict(). |
Errors¶
Everything Beehave raises on bad input derives from beehave.BeehaveError:
| Exception | When |
|---|---|
ParseError |
The XML is malformed or not a valid BT.CPP document, the files mix versions, or a py_trees factory could not be imported or raised. |
UnsupportedFormatError |
The input is in a format Beehave does not read, such as py_trees XML, or py_trees is missing. |
FlattenError |
A subtree is missing or includes itself. |
TreeSelectionError |
No tree, or an unknown tree, was selected. |
ConfigError |
The config file is invalid. |
Each error has a message and, when known, a location (file, line).
Stability¶
Beehave is in alpha (0.x). The names above are the public API; anything not
exported from beehave may change without notice.