lbm: fixed-centre moving-circle cut links (S2a)

MovingCircleLinks computes the cut links of each translating circle from an
FP64 {cx, cy, r} table over its swept band (same q/hit/clamp/fallback order
as build_cut_links, explicit _rn operations) and applies the unchanged
apply_bouzidi_link with spin wall velocity. obs keeps its contract; a
separate per-body diagnostics buffer records CME, the Wen term u_w*dm,
link_dm and the link count. Moving tables are built at initialize and
attached to the stepper, which then launches the kernel before the static
curved kernel; until then direct and run steps stay blocked. Displacement
is disabled: set_body offset/vx/vy on a translating circle raises before
mutation. Contract section 10a documents S2a and the S3 pending rule.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

tests/unit/test_moving_bodies.py

@@ -117,7 +117,8 @@ def moving_simulation(monkeypatch, *, moving=True):
                                  zero_obs_async=lambda s: writes.append("obs"),
                                  increment_obs_steps=lambda n: writes.append("count"),
                                  download_obs_full_async=lambda s: writes.append("download"))
-    sim.stepper = SimpleNamespace(step=lambda n, **k: writes.append(("step", n)), blocked=None)
+    sim.stepper = SimpleNamespace(step=lambda n, **k: writes.append(("step", n)), blocked=None,
+                                  moving=None)
     sim._assert_runtime_contracts = lambda: None
     return sim, writes
 
@@ -217,17 +218,19 @@ def test_add_body_and_set_body_route_targets(monkeypatch):
     still = sim.add_body("circle", (100., 40.), 5.)
     motion = sim.bodies.get(bid).motion
     assert sim.stepper.blocked is not None  # declaring a moving circle blocks direct steps
-    sim.set_body(bid, offset=(0., .3), vy=.05)
-    sim.set_body(bid, offset=(0., .4), vy=.05)  # last wins
-    for kwargs in (dict(offset=(0., .6)), dict(vy=.05), dict(vx=.05),
-                   dict(offset=(0., .1), vy=.2), dict(offset=(0., 0.), vy=.01)):
-        with pytest.raises(ValueError):
-            sim.set_body(bid, **kwargs)
-        assert motion.pending == ((0., .4), (0., .05))  # invalid input keeps the target
-    sim.set_body(bid, omega=.01)  # omega-only keeps the pending target
+    for initialized in (False, True):  # S2a: displacement disabled before and after initialize
+        sim._initialized = initialized
+        for kwargs in (dict(offset=(0., .3), vy=.05), dict(offset=(0., 0.)), dict(vy=.05),
+                       dict(vx=.05), dict(offset=(0., .1), omega=.01)):
+            with pytest.raises(ValueError, match="disabled until S3"):
+                sim.set_body(bid, **kwargs)
+            assert motion.pending is None and motion.applied == (0., 0.)
+    sim._initialized = False
     obj = sim.bodies.get(bid)
+    assert obj.state.omega == 0.
+    sim.set_body(bid, omega=.01)  # spin on hold stays allowed
     assert obj.state.omega == .01 and (obj.state.vx, obj.state.vy) == (0., 0.)
-    assert motion.pending == ((0., .4), (0., .05)) and motion.applied == (0., 0.)
+    assert motion.pending is None
     with pytest.raises(ValueError, match="not declared"):
         sim.set_body(still, offset=(0., .1))
     sim.set_body(still, vx=.01)  # stationary API unchanged
@@ -240,6 +243,44 @@ def test_add_body_and_set_body_route_targets(monkeypatch):
                          **kwargs)
 
 
+def test_moving_tables_layout_and_attachment(monkeypatch):
+    from CelerisLab.body.motion import MovingTables
+    a = MovingCircle((50., 40.), 10., Translation((-1., 1., -3., 3.), .1))
+    b = MovingCircle((90.25, 30.5), 5., Translation((0., 0., 0., 0.), .1))
+    band, geom = MovingTables.layout([(a, 2), (b, 5)])
+    wa, ha = 63 - 37 + 1, 55 - 25 + 1
+    assert band == [37, 25, wa, ha, 0, 2, 83, 23, 16, 16, wa * ha * 8, 5]
+    assert geom == [50., 40., 10., 90.25, 30.5, 5.]
+    sim = routed_simulation(monkeypatch)
+    sim.add_body("circle", (50., 40.), 10., translation=Translation((0., 0., 0., 0.), .1))
+    sim._moving_tables = "tables"
+    sim._attach_moving()
+    assert sim.stepper.moving == "tables" and sim.stepper.blocked is None
+    sim._moving_tables = None
+    sim._attach_moving()
+    assert sim.stepper.moving is None and sim.stepper.blocked is not None
+
+
+def test_stepper_launches_moving_links_before_static_curved():
+    from CelerisLab.lbm.stepper import LBMStepper
+    launches = []
+    module = SimpleNamespace(get_function=lambda name: lambda *a, **k: launches.append((name, a, k)))
+    cfg = SimpleNamespace(streaming="double_buffer", threads_per_block=128, is_d2q9=True,
+                          nx=64, ny=32, nz=1)
+    field = SimpleNamespace(ddf_gpu="ddf", temp_gpu="temp", flag_gpu="flag", n_curved=0,
+                            invalidate_host_ddf_cache=lambda: None)
+    stepper = LBMStepper(field, module, cfg)
+    stepper._launch_force_region = stepper._launch_sensor = lambda *a, **k: None
+    stepper.moving = SimpleNamespace(band_gpu="band", geom_gpu="geom", diag_gpu="diag",
+                                     slot_debug_gpu=None, n_bodies=1, n_slots=300)
+    stepper.step(2, action_gpu="act", obs_gpu="obs")
+    names = [name for name, _, _ in launches]
+    assert names == ["MovingCircleLinks", "OneStep"] * 2 and stepper.step_count == 2
+    args, kw = launches[0][1], launches[0][2]
+    assert args[:4] == ("ddf", "flag", "band", "geom") and int(args[5]) == 300
+    assert kw["grid"] == (3, 1, 1) and kw["block"] == (128, 1, 1)
+
+
 def test_recompile_installs_a_guarded_stepper(monkeypatch):
     from CelerisLab.lbm.stepper import LBMStepper
     sim = routed_simulation(monkeypatch)

tests/unit/test_state_regressions.py

@@ -297,7 +297,7 @@ def test_passive_overlap_failure_keeps_live_state(device, entry, second_x):
                           stream=SimpleNamespace(synchronize=device.synchronize),
                           stepper=SimpleNamespace(blocked=None))
     for name in ("_require_usable", "_moving_bodies", "_reject_moving_bodies",
-                 "_validate_moving_bodies"):
+                 "_validate_moving_bodies", "_attach_moving"):
         setattr(sim, name, getattr(Simulation, name).__get__(sim))
     with pytest.raises(ValueError, match="active fluid receivers|unique cut-link writers"):
         if entry == "sync":