CelerisLab/docs/compatibility.md

Compatibility and API changes

Changes that can make a previously accepted setup or call behave differently. Each entry names the commit, the affected entry points and the observable result.

Redundant periodic stepper alias removed

PeriodicPatchStepper is no longer exported from lbm.refinement_stepper. Use FixedPatchStepper with the same arguments, including explicit level_blocks. The old name was an alias for that exact class; periodic boundaries remain the default. Existing imports of the old name must be updated.

87c3a31: cut-link ownership is validated for every body

validate_cut_link_ownership (body/preprocess/flag_overlay.py) now runs for passive bodies as well as Jet/aperture bodies. Every cut link must have an active fluid receiver (FLUID set, SOLID clear), and each (receiver, direction) population may have only one writer.

Rejected with ValueError, before flags, populations or device buffers change:

1. Overlapping or touching passive solids whose cut links write the same population ("Boundary requires unique cut-link writers").
2. A body whose cut-link receiver is a non-fluid cell, e.g. a channel wall row or the inlet/outlet column ("Cut links must have active fluid receivers").

Both were previously accepted silently for passive bodies; the interpolated boundary then had undefined results. The rules apply to the cut links of all bodies together, so a passive body overlapping a Jet body is rejected as well. The check runs in Simulation.initialize, runtime body sync (sync_bodies), checkpoint save and checkpoint load (common/checkpoint.py). Load validates before restoring anything, so a checkpoint whose saved geometry violates either rule no longer restores; rebuild the geometry with separated bodies.

87c3a31: Simulation.read_surface_exchange accepts Jet-driven bodies

read_surface_exchange(id) previously required SurfaceActuation on the body. It now also accepts bodies that own Jet aperture links, including Jets with zero or negative amplitude (the aperture test is geometric). Bodies with neither SurfaceActuation nor aperture links still raise ValueError("Body has no surface actuation"). The value is unchanged: the latest step's wall/aperture exchange, not total nozzle force.

7afb5ad: Simulation fails closed after a Jet amplitude device-write failure

Simulation.set_jet_amplitude previously only documented that a device error leaves the per-link velocity column undefined; the instance stayed usable. Now any error after input validation (internal stream creation or the upload) marks the Simulation failed. Every later device-touching public method, including the stream property (guard added in the follow-up repair commit on claude/jet-update-consistency), raises RuntimeError("Simulation failed (...); close() and recreate it"). The host amplitude keeps its previous value. close() still works and stays retryable; cached host readers and host staging calls are not blocked. Invalid input (ValueError/IndexError) is unchanged: it raises before any change and the instance stays usable. FixedPatchStepper.set_jet_amplitude already failed the instance (status failed) and is unchanged.