Using the Python Application API

Application shape

import asyncio
import fastsim

async def main() -> None:
    async with fastsim.app("run.yaml") as simulation:
        await simulation.start()
        snapshot = await simulation.state()
        targets = await simulation.control.targets()
        print(snapshot, targets)

asyncio.run(main())

The context guarantees final close, but application code still handles start, Operation results, cancellation, and timeout explicitly. Never extract a native backend object and mutate it from another thread.

Capability clients

• scene: catalog, state, and controlled pose/drag/attach operations.
• frames: frame catalog, lookup, and transforms.
• geometry: planning-geometry capabilities, catalogs, transforms, and resources.
• kinematics: queries through an available solver.
• control: target discovery, joint/track chunks, status, and cancellation.
• visualization: debug primitives, metrics, and events.
• checkpoint, camera, and output clients appear according to Run capabilities.

Discover capabilities and targets before calling optional features. Missing optional capability is explicit—not a reason to catch every exception and continue.

The API is asynchronous, but one authority boundary still serializes backend ownership. A timeout limits caller waiting and does not automatically cancel an Operation. Simple scripts may use synchronous FastSimRun; services and UIs should retain the async Application.

Current signatures are generated in the Python SDK.