Architecture and Execution Model

Holoscan separates graph authoring, compilation, and execution. A useful mental model is:

compose the graph -> compile an accepted plan -> run and observe the session

Compose describes what should connect. Compile checks those declarations and prepares a plan. Run acquires runtime resources and executes that plan. Keeping the stages separate makes it easier to tell whether a problem belongs to graph construction, compilation, startup, or processing.

Compose: Describe the Data Flow

Start by describing the work in user terms:

Concept	Meaning in an application
Operator	One processing step, such as capture, conversion, inference, fusion, or display.
Port	A named input or output through which an operator receives or publishes a payload.
Sample	One payload moving through the graph together with metadata used to interpret or correlate it.
Graph	The connected set of operators and the data paths between them.
Contract	The rule that says when an operator may run and which input samples it should use.

A camera/IMU application may connect a frame producer and an inertial producer to a fusion operator, then send the result to control or another process. An image pipeline may connect capture, preprocessing, inference, and visualization. The graph shape comes from the desired result; it is not an implementation diagram that the reader must understand before using the application.

An operator usually separates three responsibilities: setup() declares its ports and structure, contract() describes activation and input selection, and compute() performs the work for one activation. Application, Graph, and Operator Anatomy shows how those pieces are used when writing an operator.

Follow a Sample through the Graph

A payload can be a scalar measurement, a generated schema, or a Tensor-backed array. Its representation answers what the data is; sample metadata answers how that publication participates in the graph. The Ports, Samples, and Payload Types and Sensor Payloads and Schemas pages define those choices before the application code needs to use them.

A useful example is the SDK's camera_imu_control workflow. It uses synthetic inputs to demonstrate the shape of a camera/IMU fusion application and exports a scalar result. The example is an architecture and timing demonstration; it is not a physical sensor driver or an actuator integration.

The slow_fast_fusion example uses two scalar streams at different rates. A temporal contract decides whether the slower sample is recent enough to contribute when the faster stream activates the fusion step.

Compile: Prepare an Accepted Plan

Compilation is the checkpoint between an application description and execution. The compile() function checks the graph and returns an ExecutionPlan. Check the plan's ok() result before trying to run it.

Compilation can catch structural problems such as incompatible ports, incomplete timing declarations, or unsupported resource combinations. It can also prepare queue, Tensor, and execution-partition decisions needed by the runtime. These checks do not prove that a required camera, device, driver, model, or runtime binding is available on the target.

A compile failure is therefore different from a startup failure. Keep the plan diagnostics when compilation is rejected, and move to the build or device-specific guidance when the plan is accepted but runtime resources cannot be acquired.

Run: Execute and Observe the Session

A blocking run() call suits an application whose main work is the graph. When the surrounding application must also manage a user interface, device control, or another service, run_async() returns a RunSession.

The session has a small, practical control surface: request_stop() asks the graph to stop cooperatively, wait() joins the run and cleanup, and termination() reports the coarse outcome. The Running and Stopping guide turns this into a complete application pattern.

A successful compile and a clean session outcome answer different questions. Compilation says that the graph declarations were accepted. A completed or stopped session says that this run reached its terminal state. Neither result alone proves that a physical sensor produced valid data or that the application met its latency target.

Connect Processes When the Boundary Helps

Keep work inside one graph when the stages share a lifecycle and data path. Use an external topic when a sensor service, recorder, control application, or independently deployed pipeline needs to exchange selected data across a process boundary. The External Endpoints and Endpoint Catalogs and Descriptor-Tensor External Topics pages explain those choices after the graph vocabulary is established.

At a process boundary, the payload contract still matters. A Tensor-bearing topic must agree on representation and memory requirements; a schema-bearing topic must agree on the named fields and their meaning. Transport choice does not remove those application decisions.

Continue

Continue with Running and Stopping to turn the run model into a working application. Then follow Ports, Samples, and Payload Types and Temporal Contracts and Input Selection before writing a custom operator.

Further reading

Official NVIDIA Holoscan SDK documentation
Automatic Partitioning Example for inspecting how a graph was grouped for execution.
Managed Run Control Example for explicit stop, wait, and terminal-state handling.

❯