Skip to content

zyfgi/carsim-guide-skill

carsim-guide

Verified

Operate and automate CarSim simulations from an agent, including safe output and parameter discovery, named Run Control execution contexts, structured overrides, isolated batch sweeps, dataset dependency inspection, control-mode selection, result validation, diagnostics, and version-aware CLI/Simulink/VS API routing. Use for executing, configuring, exploring, or debugging CarSim. Do not use for vehicle-dynamics theory alone, generic dataframe work, or unrelated simulators.

FileKindSize
SKILL.mdskill md6.3 KB
examples/batches/friction_sweep.yamlconfig159 B
examples/batches/mass_friction_grid.yamlconfig198 B
examples/discovery/dataset_tree.pyscript693 B
examples/discovery/find_output.pyscript715 B
examples/discovery/find_parameter.pyscript761 B
examples/scenarios/basic_cruise.yamlconfig380 B
examples/scenarios/friction_change.yamlconfig379 B
examples/scenarios/steering_maneuver.yamlconfig377 B
examples/scenarios/tire_force_output.yamlconfig437 B
examples/scenarios/vehicle_override.yamlconfig376 B
examples/simulink_cosim.pyscript5.5 KB
examples/torque_vectoring.pyscript5.6 KB
references/advanced-controls.mdmarkdown4.0 KB
references/batch-workflows.mdmarkdown1.6 KB
references/compatibility.mdmarkdown1.4 KB
references/control-modes.mdmarkdown1.0 KB
references/database-exploration.mdmarkdown7.4 KB
references/dataset-syntax.mdmarkdown6.6 KB
references/outputs-and-units.mdmarkdown2.1 KB
references/parameter-discovery.mdmarkdown1.4 KB
references/parameters.mdmarkdown3.3 KB
references/python-interface.mdmarkdown7.9 KB
references/run-validation.mdmarkdown2.2 KB
references/scenarios.mdmarkdown3.3 KB
references/simulink-cosim.mdmarkdown4.0 KB
references/troubleshooting.mdmarkdown1.4 KB
references/version-compatibility.mdmarkdown811 B
references/vs-c-api.mdmarkdown3.3 KB
scripts/base_registry.pyscript4.7 KB
scripts/batch_runner.pyscript7.1 KB
scripts/carsim_batch.pyscript23.4 KB
scripts/carsim_errors.pyscript2.2 KB
scripts/control_modes.pyscript1.8 KB
scripts/cosim_model.mother4.7 KB
scripts/database_tools.pyscript16.5 KB
scripts/diagnose_run.pyscript444 B
scripts/diagnostics.pyscript6.9 KB
scripts/discovery_query.pyscript1.0 KB
scripts/dump_dll_exports.pyscript1.9 KB
scripts/output_registry.pyscript8.9 KB
scripts/override_registry.pyscript2.9 KB
scripts/parameter_discovery.pyscript8.6 KB
scripts/parameters.pyscript10.0 KB
scripts/result_contract.pyscript548 B
scripts/scenario_runner.pyscript11.3 KB
scripts/scenario_schema.pyscript4.0 KB
scripts/setup_paths.pyscript11.2 KB
scripts/tv_cosim.mother8.5 KB
scripts/validate_run.pyscript6.1 KB
scripts/version_compatibility.pyscript2.0 KB

scripts/scenario_runner.py

View on GitHub
"""Generic scenario runner: YAML in -> compiled scenario -> (solver) ->
validated run + run_manifest.json.

This is the high-level entry point for ordinary CarSim scenarios. It delegates
all solver mechanics to carsim_batch (never re-implements them), resolves the
base by explicit name + SHA256 via base_registry, and validates results with
validate_run.check_run. The manifest records scenario, environment, artifact,
and validation facts for the run.

    python scripts/scenario_runner.py scenario.yaml --registry bases.local.json \
        --out runs --run
"""
import argparse
import json
import platform
import re
import shutil
import subprocess
import time
from dataclasses import asdict
from datetime import datetime, timezone
from pathlib import Path

import carsim_batch as cb
from base_registry import resolve_base, sha256
from parameters import ScalarOverride, coerce_structured_overrides
from scenario_schema import SimulationConfig, VehicleOverrides, load_scenario, validate_scenario
from validate_run import ValidationIssue, check_run
from version_compatibility import compatibility_status

MANIFEST_NAME = "run_manifest.json"


def utc_now():
    return datetime.now(timezone.utc).isoformat()


def _git_commit():
    try:
        proc = subprocess.run(["git", "rev-parse", "HEAD"], timeout=10,
                              capture_output=True, text=True,
                              cwd=Path(__file__).resolve().parents[1])
        return proc.stdout.strip() if proc.returncode == 0 else None
    except (OSError, subprocess.TimeoutExpired):
        return None


