Writing · 2026-07-20
An experiment is a configuration, not a fork
Research code rots because every new experiment quietly becomes a new copy of the code. The fix isn't discipline — it's making the copy structurally unnecessary. On rebuilding a lab platform around config-composition over orthogonal axes.
Here is how a research codebase dies. Someone runs an experiment. The next experiment is almost the same — one agent instead of two, or the ego can see the opponent now, or it runs on hardware instead of sim — so they copy the launch tree and change the one thing. It works. They do it again. Two years later there are a dozen near-identical stacks, nobody can run last year’s result, and the phrase “just check out that branch” has stopped meaning anything.
I built a multi-agent autonomous-racing platform through my bachelor’s, and it had exactly this disease.The platform, its history, and the rebuilt architecture are the virtual_track case study. This essay is the one idea underneath it. A centralized run and a decentralized run were different launch trees. “Ego sees the opponent” and “ego is blind to the opponent” were different code paths. Sim and hardware diverged. The core loop lived in a single file that did four jobs at once — track loading, pose I/O, velocity estimation, and control — with gains baked inline and a specific motion-capture topic hardcoded into the source. To change the experiment, you changed the program. That is the accretion engine. Every fork is individually reasonable and collectively fatal.
The reframe
Rebuilding it, the design question I actually cared about was not “which DDS” or “which solver.” It was: can an experiment be a configuration over one stable codebase, rather than a new copy of it?
The move that makes the answer yes is to notice that a multi-agent experiment is not one blob of variation — it is a point in a product of a few orthogonal axes:
- Information topology — per agent, what does this agent know? Self-only, sensed peers, a coordinator’s plan, or full state. This varies within a single run, and it is where the science lives.†The canonical case: a coordinator-informed ego that knows the opponent, racing a local-only opponent that is blind to the ego. The asymmetry is the experiment — not an accident of wiring.
- Deployment topology — where does each node run? One process on one DDS graph (sim), or N processes across machines (hardware). And crucially: this must be invisible to the algorithm code. The same information topology should run co-located or distributed with only a launch-layer change.
- Agent heterogeneity — what kind of agent? A ground car and a drone are two manifolds honoring one contract, the platform as a config value rather than a rewrite.
Once you see the axes as orthogonal, the forking stops looking like a discipline problem and starts looking like an architecture problem. Each fork in the old stack was someone hard-coding one coordinate of this product into a new copy, because there was no way to set it separately.
The mechanism
Naming the axes is not enough; something has to make them composable. Two pieces do that.
The first is a thin, versioned contract seam — shared message shapes and a handful of base classes (planner, controller, estimator, safety filter, coordinator) — with the algorithms bound behind it. The seam is the stable boundary that lets a node be a wrapper, not a rewrite: the research code never imports ROS or touches hardware, and the integration layer never touches the math.
The second is refusing to let topology be wired in more than one place. The direction the rebuild is headed is a small, ROS-free data model — an agent profile and a run manifest — compiled by a single function into the node graph.Today the scatter is real: visibility is set across three knobs, the agent roster is declared three times, and there are four ~250-line bespoke drive scripts. The manifest collapses that into one file per experiment and one generic driver. The manifest is the experiment. Change an agent’s information access, or add a third car, and you have edited a config — not authored a branch.
The test that names the whole thing
The acceptance case is the one that would have been a fork in the old world: the mixed-information
overtake — coordinator-informed ego, local-only opponent — expressed as a single config file,
running the same node code for both agents, and runnable either co-located in simulation or split
across two DDS graphs by flipping one deployment block. Same code, two machines or one, asymmetric
knowledge, one file.
If that runs without a new script, branch, or worktree, the structural reason the old platform forked is gone. That is the whole claim. I am not porting a stack from one middleware to another; I am removing the thing that made the old one accrete copies — so the next experiment, and the one after it, is a line in a config instead of a clone of the repo.
This rhymes with a lesson from the same platform’s safety work: the durable fix is almost never a smarter patch. It is changing the structure so the bad thing — a skewed timebase, a forked experiment — can no longer be written down.