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.

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.