def compile_scenario(config, base_entry, prog, datadir, directory):
    """Snapshot the base and write override.par + simfile.sim into <directory>.

    Delegates generation to carsim_batch.make_scenario (single source of the
    override.par pattern). Returns compile info consumed by run/verify steps.
    """
    directory = Path(directory)
    directory.mkdir(parents=True, exist_ok=True)  # exclusivity enforced by run_scenario
    base_copy = directory / "base_Run_all.par"
    shutil.copyfile(base_entry["base_run_all"], base_copy)
    if sha256(base_copy) != base_entry["base_sha256"]:
        raise ValueError("Base changed during snapshot")
    simulation = SimulationConfig(**config["simulation"])
    vehicle = VehicleOverrides(**config.get("vehicle", {}))
    overrides = coerce_structured_overrides(config.get("parameters", []))
    scalar = [item for item in overrides if isinstance(item, ScalarOverride)]
    structured = [item for item in overrides if not isinstance(item, ScalarOverride)]
    outputs = [n for n in config["outputs"]["channels"] if n != "Time"]
    if config.get("validation", {}).get("minimum_speed_mps") and "Vx" not in outputs:
        outputs.append("Vx")
    simfile = cb.make_scenario(
        str(directory), str(base_copy), prog, datadir, config=simulation,
        speed_rows=config["maneuver"]["speed_kmh"],
        steer_rows=config["maneuver"]["steering_deg"], mu=config["road"]["friction"],
        vehicle_overrides=vehicle, scalar_overrides=scalar,
        structured_overrides=structured, outputs=outputs,
        product_version=base_entry["carsim_version"])
    expected = dict(vehicle.keywords())
    for override in scalar:
        expected[override.keyword] = {"value": override.value,
                                      "echo_validation": override.echo_validation}
    expected.update({"TSTEP": simulation.dt, "TSTOP": simulation.duration, "IPRINT": 1})
    capabilities = []
    for override in overrides:
        capability = override.capability
        capabilities.append({
            "kind": capability.kind,
            "keyword": capability.keyword or getattr(override, "keyword", None),
            "dataset_family": capability.dataset_family,
            "verification": capability.verification.value,
            "evidence": capability.evidence,
        })
    return {"directory": directory, "simfile": simfile, "simulation": simulation,
            "outputs": outputs, "expected_parameters": expected,
            "base_copy": base_copy, "override_capabilities": capabilities}


def verify_compiled(directory, info, base_entry):
    """Compile-time checks on the generated files (before any solver call)."""
    issues = []
    add = lambda code, msg: issues.append(ValidationIssue("error", code, msg))
    par_text = (Path(directory) / "override.par").read_text(encoding="utf-8", errors="replace")
    sim_text = Path(info["simfile"]).read_text(encoding="utf-8", errors="replace")
    tstep_par = re.search(r"^TSTEP\s+([^\s]+)", par_text, re.M)
    tstep_sim = re.search(r"^EXT_MODEL_STEP\s+([^\s]+)", sim_text, re.M)
    if not tstep_par or not tstep_sim or float(tstep_par.group(1)) != float(tstep_sim.group(1)):
        add("dt_mismatch", "TSTEP (override.par) must equal EXT_MODEL_STEP (simfile.sim)")
    dll = re.search(r"^DLLFILE\s+(.+)$", sim_text, re.M)
    if not dll or "carsim_64" not in dll.group(1).lower():
        add("dll_not_64bit", "DLLFILE must pin the 64-bit solver (carsim_64.dll)")
    version = re.search(r"^PRODUCT_VER\s+([^\s]+)", sim_text, re.M)
    if not version or version.group(1) != base_entry["carsim_version"]:
        add("version_unresolved", "PRODUCT_VER missing or disagrees with the pinned base version")
    if not re.search(r"^WRT_", par_text, re.M):
        add("empty_outputs", "override.par declares no WRT_ output channels")
    if sha256(info["base_copy"]) != base_entry["base_sha256"]:
        add("base_changed", "Base snapshot hash no longer matches the registry binding")
    return issues


def _artifacts(directory):
    names = {"override_par": "override.par", "simfile": "simfile.sim",
             "run_csv": "run.csv", "run_echo": "run_echo.par",
             "run_log": "run_log.txt", "solver_stdout": "solver_stdout.txt",
             "base_run_all": "base_Run_all.par", "scenario": "scenario.yaml"}
    return {key: str(directory / name) for key, name in names.items()
            if (directory / name).is_file()}


