01 — Configuration validation and compilation

This example checks a Run without opening a simulator. It is the fastest way to find misspelled fields, unresolved use references, missing assets, and invalid runtime rates before spending time on backend startup.

Verification level

Configuration only. This case compiles and inspects a Run; it does not start a simulator or require a GPU.

Prerequisites

FastSim 0.1.0a6 in Python 3.11 or 3.12.
A checkout containing this complete demo/ tree, including _shared/.

Files

run.yaml selects PyBullet, a 60 Hz physics clock, and one red cube.
main.py uses the same compiler from Python and prints the immutable plan identity.
../.fastsim/project.yaml tells FastSim where the shared Registry is located.

Read the configuration

yaml

schema: fastsim/2          # Select the clean FastSim vNext authoring contract.
name: demo-config-validation
backend: pybullet          # Resolve the PyBullet variant of every component.

runtime:
  physics_hz: 60           # Advance physics at 60 simulated steps per second.
  control_hz: 30           # Admit control frames at 30 Hz (unused in this example).
  seed: 7                  # Make resets reproducible.

scenario:
  scene:
    objects:
      red_cube:            # Human-readable alias inside this Scenario.
        use: object://fastsim/demo-cube  # Resolve the stable Registry component.
        pose:
          xyz_m: [0.0, 0.0, 0.5]        # World position in metres.
          quat_xyzw: [0.0, 0.0, 0.0, 1.0]  # Unit quaternion, XYZW order.

use is not a filesystem path. The project Registry maps it to a pinned component manifest, and that manifest selects a backend-compatible asset.

Read the Python program

Path(__file__).with_name("run.yaml") finds the Run beside the script, independent of the current shell directory.
load_project(RUN_FILE) searches upward for .fastsim/project.yaml and loads its Registry and trusted resource roots.
project.compiler().compile_file(RUN_FILE) validates, resolves, normalizes, and freezes the Run.
compiled.execution_plan is the backend-ready, immutable plan. Its SHA-256 digest changes whenever effective simulation meaning changes.

No line in main.py creates a simulator session.

Run it

From this case directory:

bash

cd demo/fundamentals/01_config_validation_and_compilation
fastsim config validate run.yaml --json
fastsim config expand run.yaml
python main.py

Expected output includes "ok": true, backend pybullet, one resolved component, and a 64-character plan digest. expand prints defaults such as runtime.rate_policy: exact; it does not edit run.yaml.

Common errors

PROJECT_CONFIG_NOT_FOUND: run the checked-in file or pass --project; do not copy run.yaml away from its project by itself.
COMPONENT_NOT_FOUND: check the use URI and the Registry index.
RESOURCE_OUTSIDE_TRUSTED_ROOT: explicitly add the asset root to the project; do not weaken resource checks globally.
physics_hz/control_hz must be an integer: use an integer ratio with the default rate_policy: exact, such as 60/30.

Continue with 02 — Start an application and read state.