From 51987bd33d194c4ecafa3c6d271624078801d805 Mon Sep 17 00:00:00 2001 From: Arjun Rao Date: Sun, 20 Sep 2026 22:14:08 -0500 Subject: [PATCH] Point the agent docs at opt-solve and opt-trade, and record three traps The routing table and the docs index still described OptSim as sweeps plus a reverse lookup. So an agent asked to size a bar or compare two options would go to the wrong tool. They now name all three tools and say which question each one answers. Three traps cost real time during this work. They are now under common mistakes: - OpenModelica accepts an override of toe, camber or any mass value, and the override silently does nothing. - A consumer must not rewrite the sweep's committed _doe_config.yaml. It records the scope that opt-search needs. - Git Bash on Windows rewrites the /workspace paths that make passes to Docker. --- AGENTS.md | 24 +++++++++++++++++++++++- docs/README.md | 2 +- docs/architecture.md | 8 ++++++-- docs/workflows.md | 12 +++++++++++- 4 files changed, 41 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 247a66c..4d14f0b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,7 +11,7 @@ Don't read the whole folder. Route by task: | --- | --- | | Anything non-trivial, first time in the repo | [`docs/architecture.md`](docs/architecture.md) | | Running / building / testing something | [`docs/workflows.md`](docs/workflows.md) | -| Parameter sweeps, sensitivities, target-metrics → vehicle | [`docs/doe-reverse-engineering.md`](docs/doe-reverse-engineering.md) | +| Parameter sweeps and sensitivities, solving for a setup from target metrics, trade studies across standard sims (`opt-*`) | [`docs/doe-reverse-engineering.md`](docs/doe-reverse-engineering.md) | | Reduced 3/6/10/14DOF dynamics, QSS envelopes, BobLib correlation | [`docs/reduced-order-dynamics.md`](docs/reduced-order-dynamics.md) | | QSS racing lines, speed profiles, and transient laps | [`docs/lap-time-simulation.md`](docs/lap-time-simulation.md) | | Modelica missing, build fails, BobLib edits | [`docs/boblib-submodule.md`](docs/boblib-submodule.md) | @@ -75,6 +75,28 @@ above. Keep the set small; a stale doc is worse than no doc. [`docs/conventions.md`](docs/conventions.md#vertical-datum-z) and [`skills/shark-import/SKILL.md`](skills/shark-import/SKILL.md). +- **An OpenModelica `-override` can be accepted and do nothing.** Static toe and + camber feed the wheel's `toHub.R_rel` rotation matrix, which is evaluated at + compile time; every mass and CG value goes the same way through + `combineMassRecords`. The parameter still reports `isValueChangeable="true"`, + the override raises no warning, and the simulated car does not change. Only the + variables in `RUNTIME_SAFE_PATHS` (`_4_OptSim/StandardSens/pipeline/overrides.py`) + are proven to follow an override; anything else must be compiled. The runner + also silently drops an override name it cannot find in the init XML. Before + trusting a new override, read that file's comment on how to vet one. +- **OptSim is three tools, and picking the wrong one wastes hours.** + `opt-standard` samples a space to learn what matters, `opt-solve` inverts for the + setup that hits target metrics, `opt-trade` compares vehicles you name. None + finds a "best" car, and none replaces another. A consumer that needs variable + specs or compiled vehicles should use `pipeline/variants.py::VariantStore`, + never rewrite the sweep's committed `_doe_config.yaml`: that file records the + scope its population was built at, and `opt-search` relies on it. +- **Git Bash on Windows rewrites container paths.** `make` targets pass + `/workspace/...` to Docker, and MSYS turns that into + `C:/Program Files/Git/workspace/...`, so the run dies in seconds with a + file-not-found. Prefix the command with `MSYS_NO_PATHCONV=1`. The same + conversion mangles `git show origin/main:path`. + ## Verifying a change ```bash diff --git a/docs/README.md b/docs/README.md index a4fc4e0..a56a3a9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -11,7 +11,7 @@ Read in this order: | [architecture.md](architecture.md) | You need the `_0_` … `_5_` layer map and how data flows between them. Start here. | | [simulation-entrypoints.md](simulation-entrypoints.md) | You need to understand the fidelity levels and use cases of VehicleSim, EnvelopeSim, StandardSim, and FourPostSim — or you're publishing results and need to specify which workflow was used. | | [workflows.md](workflows.md) | You want to *run* something: app, standard studies, envelopes, sensitivities, tests. | -| [doe-reverse-engineering.md](doe-reverse-engineering.md) | You are doing DOE work — sweeping parameters or going backwards from target performance metrics to a car. Start here for `make opt-standard`. | +| [doe-reverse-engineering.md](doe-reverse-engineering.md) | You are doing OptSim work: sweeping parameters (`make opt-standard`), solving for the setup that hits target metrics (`make opt-solve`), or comparing named vehicles across standard sims (`make opt-trade`). It opens with which of the three to reach for. | | [reduced-order-dynamics.md](reduced-order-dynamics.md) | You are working on 3/6/10/14DOF transient models, QSS envelopes, or BobLib correlation. | | [lap-time-simulation.md](lap-time-simulation.md) | You are optimizing a QSS racing line/speed profile or running the same lap as a forward transient. | diff --git a/docs/architecture.md b/docs/architecture.md index c056d36..22d9005 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -56,11 +56,15 @@ GGV (grip-acceleration) and YMD (yaw moment diagram) generators. Quasi-steady ma Output: `generated_results/` (CSVs, PDFs) ### `_4_OptSim/` — sensitivities and DOE -- **`StandardSens/`**: sweep StandardSim studies over parameter ranges +- **`StandardSens/`**: sweep StandardSim studies over parameter ranges, solve for a + setup from target metrics (`solve_setup.py`), and compare named vehicles across + standard sims (`trade_study.py`). `pipeline/standards.py` is the registry of + VehicleSim standards one compiled vehicle can serve; `pipeline/variants.py` is the + content-addressed cache of compiled vehicles the solver and trade study share. - **`EnvelopeSens/`**: sweep envelope outputs (same ranges) - **`_shared/`**: console progress, tornado-plot rendering -See [doe-reverse-engineering.md](doe-reverse-engineering.md) for reverse-lookup (target metrics → car parameters). +See [doe-reverse-engineering.md](doe-reverse-engineering.md) for all three: the sweep and its reverse lookup, the setup solver, and trade studies. ### `_5_App/` — browser UI and HTTP server Main user entry point: `python -m _5_App.app` (port 8765). Pick/edit vehicle, generate Modelica, launch jobs, view logs and results. diff --git a/docs/workflows.md b/docs/workflows.md index 2c4a042..1be917e 100644 --- a/docs/workflows.md +++ b/docs/workflows.md @@ -111,11 +111,21 @@ make opt-standard # StandardSens pre-screen sensitivities make opt-envelope # EnvelopeSens sensitivities make opt-refined # StandardSens refined response surfaces make opt-search METRICS="Metric=value ..." # reverse lookup, see the DOE doc +make opt-solve # solve for the setup that hits configs/solve_config.yaml's targets +make opt-trade # compare the vehicles named in configs/trade_study.yaml ``` +`opt-solve` and `opt-trade` cache compiled vehicles and results under +`_4_OptSim/Build/StandardSens/{solve,trade}/`, and discard them when BobLib, the +vehicle or the simulation tooling changes, so a rerun is usually seconds. Which of +the `opt-*` tools answers which question is the first section of +[doe-reverse-engineering.md](doe-reverse-engineering.md). + Note the `opt-*` targets set `PYTHONPATH=_4_OptSim:.` and invoke modules as `StandardSens.*` / `EnvelopeSens.*`, not `_4_OptSim.StandardSens.*`. If you run -one by hand, replicate that or the imports of `_shared` will fail. +one by hand, replicate that or the imports of `_shared` will fail. `PYTHONPATH` +uses the platform's separator, so on Windows outside the container it is +`PYTHONPATH="_4_OptSim;."`. ## Visualizing a run