def run_scenario(scenario, registry, output_root, prog=None, datadir=None,
                 execute=False, timeout=600):
    """Compile (and optionally run + validate) one generic scenario.

    <scenario> is a path to YAML/JSON or an already-validated config dict.
    Returns the scenario directory; the manifest lives next to it as
    run_manifest.json.
    """
    if isinstance(scenario, (str, Path)):
        config = load_scenario(scenario)
    else:
        config = validate_scenario(scenario)
    prog, datadir, _ = cb.resolve_paths(prog, datadir, require=("prog", "datadir"))
    base_entry = resolve_base(registry, config["base"]["name"], prog)
    directory = Path(output_root).resolve() / config["scenario"]["id"]
    if directory.exists():
        raise FileExistsError("Scenario directory already exists: %s" % directory)
    directory.mkdir(parents=True)
    import yaml
    (directory / "scenario.yaml").write_text(
        yaml.safe_dump(config, sort_keys=False, allow_unicode=True), encoding="utf-8")

    cli = Path(prog) / "Programs" / "VS_SolverWrapper_CLI_64.exe"
    dll = Path(prog) / "Programs" / "solvers" / "carsim_64.dll"
    version_status = compatibility_status(base_entry["carsim_version"])
    manifest = {
        "manifest_version": 1,
        "run": {"id": config["scenario"]["id"], "created_utc": utc_now(),
                "started_utc": None, "finished_utc": None, "status": "preparing"},
        "carsim": {"version": base_entry["carsim_version"],
                   "version_verified": version_status.verified,
                   "compatibility_warning": version_status.warning,
                   "verified_features": sorted(version_status.features), "prog": str(prog),
                   "datadir": str(datadir), "solver": str(cli), "dll": str(dll),
                   "solver_sha256": sha256(cli), "dll_sha256": sha256(dll)},
        "base": {"name": base_entry["name"],
                 "base_run_all": base_entry["base_run_all"],
                 "sha256": base_entry["base_sha256"]},
        "scenario": config,
        "artifacts": {}, "input_sha256": {}, "output_sha256": {},
        "validation": None,
        "provenance": {"python": platform.python_version(),
                       "platform": platform.platform(),
                       "git_commit": _git_commit()},
    }
    manifest_path = directory / MANIFEST_NAME

    def save():
        manifest_path.write_text(json.dumps(manifest, indent=2, allow_nan=False) + "\n",
                                 encoding="utf-8")

    try:
        save()
        info = compile_scenario(config, base_entry, prog, datadir, directory)
        manifest["override_capabilities"] = info["override_capabilities"]
        issues = verify_compiled(directory, info, base_entry)
        if issues:
            raise ValueError("Compile check failed: %s" % "; ".join(
                "%s: %s" % (i.code, i.message) for i in issues))
        manifest["input_sha256"] = {n: sha256(directory / n)
                                    for n in ("scenario.yaml", "override.par", "simfile.sim",
                                              "base_Run_all.par")}
        manifest["run"]["status"] = "compiled"
        save()
        if not execute:
            return directory
        manifest["run"]["status"] = "running"
        manifest["run"]["started_utc"] = utc_now()
        save()
        started = time.time()
        stdout = cb.run_solver(info["simfile"], prog, timeout)
        (directory / "solver_stdout.txt").write_text(stdout, encoding="utf-8")
        validation = check_run(directory, info["simulation"], info["outputs"],
                               started, info["expected_parameters"],
                               **(config.get("validation") or {}),
                               solver_stdout=stdout)
        manifest["validation"] = {"passed": validation.passed,
                                  "issues": [asdict(i) for i in validation.issues],
                                  "metrics": validation.metrics}
        if not validation.passed:
            first = validation.errors()[0]
            raise ValueError("%s: %s" % (first.code, first.message))
        manifest["output_sha256"] = {p.name: sha256(p) for p in directory.iterdir()
                                     if p.is_file() and p.name not in
                                     {MANIFEST_NAME, *manifest["input_sha256"]}}
        manifest["run"]["status"] = "passed"
        return directory
    except Exception as exc:
        manifest["run"]["status"] = "failed"
        manifest["error"] = "%s: %s" % (type(exc).__name__, exc)
        raise
    finally:
        manifest["run"]["finished_utc"] = utc_now()
        manifest["artifacts"] = _artifacts(directory)
        save()


def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("scenario", help="scenario YAML/JSON path")
    parser.add_argument("--registry", required=True, help="base registry JSON")
    parser.add_argument("--out", required=True, help="output root directory")
    parser.add_argument("--prog")
    parser.add_argument("--datadir")
    parser.add_argument("--run", action="store_true", help="execute the solver; default compiles only")
    parser.add_argument("--timeout", type=float, default=600)
    args = parser.parse_args()
    print(run_scenario(args.scenario, args.registry, args.out,
                       args.prog, args.datadir, args.run, args.timeout))


if __name__ == "__main__":
    main()
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall