Add fixed-patch circle example and README scope section

examples/fixed_patch_circle.py: 32x24 coarse, patch (8,6,24,18), circle
(16,12) R2.15 in the cell-edge frame with the tested 0.7/0.85 aperture;
--mode periodic|slot_reservoir, --speed (+/-, 0 passive), optional
--fine-block BY BX, default 128 coarse steps; rest-equilibrium
postcollision initialization, caller-owned context, fluid-only leaf
mass/density/speed printed every 32 steps; no output files.
README: experimental backend usage and scope (limits, cell-edge frame,
whole-allocation divisibility, fine_block as AMR infrastructure without
speedup claim, unavailable features). No solver changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
ClaudeandClaude Opus 5.5 committed 2026-10-15 05:06:19 +00:00
1 parent 5c37d75dc4
commit 5304525e39
2 files changed
+144

No files matched your search

+42
View File
@@ -91,6 +91,48 @@ sim.run(100, stream=stream, upload_act=False, sync_obs=False)
stream.synchronize()
obs = sim.read_bodies(stream=stream) # sync already done, just read pinned buffer
### Fixed 2:1 refinement patch (experimental backend)
`FixedPatchStepper` advances one fixed 2:1 refinement patch inside a coarse
grid, optionally with stationary circles in the fine region and a prescribed
normal surface velocity (blowing/suction). It is a standalone backend, not part
of `Simulation`. Runnable demo: `examples/fixed_patch_circle.py`.
```python
from CelerisLab.body.geometry.circle import CircleGeometry
from CelerisLab.body.objects import SimObject, SurfaceActuation
from CelerisLab.config import LBMConfig
from CelerisLab.cuda.context import CudaContext
from CelerisLab.lbm.refinement_stepper import FixedPatchStepper
cfg = LBMConfig(nx=32, ny=24, viscosity=.1)
body = SimObject(0, geometry=CircleGeometry(16.0, 12.0, 2.15), center=(16.0, 12.0), radius=2.15,
surface_actuation=SurfaceActuation(0.7, 0.85, 0.002)) # angle, half-width, speed
with CudaContext(0) as ctx, FixedPatchStepper(cfg, (8, 6, 24, 18), context=ctx,
fine_objects=[body], fine_block=(16, 20)) as run:
run.initialize(coarse_g, fine_g) # (9, ny, nx) postcollision populations per level
run.step(128) # coarse steps; fine level takes two per step
coarse_g, fine_g = run.download() # NaN on covered, ghost and solid cells
```
Scope and limits:
- D2Q9, SRT, FP32, double buffer, unshifted, no LES or forcing; one fixed 2:1 patch.
- `coarse_boundary="periodic"` (default) or `"slot_reservoir"` (bottom slot, top
reservoir; patch needs `y0 >= 4`, `y1 <= ny-4`). Periodic mode ignores the wall/slot config fields.
- Object centers/radii use the coarse **cell-edge** frame (cell `I` spans `[I, I+1)`),
unlike `Simulation`'s integer-node frame. Surface speeds are in coarse lattice units.
- Bodies must be stationary circles whose whole boundary stencil lies in the fine
active region, clear of the coarse/fine transfer cells; violations are rejected
before any GPU allocation.
- `fine_block=(by, bx)` stores the fine level in fixed-size blocks; `by`/`bx` must
divide the WHOLE fine allocation, i.e. `2*(y1-y0)+8` by `2*(x1-x0)+8` including the
four-cell ghost band. It gives results identical to dense storage and is
infrastructure for future block AMR, not a speedup.
- Not available: per-link surface exchange/force readout in blocked mode,
checkpoints, moving bodies, multiple patches or dynamic refinement, `Simulation`
integration. Validation so far is storage/operator equivalence and short runs,
not accuracy, convergence or long-time stability.
## Installation
### Prerequisites