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

View on GitHub
"""Deterministic physical-term to CarSim parameter candidate discovery."""
import re
from dataclasses import dataclass, field
from pathlib import Path

import database_tools as database
from discovery_query import DiscoveryQuery, ascii_query_terms, normalized_terms
from parameters import KEYWORD_RE, PARAMETER_REGISTRY

CONFIDENCE_LEVELS = frozenset({"verified", "strong", "weak"})

# Every alias maps only to a registry entry with recorded verification evidence.
PARAMETER_ALIASES = {
    "sprung mass": ("M_SU", "CarSim 2024.0 run-echo verification"),
    "sprung-body yaw inertia": ("IZZ_SU", "CarSim 2024.0 run-echo verification"),
    "yaw inertia": ("IZZ_SU", "CarSim 2024.0 run-echo verification"),
    "sprung-body cg height": ("H_CG_SU", "CarSim 2024.0 run-echo verification"),
}

PARAMETER_PHYSICAL_TERMS = {
    "前悬架弹簧刚度": ("front suspension spring stiffness", "front spring stiffness"),
    "转向系统刚度": ("steering stiffness", "steering system stiffness"),
}


@dataclass(frozen=True)
class ParameterCandidate:
    """One evidence-bearing parameter candidate."""

    keyword: str
    dataset_path: str
    dataset_name: str | None
    nearby_text: str | None
    unit_hint: str | None
    category: str | None
    confidence: str
    reason: str

    def __post_init__(self) -> None:
        if self.confidence not in CONFIDENCE_LEVELS:
            raise ValueError("confidence must be verified, strong, or weak")


@dataclass
class ParameterDiscoveryReport:
    """Ordered candidates; only registry/alias proof sets ``resolved``."""

    query: str
    candidates: list[ParameterCandidate] = field(default_factory=list)
    unresolved: bool = False
    search_terms: tuple[str, ...] = ()

    @property
    def resolved(self) -> ParameterCandidate | None:
        verified = [c for c in self.candidates if c.confidence == "verified"]
        return verified[0] if len(verified) == 1 else None

    @property
    def ambiguous(self) -> bool:
        viable = [c for c in self.candidates if c.confidence in {"verified", "strong"}]
        return len(viable) > 1


def _registry_candidate(keyword: str, reason: str) -> ParameterCandidate:
    spec = PARAMETER_REGISTRY[keyword]
    return ParameterCandidate(
        keyword, "", spec.dataset_family, spec.description, spec.native_unit,
        spec.category, "verified", reason)


def _identity(path: str) -> tuple[str | None, str | None]:
    identity = database.get_dataset_identity(path)
    return identity.get("FullDataName"), identity.get("Category")


def normalize_parameter_query(
    query: str, search_terms: list[str] | tuple[str, ...] | None = None
) -> DiscoveryQuery:
    """Normalize physical terms while preserving the no-guessed-keyword rule."""
    original = " ".join(str(query).strip().split())
    alias = PARAMETER_ALIASES.get(original.casefold())
    aliases = (alias[0],) if alias else ()
    if search_terms is not None:
        terms = normalized_terms(search_terms)
    else:
        terms = normalized_terms(PARAMETER_PHYSICAL_TERMS.get(original, ()))
        if not terms:
            terms = ascii_query_terms(original)
    return DiscoveryQuery(original, terms, aliases)


