Move co-sim behavior configuration to scenario YAML

[kawaeeeee]

Summary

Moves CARLA/TeraSim co-simulation behavior settings from process environment variables into a typed top-level cosim section in each scenario YAML. CARLA and TeraSim now resolve the same Pydantic model, log the effective configuration, and persist it with the simulation output.

Deployment-specific values remain outside the scenario: CARLA/TeraSim hosts and ports, the direct gRPC address, and the scenario path continue to be supplied through CLI arguments or deployment environment variables.

Motivation

Previously, behavioral configuration was split across two processes and two independent groups of environment variables:

scenario YAML                 process environment
     |                         /             \
     |                 TeraSim settings   CARLA settings
     |                         \             /
     +-------------------------- co-simulation

That arrangement had no shared schema, made invalid values fail inconsistently, and allowed the CARLA and TeraSim sides to run with different effective settings. Reproducing a run also required preserving container environment in addition to the scenario file, while the final resolved values were not saved with the output.

The project is still in development and has no deployed compatibility requirement, so the old behavioral environment-variable readers are removed instead of retaining a second configuration source. This keeps precedence and debugging straightforward: scenario YAML first, then typed model defaults for omitted fields.

Design

One typed model for both processes. terasim_service.cosim_config.CosimConfig owns all behavioral settings and nested validation:

scenario YAML (`cosim`)
          |
          v
  load_cosim_config()
          |
          v
     CosimConfig
       /      \
      v        v
TeraSim plugin  CarlaCosim

The model covers:

• actor_scope — enable filtering, select the center actor, and configure its radius.
• lane_relative_position — emit reconstructed lane-relative positions in TeraSim and prefer them in CARLA.
• batch — batch CARLA transform updates and actor spawn commands.
• spawn — configure CARLA spawn Z clearance.
• backoff — configure initial and maximum actor-spawn failure delays.
• idle_state_write_interval_seconds — rate-limit Redis state refreshes while the Redis-backed plugin is idle.

Unknown keys and negative distances/intervals are rejected. If backoff.max_seconds is below initial_seconds, it is clamped to the initial delay to preserve the runtime backoff invariant.

Configuration flow. The FastAPI simulation path and run_direct.py parse the scenario and inject the same model into TeraSimCoSimPlugin / TeraSimCoSimDirectPlugin. CarlaCosim loads the same scenario before connecting to CARLA and uses the CARLA-relevant fields from that model. There is no CARLA-side or TeraSim-side environment fallback.

Effective configuration. Both sides log the fully resolved model. The TeraSim plugin additionally writes cosim_effective_config.yaml into the individual simulation output directory next to terasim_cosim_plugin.log, so a run carries the exact behavior configuration used after defaults were applied.

Deployment boundary. Runtime topology stays configurable outside the scenario. --carla_host, --carla_port, --terasim_host, --terasim_port, --direct_addr, --grpc_host, and --grpc_port are unchanged. Only simulation behavior moves into YAML.

Defaults

The shared defaults favor the current dense co-simulation path:

setting	default
actor filtering	enabled, centered on AV, 300 m radius
lane-relative position	enabled
transform batching	enabled
actor-spawn batching	enabled
spawn Z clearance	5 m
spawn failure backoff	5 s initial / 30 s maximum
idle state write interval	0.5 s

cosim_mcity.yaml and cosim_town01.yaml include the complete section explicitly. Individual scenarios can disable actor filtering or batching by setting the corresponding YAML values to false.

Files

• terasim_service/cosim_config.py — shared Pydantic models, scenario loader, effective-config logging, and YAML persistence.
• plugins/cosim.py — consumes the injected model for actor scope, lane-relative state, and idle writes; saves the effective config.
• plugins/cosim_direct.py — accepts and forwards the shared model to the base plugin.
• api.py and run_direct.py — load the scenario cosim section for Redis/FastAPI and direct gRPC runners.
• utils/carla/cosim.py — replaces CARLA behavioral environment reads with the shared model.
• examples/scenarios/cosim_{mcity,town01}.yaml — explicit typed co-sim settings.
• docker-compose.cosim-odaiba-3cosim-direct.yml — removes behavioral environment variables; the selected scenario owns those values.
• docs/cosim_configuration.md — schema, defaults, deployment boundary, and effective-config location.

Testing

• tests/test_service/test_cosim_config.py: 8 passing cases covering defaults, shared typed parsing, explicit YAML disablement, invalid/unknown value rejection, and effective-config persistence.
• Black check on the shared model and its tests.
• Ruff E,F,W,C90,I check on the shared model and its tests.
• Python compilation and YAML parsing checks for the changed modules, scenario examples, and compose file.
• Container smoke tests using the existing terasim-service:integration image:
  • CARLA, FastAPI, direct runner, and both plugin modules import with the new loader signature.
  • cosim_town01.yaml resolves actor filtering and batching as enabled.
  • TeraSimCoSimPlugin receives the configured actor scope and idle interval.
  • cosim_effective_config.yaml is written successfully.

Notes

This intentionally removes support for the former behavioral CARLA_COSIM_* and TERASIM_COSIM_* environment variables. Setting those names no longer changes simulation behavior. Deployment environment variables for connection details remain supported.

The Odaiba scenario referenced by docker-compose.cosim-odaiba-3cosim-direct.yml is not tracked in this repository; that scenario must include its own cosim section when supplied externally.