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/output_registry.py

View on GitHub
"""Verified output metadata and deterministic output discovery.

Discovery returns evidence-bearing candidates. It never turns an unfamiliar
natural-language phrase into an invented CarSim channel name.
"""
import csv
import re
from collections.abc import Iterable, Sequence
from dataclasses import dataclass
from math import pi
from pathlib import Path

from carsim_errors import OutputChannelError
from discovery_query import DiscoveryQuery, ascii_query_terms, normalized_terms

VALID_OUTPUT_CATEGORIES = frozenset({
    "time", "vehicle_state", "wheel", "tire", "suspension", "steering",
    "brake", "powertrain", "driver", "road", "aero", "control",
    "environment", "other",
})


@dataclass(frozen=True)
class OutputSpec:
    """Unit and meaning metadata for a verified CarSim output channel."""

    name: str
    source_unit: str | None
    si_unit: str | None
    scale: float | None
    category: str
    description: str | None = None
    verified: bool = True
    source: str = "CarSim native run.csv"

    @property
    def native_unit(self) -> str | None:
        """Compatibility alias for ``source_unit``."""
        return self.source_unit


@dataclass(frozen=True)
class OutputCandidate:
    """One channel candidate with the evidence that produced it."""

    channel: str
    source: str
    matched_text: str
    reason: str
    verification_state: str
    spec: OutputSpec | None = None

    @property
    def name(self) -> str:
        """Compatibility alias for ``channel``."""
        return self.channel

    @property
    def evidence(self) -> str:
        """Compatibility alias for ``matched_text``."""
        return self.matched_text

    @property
    def confidence(self) -> str:
        """Compatibility confidence derived from verification state."""
        return "verified" if self.verification_state == "registered" else "weak"


OUTPUT_REGISTRY: dict[str, OutputSpec] = {}


def _register(names: str, native: str, si: str, scale: float = 1.0,
              category: str = "other", description: str | None = None) -> None:
    if category not in VALID_OUTPUT_CATEGORIES:
        raise ValueError(f"Unknown output category: {category}")
    for name in names.split():
        OUTPUT_REGISTRY[name] = OutputSpec(
            name, native, si, scale, category, description)


_register("Time", "s", "s", category="time", description="simulation time")
_register("Vx Vy", "km/h", "m/s", 1 / 3.6, "vehicle_state", "vehicle velocity")
_register("Ax Ay", "g", "m/s^2", 9.80665, "vehicle_state", "vehicle acceleration")
_register("AVz", "deg/s", "rad/s", pi / 180, "vehicle_state", "vehicle yaw rate")
_register("Roll Pitch Yaw", "deg", "rad", pi / 180, "vehicle_state", "vehicle attitude")
_register("Xo Yo Zo", "m", "m", category="vehicle_state", description="vehicle position")
_register("Station", "m", "m", category="road", description="road station")
for _corner in ("L1", "R1", "L2", "R2"):
    _register("Vx_" + _corner, "km/h", "m/s", 1 / 3.6, "wheel", "wheel-center speed")
    _register("Steer_" + _corner, "deg", "rad", pi / 180, "steering", "road-wheel steer angle")
    _register("AVy_" + _corner, "rpm", "rad/s", 2 * pi / 60, "wheel", "wheel angular speed")
    _register("My_Dr_" + _corner, "N*m", "N*m", category="powertrain", description="drive torque")
    _register("My_Bk_" + _corner, "N*m", "N*m", category="brake", description="brake torque")
    _register(" ".join(p + _corner for p in ("Fx_", "Fy_", "Fz_")),
              "N", "N", category="tire", description="tire force")
    _register("Kappa_" + _corner, "1", "1", category="tire", description="tire longitudinal slip")
    _register("Alpha_" + _corner, "deg", "rad", pi / 180, "tire", "tire slip angle")
_register("AV_Mt_D1_L AV_Mt_D1_R AV_Mt_D2_L AV_Mt_D2_R",
          "rpm", "rad/s", 2 * pi / 60, "powertrain", "motor speed")

# Only aliases backed by verified registry entries belong here.
OUTPUT_ALIASES: dict[str, Sequence[str]] = {
    "yaw rate": ("AVz",),
    "vehicle speed": ("Vx",),
    "longitudinal vehicle speed": ("Vx",),
}