def discover_parameter(query: str, datadir: str | Path | None = None,
                       root_dataset: str | Path | None = None,
                       run_echo: str | Path | None = None,
                       limit: int = 50, *,
                       search_terms: list[str] | tuple[str, ...] | None = None
                       ) -> ParameterDiscoveryReport:
    """Apply the deterministic discovery order without guessing.

    A unique database hit remains ``strong`` until its unit/meaning is checked
    against the actual dataset and run echo; it is not silently promoted.
    """
    normalized = normalize_parameter_query(query, search_terms)
    text = normalized.original
    upper = text.upper()
    if upper in PARAMETER_REGISTRY:
        return ParameterDiscoveryReport(
            text, [_registry_candidate(upper, "exact PARAMETER_REGISTRY match")],
            search_terms=normalized.search_terms)
    if normalized.aliases:
        return ParameterDiscoveryReport(
            text,
            [_registry_candidate(normalized.aliases[0], "verified alias")],
            search_terms=normalized.search_terms,
        )
    if not datadir or not normalized.search_terms:
        return ParameterDiscoveryReport(
            text, [], True, search_terms=normalized.search_terms)

    allowed_paths = None
    if root_dataset:
        graph = database.build_dependency_graph(root_dataset, datadir)
        allowed_paths = {str(Path(path).resolve()) for path in graph.nodes}

    candidates = {}

    # 3. Exact keyword search.
    for term in normalized.search_terms:
        if not KEYWORD_RE.fullmatch(term):
            continue
        for hit in database.find_keyword(datadir, term, limit=limit):
            if allowed_paths is not None and str(Path(hit["path"]).resolve()) not in allowed_paths:
                continue
            name, category = _identity(hit["path"])
            keyword = term.upper()
            candidates[(keyword, hit["path"])] = ParameterCandidate(
                keyword, hit["path"], name, hit["first_line"], None, category,
                "strong", "exact line-initial keyword match")

    # 4. Dataset text search. Extract only a literal line-initial token.
    dataset_hits = []
    text_hits = []
    for term in normalized.search_terms:
        dataset_hits.extend(database.find_datasets(datadir, term, limit=limit))
        text_hits.extend(database.search_database_text(datadir, term, limit=limit))
    for hit in dataset_hits[:limit]:
        if allowed_paths is not None and str(Path(hit["path"]).resolve()) not in allowed_paths:
            continue
        try:
            lines = Path(hit["path"]).read_text(
                encoding="utf-8", errors="ignore").splitlines()
        except OSError:
            continue
        for line in lines:
            match = re.match(r"\s*([A-Za-z][A-Za-z0-9_]*)\b", line)
            if not match or line.lstrip().startswith("#"):
                continue
            keyword = match.group(1).upper()
            if keyword in {"PARSFILE", "END", "ENDTABLE"}:
                continue
            candidates.setdefault((keyword, hit["path"]), ParameterCandidate(
                keyword, hit["path"], hit["full_data_name"], line.strip(), None,
                hit.get("library"), "weak",
                "keyword in a dataset whose verified name matches the query"))
    for hit in text_hits[:limit]:
        if allowed_paths is not None and str(Path(hit["path"]).resolve()) not in allowed_paths:
            continue
        match = re.match(r"\s*([A-Za-z][A-Za-z0-9_]*)\b", hit["line"])
        if not match or hit["line"].lstrip().startswith("#"):
            continue
        keyword = match.group(1).upper()
        if keyword in {"PARSFILE", "END", "ENDTABLE"}:
            continue
        name, category = _identity(hit["path"])
        candidates.setdefault((keyword, hit["path"]), ParameterCandidate(
            keyword, hit["path"], name, hit["line"], None, category,
            "weak", "free-text dataset match; verify meaning and unit"))

    # 5 is represented by allowed_paths; 6 adds echo evidence for literal keywords.
    if run_echo:
        for term in normalized.search_terms:
            if not KEYWORD_RE.fullmatch(term):
                continue
            keyword = term.upper()
            for row in database.inspect_echo_keyword(run_echo, term):
                candidates[(keyword, str(run_echo))] = ParameterCandidate(
                    keyword, str(run_echo), "run echo", row["line"],
                    row["comment"] or None, None, "strong",
                    "keyword present in run echo; unit still requires confirmation")

    result = list(candidates.values())
    rank = {"verified": 0, "strong": 1, "weak": 2}
    result.sort(key=lambda item: (rank[item.confidence], item.keyword, item.dataset_path))
    return ParameterDiscoveryReport(
        text, result, not result, search_terms=normalized.search_terms)


def format_discovery_report(report: ParameterDiscoveryReport) -> str:
    """Format candidates for an agent/user decision."""
    if report.unresolved:
        return f"Unresolved parameter: {report.query}. No keyword was guessed."
    blocks = []
    for index, item in enumerate(report.candidates, 1):
        blocks.append(
            f"Candidate {index}\nkeyword: {item.keyword}\ndataset: "
            f"{item.dataset_name or item.dataset_path or 'verified registry'}\n"
            f"context: {item.nearby_text or '-'}\nunit: {item.unit_hint or 'unverified'}\n"
            f"confidence: {item.confidence}\nreason: {item.reason}")
    return "\n\n".join(blocks)
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