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

View on GitHub
"""Read-only CarSim database exploration.

Turns the grep recipes into a Python API an agent can call directly:
find datasets by #FullDataName, inspect dataset identity, follow PARSFILE
links, locate keywords, free-text search, and check what a run actually
echoed. Every function only reads; nothing here writes, replaces or renames.

Workflow for unknown parameters: natural language -> search_database_text /
find_datasets -> candidate keyword -> confirm unit & context in the dataset
and/or run_echo (inspect_echo_keyword) -> typed VehicleOverrides /
ScalarOverride or unsafe_extra_lines. Never guess a keyword.

These tools parse the documented plain-text surface of .par files only
(header comments, PARSFILE lines, keyword lines, tables). They are not a
complete CarSim dataset parser.
"""
import argparse
import json
import os
import re
from dataclasses import dataclass, field
from pathlib import Path
from typing import Dict, List, Optional

from carsim_errors import DatasetResolutionError

HEADER_READ_LINES = 60
_KEYSPLIT = re.compile(r"^#(\w+)\s*(.*)$")


def _keymatch(line):
    match = _KEYSPLIT.match(line.strip())
    return (match.group(1), match.group(2).strip()) if match else None


def _par_files(datadir, roots=None):
    """Yield .par file paths under datadir, restricted to roots (subdirectory
    names or paths) when given."""
    datadir = Path(datadir).resolve()
    if roots:
        seen = set()
        for root in roots:
            root = datadir / root if not Path(root).is_absolute() else Path(root)
            root = root.resolve()
            try:
                root.relative_to(datadir)
            except ValueError:
                raise DatasetResolutionError(
                    "Database search roots must remain inside DATADIR: %s" % root) from None
            if root in seen or not root.exists():
                continue
            seen.add(root)
            for base, _, files in os.walk(root):
                for name in files:
                    if name.lower().endswith(".par"):
                        yield Path(base) / name
    else:
        for base, _, files in os.walk(datadir):
            for name in files:
                if name.lower().endswith(".par"):
                    yield Path(base) / name


def _library_of(datadir, path):
    try:
        return Path(path).resolve().relative_to(Path(datadir).resolve()).parts[0]
    except (ValueError, IndexError):
        return ""


def find_datasets(datadir, query, roots=None, limit=200):
    """Datasets whose #FullDataName contains <query> (case-insensitive).

    Returns [{"path", "full_data_name", "library"}]; newest/first ordering is
    filesystem order - selection is the caller's explicit decision.
    """
    needle = str(query).casefold()
    hits = []
    for path in _par_files(datadir, roots):
        try:
            with open(path, "r", encoding="utf-8", errors="ignore") as handle:
                head = [handle.readline() for _ in range(HEADER_READ_LINES)]
        except OSError:
            continue
        for line in head:
            if line.startswith("#FullDataName"):
                full = line.split(None, 1)[1].strip() if len(line.split(None, 1)) > 1 else ""
                if needle in full.casefold():
                    hits.append({"path": str(path), "full_data_name": full,
                                 "library": _library_of(datadir, path)})
                break
        if len(hits) >= limit:
            break
    return hits


def get_dataset_identity(path):
    """Header identity of a dataset file: #FileID/#DataSet/#Category/
    #FullDataName/#Modified ... (whatever the header carries). No UUID is
    required for use - #FullDataName is the human identity."""
    identity = {}
    try:
        with open(path, "r", encoding="utf-8", errors="ignore") as handle:
            for _ in range(HEADER_READ_LINES):
                line = handle.readline()
                if not line:
                    break
                if line.startswith("#"):
                    match = _keymatch(line)
                    if match:
                        identity[match[0]] = match[1]
                elif identity:
                    break
    except OSError as exc:
        raise ValueError("Cannot read dataset %s: %s" % (path, exc)) from exc
    return identity


def get_parsfile_links(path, datadir=None):
    """PARSFILE references of a dataset: [{"raw", "path", "exists"}].
    Relative references resolve against datadir when given, else the file's
    own directory."""
    links = []
    base = Path(datadir) if datadir else Path(path).parent
    with open(path, "r", encoding="utf-8", errors="ignore") as handle:
        for line in handle:
            if line.startswith("PARSFILE"):
                raw = line.split(None, 1)[1].strip() if len(line.split(None, 1)) > 1 else ""
                if not raw:
                    continue
                candidate = Path(raw)
                if not candidate.is_absolute():
                    candidate = base / candidate
                links.append({"raw": raw, "path": str(candidate),
                              "exists": candidate.is_file()})
    return links


