Automatic Partitioning Example

See how a branched graph is divided into execution partitions during compilation. The example compares automatic planning with one explicitly named partition and an optional GPU case that keeps one branch anchored to a CUDA resource.

The program compiles and inspects plans. It does not start the graph runtime. Read Automatic Partitioning and Plan Inspection first if partition terminology is new.

Prerequisites

Use the examples-enabled SDK installation from Build the SDK on AGX Orin. The CPU mode does not require a Green Context-capable device. The optional hybrid mode queries CUDA device 0 and can be skipped when the target does not expose the required structured capacity.

What you will learn

How graph shape affects automatic partitioning.
How to inspect partition members and lookup results.
How an authored partition differs from an automatic remainder.
Why a successful plan inspection does not execute the graph.

Build and run

Build the examples through the shared SDK build page, then run the CPU-only walkthrough:

WORKSPACE="$HOME/holoscan-5.0"
cd "$WORKSPACE/holoscan-sdk"
INSTALL_DIR="$(./run get_install_dir)"
RUN_BIN="/workspace/holoscan-sdk/$INSTALL_DIR/lib/holoscan/examples/automatic_partitioning/cpp/automatic_partitioning"
./run launch "$INSTALL_DIR" --run-cmd "$RUN_BIN --mode cpu"

To inspect the optional device-qualified case, use --mode hybrid with the same command.

Follow the workflow

The CPU walkthrough composes this diamond:

         +-> left --+
source --+          +-> join -> tail
         +-> right -+

Operators used

Operator	Role in this example
`Source`	Emits values to the two branches.
`Stage`	Processes branch values; its instances form the left, right, and tail stages.
`Join`	Combines the left and right branches before the tail stage.
`EmbeddedStage`	Provides the descendant graph used by the named-partition case.

The first case lets the compiler choose partitions and prints their identifiers, origin, execution lane, members, and operator paths. It also checks lookup by ID, path, and operator handle. Automatic partitions do not have authored names, so a missing-name lookup is expected to fail.

The second case creates a named partition with include_all(). Its embedded graph descendant belongs to that authored partition. In hybrid mode, the left branch receives a named CUDA anchor while the remaining work stays automatic.

Expected result

The CPU command ends with:

automatic_partitioning cpu example complete

Hybrid mode ends with automatic_partitioning hybrid example complete when the device capability is available. Return code 77 means the hybrid case was skipped because the target could not provide the requested capability. A compilation or inspection error returns a different nonzero result.

The output describes an accepted plan. It does not prove that a later runtime session can start, that CUDA work was launched, or that the chosen layout improves performance.

Related examples and concepts

Examples

CUDA Green Context Example follows a named resource into a running CUDA graph.
Managed Run Control Example shows the run phase after compilation.

Concepts

Automatic Partitioning and Plan Inspection explains the plan records and lookup choices.
Building Graphs and Queue Policies explains the graph connections used by the diamond.
Application, Graph, and Operator Anatomy connects composition, compilation, and execution.

Source The complete example is in the Automatic Partitioning example. The application source contains the graph and inspection checks, and the build definition registers the CPU and hybrid tests.

Official documentation

NVIDIA Holoscan SDK official documentation provides the current graph and execution-plan reference.

❯