Prerequisites

  • Python 3.11 or 3.12
  • FastSim 0.1.0a6
  • UniRoboSim Core 0.10.0
  • No native simulator is required for this compile-only example

Configuration

The readable Run declares backend: pybullet. The shared arm component has three backend variants:

  • PyBullet selects two_joint_arm.urdf;
  • MuJoCo selects two_joint_arm.urdf;
  • Isaac Lab selects two_joint_arm.usda.

An override changes compilation input and therefore produces a different immutable plan digest. It does not edit run.yaml.

Key code, line by line

python
project = load_project(RUN_FILE)                    # Find the trusted demo Registry.
compiler = project.compiler()                       # Create the public compiler.

The project file under fundamentals/.fastsim/ makes the shared component registry available from every fundamentals directory.

python
for backend in ("pybullet", "mujoco", "isaaclab"):
    compiled = compiler.compile_file(
        RUN_FILE,
        backend_override=backend,                   # Override this invocation only.
    )

Each loop validates the same authoring, selects that backend's component variant, resolves its resource, and seals an ExecutionPlan.

python
origin = compiled.explain("backend").origin

explain() proves that the effective backend came from api_override, rather than silently changing the source file.

Run it

From this case directory:

bash
cd demo/fundamentals/16_backend_selection
python main.py

The equivalent CLI compilation commands are:

bash
fastsim config validate run.yaml --backend pybullet --json
fastsim config validate run.yaml --backend mujoco --json
fastsim config validate run.yaml --backend isaaclab --json

To launch instead of compile, the same CLI switch is accepted:

bash
fastsim run run.yaml --backend isaaclab --duration 3

Adapter compatibility is separate

Successful compilation proves that the Run and selected component variant are valid. Native startup additionally requires a provider built for the installed UniRoboSim Core contract. This FastSim release pins Core 0.10.0; therefore a native run must use a Core 0.10-compatible adapter. At the time of this example, Isaac adapter 0.10.1 and the exact PyBullet/MuJoCo 0.9.2 adapters match FastSim's frozen alias matrix. Other adapter versions are rejected at startup even when their plans compile.

Verification level

COMPILE-ONLY PASS. Python compilation, default Run compilation, and all three backend_override compilations pass. Their selected variants/formats are pybullet/URDF, mujoco/URDF, and isaaclab/USD, with three distinct plan digests. No native backend is started by this example.

Common errors

  • Expecting backend_override to modify run.yaml: it affects one compilation only.
  • Overriding a locked Run: locks reject backend changes by design.
  • Treating compile success as native compatibility: provider loading is a separate runtime gate.

Next: 17 · Liquid.