def resolve_dataset_tree(root, datadir=None, max_depth=3, allow_external=False):
    """Recursive PARSFILE expansion with cycle detection and a depth limit.
    Nodes: {"path", "identity", "links": [child nodes], "cycle": bool}."""
    data_root = Path(datadir).resolve() if datadir else None

    def walk(path, depth, stack, external=False):
        resolved = Path(path).resolve()
        node = {"path": str(resolved),
                "identity": get_dataset_identity(resolved),
                "links": [], "cycle": resolved in stack,
                "external": external}
        if node["cycle"] or depth >= max_depth:
            return node
        stack = stack | {resolved}
        for link in get_parsfile_links(resolved, datadir):
            child = Path(link["path"]).resolve()
            if child.is_file():
                child_external = bool(data_root and not _inside(child, data_root))
                if child_external and not allow_external:
                    node["links"].append({
                        "path": str(child),
                        "identity": {},
                        "links": [],
                        "cycle": child in stack,
                        "external": True,
                    })
                else:
                    node["links"].append(
                        walk(child, depth + 1, stack, child_external or external)
                    )
        return node

    if not Path(root).is_file():
        raise ValueError("Not a dataset file: %s" % root)
    return walk(root, 0, frozenset())


@dataclass(frozen=True)
class DatasetNode:
    """One dataset identity in a dependency graph."""

    path: str
    full_data_name: Optional[str]
    category: Optional[str]
    exists: bool = True
    external: bool = False


@dataclass(frozen=True)
class DatasetEdge:
    """One parsed reference between datasets."""

    source: str
    target: str
    keyword: str


@dataclass(frozen=True)
class GraphIssue:
    """Non-fatal graph condition requiring caller attention."""

    code: str
    path: str
    message: str


@dataclass
class DatasetGraph:
    """Explainable dependency graph and its structural warnings."""

    root: str
    nodes: Dict[str, DatasetNode] = field(default_factory=dict)
    edges: List[DatasetEdge] = field(default_factory=list)
    issues: List[GraphIssue] = field(default_factory=list)

    def issues_by_code(self, code: str) -> List[GraphIssue]:
        """Return graph issues with one stable code."""
        return [issue for issue in self.issues if issue.code == code]


def _inside(path: Path, root: Path) -> bool:
    try:
        path.resolve().relative_to(root.resolve())
        return True
    except ValueError:
        return False


def build_dependency_graph(root: str | Path, datadir: str | Path | None = None,
                           allow_external: bool = False,
                           max_depth: int = 10) -> DatasetGraph:
    """Build a PARSFILE dependency graph without modifying any dataset.

    Cycles, repeated references, missing targets, traversal depth limits and
    references outside DATADIR are retained as explicit issues. External files
    are not opened unless ``allow_external=True``.
    """
    root_path = Path(root).resolve()
    if not root_path.is_file():
        raise DatasetResolutionError("Not a dataset file: %s" % root)
    if max_depth < 0:
        raise ValueError("max_depth must be nonnegative")
    data_root = Path(datadir).resolve() if datadir else None
    graph = DatasetGraph(str(root_path))
    seen = set()

    def add_node(path: Path, exists: bool = True, external: bool = False,
                 inspect: bool = True) -> None:
        key = str(path.resolve())
        if key in graph.nodes:
            return
        identity = get_dataset_identity(path) if exists and inspect else {}
        graph.nodes[key] = DatasetNode(
            key,
            identity.get("FullDataName"),
            identity.get("Category"),
            exists,
            external,
        )

    def walk(path: Path, depth: int, stack: tuple[Path, ...]) -> None:
        resolved = path.resolve()
        node_external = bool(data_root and not _inside(resolved, data_root))
        add_node(resolved, external=node_external)
        seen.add(resolved)
        links = get_parsfile_links(resolved, data_root)
        if links and depth >= max_depth:
            graph.issues.append(GraphIssue(
                "depth_limit", str(resolved),
                "Dependencies were not traversed beyond max_depth=%s" % max_depth))
            return
        for link in links:
            target = Path(link["path"]).resolve()
            graph.edges.append(DatasetEdge(str(resolved), str(target), "PARSFILE"))
            external = bool(data_root and not _inside(target, data_root))
            if external:
                graph.issues.append(GraphIssue(
                    "external_reference", str(target),
                    "Reference resolves outside DATADIR"))
            if not target.is_file():
                add_node(target, False, external)
                graph.issues.append(GraphIssue(
                    "missing_reference", str(target),
                    "Referenced dataset does not exist"))
                continue
            if external and not allow_external:
                add_node(target, True, True, inspect=False)
                continue
            if target in stack or target == resolved:
                add_node(target, external=external)
                graph.issues.append(GraphIssue(
                    "cycle", str(target), "Dependency cycle detected"))
                continue
            if target in seen:
                graph.issues.append(GraphIssue(
                    "duplicate_dataset", str(target),
                    "Dataset is referenced by more than one traversal path"))
                continue
            walk(target, depth + 1, (*stack, resolved))

    walk(root_path, 0, ())
    return graph


