More › tuning

More

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 formal property, a metric with a limit, a field's range

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's task, 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 framepos sensor named tip, pen, nib, brush or marker (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 const written as a plain number. A part's parameter or a parameter is not tuned by --pass; archec fit fits 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 why for 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.