# These map physical descriptions to English physical search phrases, never to
# a CarSim channel. A literal channel still has to be found in an artifact.
OUTPUT_PHYSICAL_TERMS: dict[str, Sequence[str]] = {
    "前悬架垂向行程": ("front suspension travel", "front suspension vertical travel"),
    "方向盘转角": ("steering wheel angle",),
    "发动机转速": ("engine speed", "engine rpm"),
}

# WRT spellings differ from CSV spellings for these two known channels.
WRT_ALIASES = {"ROLL": "Roll", "PITCH": "Pitch"}
UNRELIABLE_COLS = ("Lat_Veh", "Lat_Targ")


def output_spec(name: str) -> OutputSpec:
    """Return verified metadata or fail closed when units are unknown."""
    canonical = WRT_ALIASES.get(name, name)
    try:
        return OUTPUT_REGISTRY[canonical]
    except KeyError:
        raise OutputChannelError(
            f"Unregistered channel {name!r}; discover and verify its native "
            "unit before adding it to OUTPUT_REGISTRY") from None


def resolve_output_alias(query: str) -> list[OutputSpec]:
    """Resolve an exact verified alias; unfamiliar text returns an empty list."""
    normalized = " ".join(str(query).casefold().split())
    if query in OUTPUT_REGISTRY or query in WRT_ALIASES:
        return [output_spec(query)]
    names = OUTPUT_ALIASES.get(normalized, ())
    return [output_spec(name) for name in names]


def normalize_output_query(
    query: str, search_terms: Iterable[str] | None = None
) -> DiscoveryQuery:
    """Normalize a multilingual query without mapping it to an invented channel."""
    original = " ".join(str(query).strip().split())
    aliases = tuple(spec.name for spec in resolve_output_alias(original))
    if search_terms is not None:
        terms = normalized_terms(search_terms)
    else:
        terms = normalized_terms(OUTPUT_PHYSICAL_TERMS.get(original, ()))
        if not terms:
            terms = ascii_query_terms(original)
    return DiscoveryQuery(original, terms, aliases)


def _source_files(sources: Iterable[str | Path]) -> Iterable[Path]:
    for source in sources:
        path = Path(source)
        if path.is_file():
            yield path
        elif path.is_dir():
            yield from (p for p in path.rglob("*") if p.is_file() and
                        p.suffix.lower() in {".csv", ".par", ".txt", ".sim"})


def find_output_candidates(
    query: str,
    sources: Iterable[str | Path] = (),
    limit: int = 50,
    *,
    search_terms: Iterable[str] | None = None,
    artifacts: Iterable[str | Path] | None = None,
) -> list[OutputCandidate]:
    """Find output candidates from verified aliases and supplied artifacts.

    Artifact discoveries are candidates, not verified facts. Callers must
    confirm native units in an echo/data definition before registration/use.
    """
    normalized = normalize_output_query(query, search_terms)
    if normalized.aliases:
        return [
            OutputCandidate(
                name,
                "verified registry",
                normalized.original,
                "exact verified alias or registered channel",
                "registered",
                output_spec(name),
            )
            for name in normalized.aliases
        ]
    if not normalized.search_terms:
        return []
    artifact_sources = tuple(sources) + tuple(artifacts or ())
    found: dict[str, OutputCandidate] = {}
    for path in _source_files(Path(p) for p in artifact_sources):
        try:
            if path.suffix.lower() == ".csv":
                with path.open("r", encoding="utf-8-sig", errors="ignore", newline="") as handle:
                    evidence_lines = [",".join(next(csv.reader(handle), []))]
            else:
                evidence_lines = path.read_text(encoding="utf-8", errors="ignore").splitlines()
        except OSError:
            continue
        for line in evidence_lines:
            folded = line.casefold()
            matched = next((term for term in normalized.search_terms if term in folded), None)
            if matched is None:
                continue
            tokens = re.findall(r"\b(?:WRT_)?[A-Za-z][A-Za-z0-9_]*\b", line)
            for token in tokens:
                name = token[4:] if token.upper().startswith("WRT_") else token
                canonical = WRT_ALIASES.get(name, name)
                spec = OUTPUT_REGISTRY.get(canonical)
                if spec is None and "_" not in name:
                    continue
                found.setdefault(
                    canonical,
                    OutputCandidate(
                        canonical,
                        str(path),
                        line.strip(),
                        f"literal artifact match for physical search term {matched!r}",
                        "registered" if spec else "artifact_match",
                        spec,
                    ),
                )
                if len(found) >= limit:
                    return list(found.values())
    return list(found.values())
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