def format_dependency_tree(graph: DatasetGraph) -> str:
    """Render a compact tree while preserving cycles/duplicates as markers."""
    children = {}
    for edge in graph.edges:
        children.setdefault(edge.source, []).append(edge.target)
    lines = []
    expanded = set()

    def label(path: str) -> str:
        node = graph.nodes[path]
        return node.full_data_name or Path(path).name

    def render(path: str, prefix: str = "", is_last: bool = True) -> None:
        marker = "└─ " if is_last else "├─ "
        lines.append((prefix + marker if prefix else "") + label(path))
        if path in expanded:
            lines[-1] += " [duplicate/cycle]"
            return
        expanded.add(path)
        kids = children.get(path, [])
        next_prefix = prefix + ("   " if is_last else "│  ") if prefix else ""
        for index, child in enumerate(kids):
            render(child, next_prefix, index == len(kids) - 1)

    render(graph.root)
    if graph.issues:
        lines.append("Warnings: " + ", ".join(sorted({i.code for i in graph.issues})))
    return "\n".join(lines)


def find_keyword(datadir, keyword, roots=None, limit=50):
    """Datasets containing <keyword> as a line-initial token (case-insensitive).
    Returns [{"path", "library", "full_data_name", "count", "first_line"}]."""
    pattern = re.compile(r"^\s*" + re.escape(str(keyword)) + r"\b", re.I)
    name_pattern = re.compile(r"^#FullDataName\s+(.+)$", re.I)
    hits = []
    for path in _par_files(datadir, roots):
        count, first_line, full_name = 0, None, ""
        try:
            with open(path, "r", encoding="utf-8", errors="ignore") as handle:
                for line in handle:
                    if pattern.match(line):
                        count += 1
                        if first_line is None:
                            first_line = line.strip()
                    elif name_pattern.match(line) and not full_name:
                        full_name = name_pattern.match(line).group(1).strip()
        except OSError:
            continue
        if count:
            hits.append({"path": str(path), "library": _library_of(datadir, path),
                         "full_data_name": full_name, "count": count,
                         "first_line": first_line})
            if len(hits) >= limit:
                break
    return hits


def search_database_text(datadir, text, roots=None, limit=100):
    """Case-insensitive free-text search across dataset files (grep analogue).
    Returns [{"path", "library", "line_number", "line"}]."""
    needle = str(text).casefold()
    hits = []
    for path in _par_files(datadir, roots):
        try:
            with open(path, "r", encoding="utf-8", errors="ignore") as handle:
                for number, line in enumerate(handle, 1):
                    if needle in line.casefold():
                        hits.append({"path": str(path),
                                     "library": _library_of(datadir, path),
                                     "line_number": number,
                                     "line": line.strip()})
                        if len(hits) >= limit:
                            return hits
        except OSError:
            continue
    return hits


def inspect_echo_keyword(run_echo, keyword):
    """Lines of a run_echo.par that carry <keyword>: actual parsed values and
    the trailing comment. Returns [{"keyword", "values", "value", "comment",
    "line"}]. This is the post-run proof of what the solver actually used."""
    pattern = re.compile(r"^\s*" + re.escape(str(keyword)) + r"\b(.*)$", re.I)
    number = re.compile(r"[-+]?[0-9]*\.?[0-9]+(?:[eE][-+]?[0-9]+)?")
    out = []
    with open(run_echo, "r", encoding="utf-8", errors="ignore") as handle:
        for line in handle:
            match = pattern.match(line)
            if not match:
                continue
            rest = match.group(1)
            comment = ""
            if "!" in rest:
                rest, comment = rest.split("!", 1)
                comment = comment.strip()
            values = [float(v) for v in number.findall(rest)]
            out.append({"keyword": keyword, "values": values,
                        "value": values[-1] if values else None,
                        "comment": comment, "line": line.strip()})
    return out


def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("command",
                        choices=["find-dataset", "find-keyword", "search",
                                 "tree", "identity", "echo"])
    parser.add_argument("query", help="dataset text / keyword / dataset path")
    parser.add_argument("--datadir", help="database root (for find/search/tree)")
    parser.add_argument("--roots", nargs="*", help="restrict scan to these datadir subdirectories")
    parser.add_argument("--limit", type=int, default=50)
    args = parser.parse_args()

    if args.command == "find-dataset":
        results = find_datasets(args.datadir, args.query, args.roots, args.limit)
    elif args.command == "find-keyword":
        results = find_keyword(args.datadir, args.query, args.roots, args.limit)
    elif args.command == "search":
        results = search_database_text(args.datadir, args.query, args.roots, args.limit)
    elif args.command == "tree":
        results = resolve_dataset_tree(args.query, args.datadir)
    elif args.command == "identity":
        results = get_dataset_identity(args.query)
    else:
        results = inspect_echo_keyword(args.query, args.datadir or "")
    print(json.dumps(results, indent=2))


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