chc.meanfield

Stability tier: experimental.

Sequential mean-field control: steer a distribution of agents over a zone graph toward a target.

The "recommend a zone, agents migrate, new distribution" loop: agents adjust gradually toward the softmax response to the per-tick incentives, so an action plays out over several ticks -- a planner that anticipates the migration lag beats a myopic controller that only reacts to the mismatch. Builds on the game response in chc.games.

MeanFieldControl dataclass

Agents migrate gradually toward incentivised zones; the platform steers them to a target.

rollout_cost(u_seq)

Cumulative cost of a plan u_seq: distance-to-target + control effort.

plan(steps=400, lr=0.05, init=None)

Projected-gradient MPC on u_seq through the rollout (warm-start from init).

regrets(steps=400)

Regret vs a well-planned oracle for no-control / myopic / planned mean-field control.

The planner warm-starts from the myopic open-loop plan, so it refines (never worsens) it.