Tuning a controller to its requirements
A controller has numbers you choose by trying: gains, waypoints, a grip force. Mark them as tunable, and archec tries values in the simulator until every test case and requirement passes. The simulator and the requirements decide each verdict. A search or an AI only proposes values.
Mark what may change#
A tunable is a constant with a range: the values a tuner may give it.
const KP = 30.0 { range 5..80 }
const GRIP_FORCE = 8.0 unit N { range 2..14 }
const WAYPOINT_Z = 0.12 { range 0.05..0.2 }
A constant with no range is left alone. A model that does not use range
reads as before: nothing else changes.
Tune with no AI#
archec fit --pass runs the test cases, changes the tunables, and runs them
again. It stops at the first try where everything passes.
archec fit main.arche --pass TC-SETTLE
archec fit main.arche --pass --plant out/mujoco/plant_bridge.py --tries 60 --write
1 fail score 1.91705 KP=0.5 (start: the values as written)
REQ-SETTLE failed at 1.00 s: at 1s expect abs(loop.x - 1.0) < 0.05 — loop.x = 0.3973
2 fail score 1.26941 KP=5.475 (search: KP up by 25% of its range)
REQ-SETTLE failed at 0.00 s: until 1s expect never: abs(loop.u) > U_MAX — loop.u = 5.475
…
5 pass score 0 KP=2.9875 (search: KP down by 12.5% of its range)
✓ try 5 of 5 passes: KP = 2.9875
What it checks on each try:
- every check of the test cases (
at 1s expect …,never:,always:,within) - every requirement archec can check on the run: an EARS sentence, a
formalproperty, ametricwith alimit, a field'srange
The score is 0 when all of this passes. Each failed check adds 1, plus how far its comparison was off, so the search can tell "nearly" from "far".
The search is coordinate steps by default: each tunable up and down, the step
halved when nothing helps, a seeded restart when the step is too small.
--method grid tries a grid, --method nelder-mead a simplex. --seed gives
the same tries again, --tries bounds them (40 by default).
--write puts the passing values in the source, checked first. Without it the
source is left alone.
Let an AI propose#
--propose ai asks an AI for the next values, with the tries so far. It goes
through the egress gateway (AI engineering), so it is
refused offline, which is the default. Turn it on with archec config ai online, or ai local-ai for a model on your machine.
The AI only proposes. The simulator and the requirements decide. The values it
proposed are marked as an AI's in .arche/provenance.jsonl when written, so
archec debt and archec guard see them.
From an AI agent, over MCP#
archec mcp has five tools for the same loop. Claude Code, or any MCP client,
can call them.
| Tool | What it does |
|---|---|
scenario_list |
the test cases and the tunables |
sim_run |
runs the cases; pass or fail, a score, each failed check with its values |
sim_observe |
signals sampled at times, and the states entered |
params_get |
each tunable's value, range and place |
params_set |
writes values into the source, checked, marked as an AI's edit |
sim_run takes values to try tunables without writing them. Each sim_run is
logged as a try, so a replay shows what the agent tried.
The tries files#
Each tuning run writes what it tried beside the model, one folder per run. A replay or a video export reads them.
.arche/tries/20261114-101500-TC-CAP/
session.json what was tuned, against what, and the outcome
001.json try 1: the values, the verdicts, a one-line summary
001.trace.json try 1's runs: sampled signals, states and poses
002.json …
The folder name is the start time (UTC) and the first scenario, so the folders
sort in time. The TypeScript types are in src/tries.ts.
session.json (TriesSession):
| Field | What it holds |
|---|---|
format, version |
"arche-tries", 1 |
id |
the folder's name |
model, system |
the entry file, relative to the model's folder, and the system |
task |
the task in plain words, for a title card (optional) |
scenarios |
the cases each try runs, TP/TC |
plant |
the plant they ran against; none means archec's simulator alone |
params |
each tunable: name, unit, start, lo, hi, file, line |
proposer |
grid, coordinate, nelder-mead, ai or manual |
egress, aiModel |
the egress mode and the model, when an AI proposed |
seed, budget |
the seed of every run, and the most tries allowed |
started, finished |
ISO 8601 times |
outcome |
running, pass, fail, budget or error |
tries, best |
how many tries, and the index of the best one |
written |
the best values were written into the source |
NNN.json (Try):
| Field | What it holds |
|---|---|
format, version |
"arche-try", 1 |
index, at |
1-based (the file name), and when it ran |
by |
start, search, ai or manual |
params, changed |
each tunable's value in its written unit, and the names that changed since the try before |
rationale |
why these values: the search step, or the proposer's reason |
pass, status |
every verdict passed; pass, fail, error or inconclusive |
score |
lower is better, 0 on a pass: 1 per failed verdict, plus how far it was off |
verdicts |
each check and requirement: kind, id, requirement, scenario, text, status, at (s), why, values, miss (how far a failed comparison was off) |
summary |
one line, such as REQ-GRIP failed at 3.20 s: gripper.force = 21.4 |
trace |
the trace file beside it, when written |
NNN.trace.json is an array with one TryTrace per scenario:
| Field | What it holds |
|---|---|
format, version |
"arche-try-trace", 1 |
scenario, end |
the case TP/TC, and its length in seconds |
sample |
the sampling step in seconds |
signals |
each name, unit, t[], v[]: message fields and part variables that are numbers |
states |
each state a part entered: t, part, state |
poses |
each body's t[], pos[] and quat[], when the plant sends them |
contacts |
at each pose sample, t[] and pairs[]: the pairs of bodies that touch, by name (world is the ground) |
verdicts |
the verdicts of this scenario, with their times |
A plant may add bodies' poses to the trace. Next to its messages it sends a
line {"kind": "pose", "t": <ns>, "bodies": {"hand": [x, y, z, qw, qx, qy, qz]}};
archec keeps them in poses. The line may also say what touches,
"contacts": [["hand", "cap"]]; archec keeps that in contacts.
plant_bridge.py sends both. A line of any other kind is ignored, as before.
Watching the tries#
The tries can be watched in 3D, one after the other, like a short film:
archec story export main.arche --tries -o reel.html # a page that plays it
archec story export main.arche --tries -o reel.gif # a GIF, for a chat or a README
archec story export main.arche --tries -o reel.webm # a video, smaller than the GIF
- The reel starts with a title card: the task (
--task "…", else the run'stask, else the system's name). - Then each try moves as the plant moved it: the bodies' poses from its trace. Over it: "Try 3 of 7", why it failed, each verdict, and the values tried. With more than six tries, the reel shows the first, four between and the last.
- It ends on a card: passed after N tries, or not passed yet.
- Each try lasts at most 3 s (
--seconds), the last twice that.
The page also lists every try. Click one to replay it, and drag the slider
to scrub through it. #reel at the end of the address plays the reel again.
What the 3D view adds for a robot:
- The pen's trace. A
framepossensor namedtip,pen,nib,brushormarker(or a part with such a name: its shape's far end) is the pen. Where it touches something (MuJoCo's contacts), or is within 1.5 mm of the box under it, it leaves ink on the surface. - The target, ghosted. A constant named
…TARGET…or…SHAPE…that is a list of points in metres ([[0.3, -0.04], [0.22, -0.04], …], on the surface under each point, or[x, y, z]) is drawn in green. Its last point equal to its first closes it. - What touches. A body of the robot (a body an actuator moves, and what it carries) and what it touches glow orange. Something that never moves (a table) does not.
A GIF or a WebM needs Chrome or Chromium (--chrome, or $CHROME). The GIF is
drawn frame by frame (10 a second, --fps), 640 px wide (--width); the WebM
is recorded in real time. A recording is light unless --theme dark. Nothing
is fetched from the network.
Without contacts in a trace (an older plant), the pen's ink comes from its
height above the surface alone, and nothing glows.
Limits#
- A tunable is a top-level
constwritten as a plain number. A part's parameter or aparameteris not tuned by--pass;archec fitfits those to measurements. - The verdicts are only as good as the test cases and requirements. A case that checks nothing passes at once.
- A trace is sampled, not every event. Use
archec whyfor the whole run. - Tuning finds numbers for a controller you wrote: gains, waypoints, a grip force. It does not learn a skill. A scripted grasp stays scripted.
- A search over many tunables needs many tries. Keep to the few that matter, with ranges as narrow as you can say.
- Each try with a plant starts the plant again, so a MuJoCo try costs a run.