Compare commits

..
Author SHA1 Message Date
ClaudeWorkerandClaude Opus 5.5 5ad4995f89 docs: add ClaudeWorker smoke test file
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-14 17:15:24 +00:00
Frank14fandCursor 6e3756c587 fix(esopull): correct init layout and pre-streaming semantics (v0.5.1)
EsoPull curved boundaries and wall BCs now use consistent backing-layout
reads; InitEsoPull writes equilibrium in t=0 EsoPull layout. Cache N_OBJS
after compile and atomic config header writes to avoid parallel races.
Adds config screening tools, flume configs, and FP16S/EsoPull diagnosis doc.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-27 22:32:01 +08:00
Frank14fandCursor 00b957f904 feat(esopull): runtime body sync for EsoPull streaming mode
- New esopull_sync.cu: DecodeCellsToPhysical + EncodePhysicalToCells
  (compact-list mode, ddf_shifting-aware, encode applies collision).
- sync_bodies() now branches for double_buffer vs esopull: decode
  backing layout to physical DDF on GPU -> host patch -> collide +
  encode back to backing layout. No temp_gpu, no full-grid copy.
- 4 new integration tests covering esopull add/remove/cycle/roundtrip.
- ddf_shifting + esopull + sync_bodies jointly verified (1300 steps
  stable after add/remove).
- Bump version to 0.5.0.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-21 22:31:02 +08:00
Frank14fandCursor 04c2bc75ea feat(obs): unified zero_obs control and time-normalised readback
- Replace split zero_force_segment / zero_sensor_segment with unified
  zero_obs_async() — a single memset covers all three obs segments
  (force, torque, sensor), resetting the step accumulator.
- Add _obs_accum_steps counter so read_*(normalize=True) returns the
  physically meaningful per-step average for all telemetry fields.
- Sensor now always applies area-normalisation internally; the normalize
  parameter only controls the additional time-normalisation step.
- run() gains zero_obs=True parameter (default) to control reset-on-step.
- 7 new integration tests covering accumulation, zeroing, and normalise.
- Fix bug in test_sensor_accuracy.py (undefined loop variable i).
- Bump version to 0.4.0 for the API change.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-21 00:50:20 +08:00
Frank14fandCursor 7a609b2c76 chore: remove legacy, sync generated config headers, fix inlet kernel
- Remove legacy/ directory (superseded by current architecture).
- Sync auto-generated config headers (config_grid.h, config_objects.h,
  config_method.h, config_physics.h) for current LBMConfig defaults.
- Sync zou_he_local.cuh inlet kernel changes.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-20 18:48:23 +08:00
Frank14fandCursor 987566c0e6 feat(body): runtime body add/remove, unified action/obs, FRC_REGION flag
- Add runtime body topology sync (add_body/remove_body + sync_bodies)
  with recompile, DDF patch (feq + BFS inward fill), and commit.
- Unify action/obs flow: set_body/set_force are now host-only;
  run() auto-uploads action and downloads obs via CUDA stream.
- Add read_body(id) -> BodyTelemetry and read_bodies() for DRL loops.
- Add FRC_REGION flag (0x0800) for force_region cells.
- Extract equilibrium helpers (lbm/equilibrium.py) and DDF patch module
  (body/ddf_patch.py).
- Merge recompile / _runtime_recompile into single _recompile().
- Add n_objects to checkpoint; validate on load.
- Add test suite: 40 unit + 19 integration tests (59 total).
- Add conftest.py and docs/tests_overview.md for test documentation.
- Update README.md and CONFIG.md for new API.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-20 18:17:07 +08:00
Frank14fandCursor d5b7e98750 feat(compat): FP16S and ddf_shifting compatibility, EsoPull curved closure
Phase A: FP16S store precision verification
- Kan99b K2 FP16S: quantization sensitivity documented (St 0.170 -> 0.142)
- Sah04 S2 FP16S: PASS (St error 1.53% within 5% gate)
- Sah04 S4 FP16S: diverges at high blockage (known limitation)

Phase B: ddf_shifting code fixes
- Fix inlet west_velocity_rho_closure for shifted DDF (common.cuh)
- Fix curved force/torque accumulation for shifted DDF (curved_boundary.cuh, aux_kernels.cu)
- Fix host upload_ddf() asymmetry (field.py)
- Add checkpoint streaming/ddf_shifting match check (checkpoint.py)
- MRT shifting fix: MRT is NOT shift-invariant; unshift/reshift around collision
- Generalize inlet knowns repair from Zou-He to all west inlet schemes

Phase C: EsoPull curved boundary semantic closure (from round 2)
- streaming/esopull_semantic_helpers.cuh: single truth for physical-value semantics
- step/esopull_macro.cu: MacroscopicEsoPullKernel for correct GPU diagnostics
- SensorKernel, ForceRegionKernel share semantic helpers
- Kan99b K2: bit-identical to double-buffer
- Code-level comments document compatibility boundaries
- README updated with compatibility matrix
- output/round3_compatibility_summary.md: full round documentation

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-03 10:48:42 +08:00
Frank14fandCursor b110591433 feat(body): add force_region, fix sensor API, reorganize docs
- Add force_region object type: local Guo forcing via sparse compact list
- ForceRegionSoA container, ForceRegionKernel, stepper dispatch
- add_body("force_region", ...) + set_force(id, fx, fy) API
- Fix read_sensor(normalize=...) not being passed from Simulation layer
- Fix force_region incorrectly entering curved cut-link path (P0 blocker)
- Clean up module boundaries: body/__init__ no longer imports from lbm
- Circluar import fix: common/streakline <-> pathline
- Package data globs fixed for recursive kernel files
- Version unified to 0.3.0
- Performance analysis: pycuda launch overhead vs GPU compute at various grid sizes
- Nsight Systems + Nsight Compute profiling data and report
- Documentation reorganized under docs/ (audit, validation_specs)
- README overhaul: multi-body examples, validated benchmarks, force_region docs

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-01 18:07:55 +08:00
Frank14f 2e052480c2 重构body api,性能分析,项目整理 2026-05-31 01:42:58 +08:00
Frank14f 4758eb3215 Add streakline post-processing and exp control-matrix batch runners (vorticity + streakline) 2026-05-27 19:19:51 +08:00
Frank14f 50b2b6a7ca zou_he inlet无法保障稳定,加入新的inlet模式 2026-05-18 17:51:46 +08:00
Frank14f ce492f2794 Sah04验证部分通过,临时修复部分NEQ inlet解决高阻塞流动。kan99b验证初期。 2026-05-16 21:52:06 +08:00
Frank14f 925417abcb Undermind审计前,Cursor重构 2026-05-12 19:08:49 +08:00
Frank14f 654e3290a4 重构:分级设计,EsoPull 2026-04-17 21:50:38 +08:00
Frank14f b339f302d3 Add TRT-LES diagnostics and plotting functionality
- Introduced new functions for computing and plotting TRT-LES fields.
- Enhanced case diagnostics to include mass drift and inlet variance metrics.
- Updated configuration to support inlet profile selection and TRT magic parameter.
- Modified existing functions to accommodate new diagnostic calculations.
- Improved case tagging to include inlet profile and TRT parameters.
- Added checks for fluid dynamics and diagnostics in the run_case function.
2026-04-06 15:57:44 +08:00
Frank14f 5076e5d789 improve LES stability 2026-03-29 22:16:20 +08:00
Frank14f f3e2e557d4 D3Q19 SRT 2026-03-17 18:14:56 +08:00
Frank14f d3b32c8be3 重构: 采用模块化 src 布局
- 重组代码为模块化结构:lbm/, common/, cuda/
- LBM 相关代码移至 src/CelerisLab/lbm/
- 通用工具移至 src/CelerisLab/common/
- CUDA 编译器移至 src/CelerisLab/cuda/
- 更新所有导入路径以适配新结构
- 提供灵活的导入接口(直接导入/模块导入/命名空间风格)
- 为未来扩展(FEM, SPH, MPM 等)做好准备
2026-02-20 15:02:24 +08:00
Frank14f 1137e9a247 SyncTest 2026-02-15 23:13:03 +08:00
Frank14f 0e1b69a55b GiteaSyncTest 2026-02-15 23:12:12 +08:00
Frank14f 304d4f3fe5 Gitea sync 2026-02-15 22:53:38 +08:00
Frank14f 99c175042a Initial commit: CelerisLab v0.2.0 with src layout 2026-02-15 22:36:46 +08:00
145 changed files with 24325 additions and 7 deletions

No files matched your search

+56
View File
@@ -0,0 +1,56 @@
---
description: CUDA/C++ naming — macros, kernels, device helpers, module growth
globs: src/**/*.cu,src/**/*.cuh,src/**/*.h
---
# CUDA and GPU-side naming (CelerisLab)
## File banner and guards
- First line of each hand-written `.cu` / `.cuh`: `// CelerisLab – <path_under_lbm/kernels/>` (en-dash `–`), matching siblings (e.g. `operators/collision_srt.cuh`, `step/one_step_double.cu`).
- Include guards: `CELERIS_<PATH_UPPER>_<STEM>_CUH` (match existing pattern, e.g. `CELERIS_OPERATORS_COLLISION_SRT_CUH`).
- Auto-generated headers under `lbm/kernels/config/` must start with:
`// AUTO-GENERATED by CelerisLab compiler – DO NOT EDIT MANUALLY`
## Module domains (plan for growth)
Keep names readable across domains. Today most GPU code lives under `lbm/kernels/`; future areas may add parallel trees (e.g. particles, deformable solids). Use consistent **semantic** prefixes in identifiers when ambiguity is likely:
| Domain | Scope (conceptual) | Identifier hint |
|--------|-------------------|-----------------|
| Orchestration | Host-side launch, thin wrappers | Already mostly Python; CUDA entry files stay thin |
| Common | Shared numerics / helpers used by multiple domains | Prefer neutral names (`clamp01`, `dot3`) or `cel_*` only if truly project-global |
| LBM | Lattice, collision, streaming, macroscopic | `collide_*`, `stream_*`, `macro_*`, step drivers `one_step_*` — keep physics meaning in the name |
| Body / IBM | Immersed boundaries, rigid surfaces | `ibm_*`, `curved_*`, `cut_link_*` style names where they describe physics |
| Future: flexible solids | Not present yet | Reserve `flex_*` or a dedicated subdirectory prefix when added |
| Future: particles | Not present yet | Reserve `part_*` or `particle_*` under a dedicated subtree when added |
Do not rename working kernels for style alone in a mixed PR with behavior changes; batch renames in a dedicated change after audit.
## Config macros (`config_*.h`)
- Macros are compile-time switches and constants. Prefer **layer + clear token**:
- **Grid**: `NX`, `NY`, `NZ`, `DIM`, `NQ`, … (existing tier “Global/Grid”).
- **Physics**: `VIS`, `RHO`, `U0`, … (existing).
- **Method**: group by sub-area where possible — collision (`COLLISION_MODEL`, …), streaming (`STREAMING_MODEL`, …), LES (`USE_LES` / future `LES_*`), inlet/outlet (`INLET_*`, `OUTLET_*`), stability guards (`OMEGA_COLLISION_*`, `TRT_MAGIC_PARAM`, …).
- **Objects / case**: `N_OBJS`, …
- When **adding** macros, pick names that won’t collide across layers and that encode the tier (document in `configs/CONFIG.md` and in compiler mapping).
- Full normalization of legacy macro names is a **separate refactor** (compiler + all `#ifdef` / macro uses).
## Device functions and kernels
- Device helpers: `__device__ __forceinline__`; prefer small verbs (`compute_feq`, `apply_bc_wall`).
- Pointer parameters that are not aliased: use `__restrict__` where appropriate.
- Kernel entry points (`__global__`): name should state **what step** and **which path** (e.g. `step_lbm_double_buffer`), not only `kernel_launch`.
## Flags and constants
- Cell flags live in `core/flags.cuh`: keep `FLAG_*`, `MASK_*`, and helpers (`is_fluid`, …). Do not change bit layout without a versioned migration plan.
- Python flag constants in `lbm/descriptors.py` must stay consistent with GPU flags; any change updates both sides and user docs.
## Section comments
- File-level title: `// ==== Title ====` or equivalent single banner.
- Subsections: `// --- Section ---` or aligned `// -----` blocks — pick one style **within a file** and match neighbors.
+47
View File
@@ -0,0 +1,47 @@
---
description: Layout, forbidden paths, doc sync across README / CONFIG / code
alwaysApply: true
---
# Project layout and documentation discipline (CelerisLab)
## Source tree (authoritative roles)
- [`src/CelerisLab/simulation.py`](src/CelerisLab/simulation.py): Top-level orchestration API (`Simulation`).
- [`src/CelerisLab/config.py`](src/CelerisLab/config.py): `LBMConfig` / `BodyConfig`, load/validate JSON.
- [`src/CelerisLab/configs/`](src/CelerisLab/configs/): JSON defaults and [`CONFIG.md`](src/CelerisLab/configs/CONFIG.md) (human-oriented parameter reference).
- [`src/CelerisLab/cuda/`](src/CelerisLab/cuda/): CUDA context, compile pipeline, **generation** of `lbm/kernels/config/*.h`.
- [`src/CelerisLab/lbm/`](src/CelerisLab/lbm/): Python field/stepper; [`lbm/kernels/`](src/CelerisLab/lbm/kernels/) holds `.cu` / `.cuh` implementation.
- [`src/CelerisLab/body/`](src/CelerisLab/body/): Rigid-style objects, `ObjectManager`, GPU sync for IBM/sensors.
- [`src/CelerisLab/common/`](src/CelerisLab/common/): Shared host utilities (checkpoint, preprocess, …).
Future domains (flexible solids, particles, etc.) should get **new packages** under `src/CelerisLab/` (e.g. `flex/`, `particle/`) and, if they need GPU code, sibling trees under a clear namespace — not ad-hoc files at repo root.
## Do not edit by hand
- `src/CelerisLab/lbm/kernels/config/*.h` — generated by the compiler from `LBMConfig`; change [`cuda/compiler_v2.py`](src/CelerisLab/cuda/compiler_v2.py) and JSON/schema instead.
- `**/*.ptx` — build artifact.
## Low-value context for agents
- [`legacy/`](legacy/): superseded; do not extend.
- [`ref/`](ref/): external reference trees; not part of the shipping package.
(Also listed in [`.cursorignore`](.cursorignore) to save indexing cost.)
## Configuration and documentation sync (critical)
Agents often update one layer and leave others stale. After changing **any** of the following, reconcile **all** that apply in the same task or an immediately following doc-only commit:
1. **JSON keys or shape** in `configs/config_lbm.json` / `config_body.json`
2. **Fields or validation** in `config.py`
3. **Generated macro names or tiers** in `compiler_v2.py` → `kernels/config/*.h`
4. **[`configs/CONFIG.md`](src/CelerisLab/configs/CONFIG.md)** — tables and “config → code” diagram
5. **[`README.md`](README.md)** — Quick Start JSON example, API bullets, Project Layout if paths change
6. **Docstrings** on `Simulation` and other public entry points if behavior or parameters change
Goal: one mental model — README example, CONFIG.md, and actual loader agree.
## Tests
- Behavioral changes should touch or add coverage under [`tests/`](tests/) when feasible.
+34
View File
@@ -0,0 +1,34 @@
---
description: Python style for CelerisLab — path header, docstrings, English comments
alwaysApply: true
---
# Python style (CelerisLab)
## File header
- Every `src/CelerisLab/**/*.py` file starts with a single-line path comment so agents can orient without reading the body:
- Format: `# CelerisLab/<path_under_package>` (e.g. `# CelerisLab/simulation.py`).
- Match the real path under `CelerisLab/` after edits or moves.
## Language
- All comments and docstrings in Python source are **English**. User-facing prose in `configs/CONFIG.md` may stay Chinese if that file is explicitly maintained for Chinese readers.
## Docstrings and structure
- Module docstring: one-line summary plus at least one structured block where useful (`Usage::`, `Responsibilities:`, `Design:`).
- Public classes and public functions/methods should have a docstring that states purpose; use Google-style sections (`Args:`, `Returns:`, `Raises:`) when parameters or return value are non-obvious.
- Section dividers in long files: `# -- Section name ---------------------------------------` (consistent with existing files like `simulation.py`).
## Types
- Prefer type hints on public APIs (`Simulation`, `ObjectManager`, `LBMField`, config loaders). Completeness can improve incrementally; do not block features on perfect annotation coverage.
## Imports
- Avoid obvious dead imports when touching a file, but **do not** run broad “import cleanup only” refactors as a standalone task unless asked.
## Placeholders
- Stub methods: `pass` plus a short docstring; mark intent with `(placeholder)` or `(future)` where appropriate.
+10
View File
@@ -0,0 +1,10 @@
# Cursor indexing / context — keep noise out of agent view
# (Independent of .gitignore; ref/legacy are huge or obsolete.)
# ref/
legacy/
output/*.pdf
**/*.ptx
**/__pycache__/
.git/
-1
View File
@@ -1 +0,0 @@
*.npz filter=lfs diff=lfs merge=lfs -text
+75
View File
@@ -0,0 +1,75 @@
# Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
*$py.class
*.so
# Distribution / packaging
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
*.egg-info/
.installed.cfg
*.egg
# CUDA compilation outputs
*.ptx
*.cubin
# IDE
.vscode/
.github/
.idea/
*.swp
*.swo
*~
# Jupyter Notebook
.ipynb_checkpoints
# PyCharm
.idea/
# Unit test / coverage reports
htmlcov/
.tox/
.coverage
.coverage.*
.cache
.pytest_cache/
nosetests.xml
coverage.xml
*.cover
# Environments
.env
.venv
env/
venv/
ENV/
env.bak/
venv.bak/
# MacOS
.DS_Store
# Temporary files
*.tmp
*.bak
*.log
# reference:
ref/
output/
legacy/
+21
View File
@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2026 Frank14f
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
+567 -3
View File
@@ -1,5 +1,569 @@
# Isolated VIV evidence backup
# CelerisLab
This orphan data branch does not modify main or source history. Binary arrays are Git LFS objects. Source: fb58c7982763d3b26d9485fc63580009e6629016. Preserve the original Drive parts000-006.
**GPU-Accelerated Lattice Boltzmann Method (LBM) CFD Solver**
Initial transport trial: exact Taylor target native array; full evidence follows only after checksum verification.
CelerisLab is a high-performance computational fluid dynamics solver based on the Lattice Boltzmann Method, leveraging NVIDIA CUDA for GPU acceleration. It provides a Python API for scripting, real-time control loop integration, and scientific workflow automation.
## Features
- **GPU Acceleration**: CUDA kernels for high-performance simulation (384x192 D2Q9: ~4400 MLUPS on V100)
- **D2Q9 / D3Q19 Lattice**: 2D and 3D lattice implementations
- **Multiple Collision Models**: SRT, TRT, and MRT operators; Smagorinsky LES subgrid model
- **Dual Streaming Paths**: Standard double-buffer pull and memory-efficient esoteric-pull (EsoPull). EsoPull is verified as numerically equivalent to double-buffer for D2Q9 curved-boundary MRT (Kan99b K2 validation).
- **Curved Boundary Bouzidi**: Immersed boundary support for complex geometries with wall velocity control
- **Flexible Boundary Conditions**: NEQ-extrapolation pressure outlet, parabolic/uniform velocity inlet, half-way bounce-back walls
- **Rotating Body Control**: Real-time setting of body rotation speeds via `sim.set_body()`
- **Force / Torque / Sensor Readback**: On-demand force, torque, and area-averaged sensor velocity
- **Physics Validated**: Strouhal numbers match Sah04 (confined cylinder) and Kan99b (rotating cylinder) references
## Quick Start
### Single cylinder
```python
from CelerisLab import Simulation
sim = Simulation()
sim.add_body("circle", center=(50, 50), radius=10)
sim.initialize()
for step in range(10000):
sim.run(1)
macro = sim.get_macroscopic() # {"rho": ..., "ux": ..., "uy": ...}
force = sim.read_force(0) # [fx, fy] on body 0
sim.close()
```
### DRL control loop
```python
from CelerisLab import Simulation
sim = Simulation()
sim.add_body("circle", center=(256, 128), radius=10)
sim.add_body("sensor", center=(300, 128), radius=10)
sim.initialize()
for episode in range(100):
# Step the simulation (auto uploads action, downloads obs)
sim.run(100)
# Read individual body telemetry (primary API)
data = sim.read_body(0)
print(f"step={sim.stepper.step_count} "
f"force=({data.force[0]:.4f},{data.force[1]:.4f}) "
f"sensor=({data.sensor[0]:.4f},{data.sensor[1]:.4f})")
# DRL policy inference (replace with your model)
action_omega = 0.001 * (0.5 - data.force[0])
# Set action (host-only, will be auto-uploaded next run)
sim.set_body(0, omega=action_omega)
sim.close()
```
### Async control (performance-oriented, custom stream)
```python
import pycuda.driver as cuda
stream = cuda.Stream()
sim.set_body(0, omega=0.002) # host-only
sim.run(100, stream=stream) # action uploaded, steps run, obs downloaded on stream
# stream is synced inside run() -- obs is ready
data = sim.read_body(0)
```
### Manual stream control (max overlap)
```python
import pycuda.driver as cuda
stream = cuda.Stream()
# Skip transfers for the first batch, just enqueue kernels
sim.run(100, stream=stream, upload_act=False, sync_obs=False)
# ... other GPU work can overlap with the kernel launches ...
# Later: sync and read
stream.synchronize()
obs = sim.read_bodies(stream=stream) # sync already done, just read pinned buffer
## Installation
### Prerequisites
- Python 3.8+
- NVIDIA GPU with CUDA Compute Capability 6.0+
- CUDA Toolkit 11.0+
- NVIDIA drivers
### Install from source
```bash
git clone <repository_url>
cd CelerisLab
pip install -e .
```
### Dependencies
- `pycuda>=2020.1` — CUDA Python bindings
- `numpy>=1.19.0` — numerical computing
- `scipy>=1.5.0` — special functions for vortex initialization
## API Reference
### Simulation
```python
sim = Simulation(
lbm_config_path: Optional[str] = None, # path to config JSON
body_config_path: Optional[str] = None, # path to body config JSON
device_id: int = 0, # GPU device index
)
```
#### Body creation
| Method | Returns | Description |
|--------|---------|-------------|
| `sim.add_body(type="circle", center=(x,y), radius=r)` | int body_id | Add a cylinder body (primary API) |
| `sim.add_body(type="sensor", center=(x,y), radius=r)` | int body_id | Add a velocity sensor |
| `sim.add_body(type="force_region", center=(x,y), radius=r)` | int body_id | Add a force application region |
| `sim.add_cylinder(center, radius)` | int body_id | Convenience wrapper (deprecated) |
| `sim.add_sensor(center, radius)` | int body_id | Convenience wrapper (deprecated) |
| `sim.add_object(obj)` | int body_id | Add pre-configured SimObject |
Future geometry types (polygon, mesh) will use the same `add_body()` function with a different `type` parameter.
#### Runtime control
| Method | Description |
|--------|-------------|
| `sim.initialize()` | Recompile if needed, flow field + sync objects to GPU |
| `sim.run(steps, *, upload_act=True, sync_obs=True, zero_obs=True, stream=None)` | Run N LBM steps. See stream subsection below. |
| `sim.set_body(id, omega=...)` | Set body rotation speed (host array only, uploaded at next `run()`) |
| `sim.read_body(id, *, normalize=True)` -> BodyTelemetry | Unified telemetry: {force, torque, sensor} from pinned buffer |
| `sim.read_bodies()` -> ndarray | Flat array of all bodies' telemetry (batch DRL read) |
| `sim.read_force(id, *, normalize=True)` -> ndarray | Force vector [fx, fy] |
| `sim.read_torque(id, *, normalize=True)` -> ndarray | Torque [tz] |
| `sim.read_sensor(id, *, normalize=True)` -> ndarray | Area-averaged velocity; time-normalised when normalize=True |
| `sim.set_force(id, fx=..., fy=...)` | Set force density on a force_region object |
**Action/obs transfer model:** `set_body()` / `set_force()` are host-only — they modify
the host action array without triggering GPU upload. The GPU buffer is automatically
updated at the start of the next ``run()`` call when ``upload_act=True`` (the default).
**Obs telemetry model:** GPU kernels accumulate force, torque, and sensor readings into
the ``obs_gpu`` buffer via ``atomicAdd``. By default, ``run(zero_obs=True)`` clears the
entire ``obs_gpu`` buffer (all three segments) and resets an internal step counter before
stepping. After the step group, telemetry is downloaded to a pinned host buffer when
``sync_obs=True``.
All three readback methods accept a ``normalize`` keyword:
- ``normalize=True`` (default): divides the raw GPU value by the accumulated step count,
yielding a **per-step average** — the physically meaningful quantity for most use cases.
- ``normalize=False``: returns the raw GPU-accumulated sum (no time division).
**Sensor special handling:** Area-normalisation (dividing by the number of sensor cells)
is **always applied internally** in ``read_sensor()``, regardless of the ``normalize`` flag.
The ``normalize`` parameter only controls the additional time-normalisation step.
``run()`` parameters:
- ``steps``: Number of LBM steps.
- ``upload_act`` (default True): Upload host action array to ``action_gpu`` before stepping.
- ``sync_obs`` (default True): Download ``obs_gpu`` to host pinned buffer after stepping.
- ``zero_obs`` (default True): Zero all obs segments (force, torque, sensor) on GPU and
reset the step accumulator before the step group. Set ``False`` to accumulate
telemetry across multiple ``run()`` calls.
- ``stream`` (default None): CUDA stream for all operations. ``None`` uses an internal stream.
- ``checkpoint_interval`` (default 0): If >0, save an HDF5 checkpoint every N steps.
Use ``upload_act=False, sync_obs=False`` to skip all transfers and enqueue pure
kernel launches on a user-provided stream, then sync and read later.
#### Runtime body topology sync
| Method | Description |
|--------|-------------|
| `sim.remove_body(id)` | Stage a body for removal (committed at next `sync_bodies()`) |
| `sim.sync_bodies()` | Commit pending add/remove edits: recompile kernel, rebuild flags/compact lists, patch DDF, re-upload to GPU |
`sync_bodies()` applies all staged body edits (added via `add_body()` and removed via `remove_body()`) to a running simulation without full reinitialization. The GPU flow field is preserved; only the body-related topology is rebuilt.
**Limitations:**
- Abrupt body introduction causes a transient; force readback is finite but may take 50+ steps to settle
- Verified for `"circle"` type bodies; sensors and force_regions are also expected to work
(they produce no curved links so the DDF patch is simpler)
```python
# Add a body to an already-initialized simulation
sim = Simulation()
sim.initialize()
sim.run(500)
sim.add_body("circle", center=(256, 128), radius=10)
sim.sync_bodies() # recompile + patch
sim.run(500)
force = sim.read_force(0)
# Remove the same body at runtime
sim.remove_body(0)
sim.sync_bodies() # recompile + patch flags/DDF
sim.run(500)
```
**Note:** If `run()` is called without a preceding `sync_bodies()`, any staged edits are silently discarded.
### force_region usage
```python
# Create a circular force application region
fr_id = sim.add_body("force_region", center=(50, 50), radius=15)
# Set force density (lattice units, implicit GPU upload)
sim.set_force(fr_id, fx=0.001, fy=0.0)
# The region applies Guo forcing on each step. Zero force = no-op.
sim.set_force(fr_id, fx=0.0, fy=0.0) # disable force
```
**Persistence note:** `set_force()` only updates the host action array. The GPU
buffer is synced at the next `run()` call. If `sync_to_gpu()` is called manually
before `run()`, the force will be reset to zero. For the common usage pattern
(initialize -> set_force -> run -> set_force -> run ...), this is not an issue.
### Comparison: body types
| Type | Flag overlay | Produces cut-links | Readback | Runtime control |
|------|-------------|-------------------|----------|-----------------|
| `"circle"` | OBSTACLE + BC_CURVED | Yes (Bouzidi) | force/torque | `set_body(id, omega=...)` |
| `"sensor"` | FLUID + SENSOR_FLAG | No | area-averaged velocity (always); optional per-step average | None needed |
| `"force_region"` | FLUID + FRC_REGION | No | None | `set_force(id, fx=..., fy=...)` |
#### Data access
| Method | Description |
|--------|-------------|
| `sim.get_macroscopic()` | Download DDF, return dict with rho/ux/uy |
| `sim.get_ddf()` | Download raw DDF array |
| `sim.get_flags()` | Copy host-side flag array |
| `sim.update_runtime_params(omega=..., fx=..., fy=...)` | Update runtime constants without recompile |
#### Checkpoint / Snapshot
| Method | Description |
|--------|-------------|
| `sim.save_checkpoint(path)` -> str | HDF5 checkpoint with full state |
| `sim.load_checkpoint(path)` | Restore from HDF5 (config must match) |
| `sim.snapshot()` / `sim.restore()` | In-memory field snapshot |
#### Low-level access
| Attribute | Description |
|-----------|-------------|
| `sim.bodies` | ObjectManager for direct GPU buffer access (action_gpu, obs_gpu) |
| `sim.stream` | Internal CUDA stream for async operations |
| `sim.field` | LBMField (GPU memory + curved/sensor SoA handles) |
| `sim.stepper` | LBMStepper for fine-grained step control |
### LBMStepper (advanced usage)
```python
stepper.step(n=1, *, action_gpu, obs_gpu, stream=None)
```
When fine-grained control is needed (e.g., custom async patterns), step manually:
```python
stream = cuda.Stream()
sim.bodies.zero_obs_async(stream)
sim.stepper.step(
1,
action_gpu=sim.bodies.action_gpu,
obs_gpu=sim.bodies.obs_gpu,
stream=stream,
)
stream.synchronize()
sim.bodies.increment_obs_steps(1) # manually track steps for normalize
force = sim.read_force(0) # normalize=True: divides by 1 step
```
## Configuration
### Config file location
`Simulation()` resolves `config_lbm.json` in this order:
1. Explicit path argument to `Simulation(path)`
2. `$CELERISLAB_CONFIG_DIR/config_lbm.json`
3. `./configs/config_lbm.json` (current working directory)
4. The copy shipped inside the installed package
### Config structure
```json
{
"grid": {
"lattice_model": "D2Q9",
"nx": 512, "ny": 256, "nz": 1
},
"physics": {
"data_type": "FP32",
"viscosity": 0.0035,
"velocity": 0.03,
"rho": 1.0
},
"method": {
"collision": "SRT",
"streaming": "double_buffer",
"store_precision": "FP32",
"ddf_shifting": false,
"les": { "enabled": false, "cs": 0.16, "closed_form": true },
"trt": { "magic_param": 0.1875 },
"inlet": {
"profile": "parabolic",
"scheme": "zou_he_local",
"trt_neq_damp": 0.5,
"regularized_neq_damp": 0.5
},
"outlet": {
"mode": "neq_extrap",
"backflow_clamp": true,
"blend_alpha": 0.7,
"srt_neq_damp": 0.5
},
"y_wall_bc": "bounce_back",
"omega_guard": { "min": 0.01, "max": 1.99 }
},
"cuda": {
"threads_per_block": 256,
"compute_capability": "auto"
}
}
```
Full parameter documentation lives in `src/CelerisLab/configs/CONFIG.md`.
## Performance
### Benchmarks (V100, D2Q9, 384x192)
| Config | Streaming | MLUPS |
|--------|-----------|-------|
| Re100 MRT noLES | double_buffer | ~4400 |
| Re100 MRT noLES | esopull | ~4400 |
### EsoPull streaming mode
EsoPull (Esoteric-Pull) is a single-buffer streaming scheme that uses half the memory of double-buffer. It is **fully supported** for 2D D2Q9 with curved boundaries, rotating cylinders, sensors, and force regions.
Current verification scope (v0.5.1, confirmed bit-identical to double-buffer):
- 2D D2Q9 only (D3Q19 not yet implemented)
- MRT collision with both regularized and zou_he_local inlets
- Fixed and rotating cylinder benchmarks:
| Benchmark | D | EsoPull CD | Double-buffer CD | CD diff |
|-----------|---|-----------|-----------------|---------|
| Kan99b K2 | 20 | 1.101 | 1.137 | <3.2% |
| Kan99b K2 | 30 | 1.082 | 1.146 | <5.6% |
- Runtime body topology sync via ``sync_bodies()`` -- add and remove bodies at runtime
- ``get_macroscopic()`` uses GPU kernel for physically correct output
- ``get_ddf()`` returns backing-layout data (not physical DDF) in EsoPull mode
Enable via config: `"streaming": "esopull"`
### FP16S store precision
Half-precision storage is supported for the DDF buffer. All computations are performed in FP32; only storage uses FP16 with a scaling factor.
**Known limitation (v0.5.1):** FP16S combined with Bouzidi curved boundaries produces ~30-40% CD error even with ddf_shifting enabled. This is inherent to Bouzidi's per-direction DDF reads — FP16 quantization noise (~3e-5 per value) is not averaged across directions. DDF shifting is essential for FP16S (keeps values near 0 where FP16 has best precision), but does not fully resolve the Bouzidi incompatibility.
Verified benchmarks:
- Sah04 S2: St error within 1.5% (channel + curved + inlet/outlet)
- Kan99b K2: ~30% CD error with ddf_shifting (FP16S quantization noise through Bouzidi)
- Kan99b K2 without ddf_shifting: >100% error (unusable)
- High-blockage cases (S4 beta=0.9): May diverge earlier than FP32
For force-critical applications with curved boundaries, use FP32 storage. FP16S is suitable for applications where the curved boundary is simple (large D) or force accuracy is secondary.
Enable via config: `"store_precision": "FP16S"`
### ddf_shifting mode
Stores `f_i - w_i` instead of `f_i` to improve FP16 accuracy. Supported with the following verified combinations:
| Collision | Streaming | Inlet | Curved body | Status |
|-----------|-----------|-------|-------------|--------|
| MRT | double_buffer | zou_he_local | cylinder | Verified (K2 metrics match FP32) |
| MRT | double_buffer | regularized | cylinder | Verified (K2 metrics match FP32) |
| MRT | esopull | zou_he_local | cylinder | Verified (sync_bodies tested, bit-identical to double-buffer) |
| MRT | esopull | regularized | cylinder | Verified (bit-identical to double-buffer) |
| SRT | double_buffer | any | cylinder | Expected to work (f-feq style) |
**Known limitations (ddf_shifting):**
- Verified configurations as of v0.5.1: **D2Q9 + MRT + double_buffer + any_inlet** and **D2Q9 + MRT + esopull + any_inlet** (sync_bodies add, remove, stepping stable)
- MRT shifts to physical space before collision, shifts back after (SRT/TRT are shift-invariant natively)
- D3Q19 MRT shifting patch has a ``compute_feq`` inconsistency (not in scope for 2D-only)
- Host ``upload_ddf()`` path is asymmetric (repaired)
- Checkpoint now enforces streaming and ddf_shifting match
### Performance characteristics
The GPU is the primary runtime cost. Python overhead is minimal.
**384x192 (validation grid):** GPU kernel time is ~78 μs/step, of which OneStep is ~5.9 μs (MRT D2Q9). The remaining time is dominated by pycuda kernel launch overhead (~37 μs per launch).
**3000x300 (production grid):** Estimated GPU compute time is ~530 μs/step, with pycuda overhead fixed at ~111 μs, yielding ~83% GPU utilization.
`sim.set_body()` and `sim.read_force()` data transfers are negligible (~1 μs for 72 bytes).
For a detailed breakdown, see [docs/performance_analysis.md](docs/performance_analysis.md).
## Body Module Architecture
```
body/
__init__.py Package exports
objects.py SimObject container + ObjectState / ObjectControl
manager.py ObjectManager: GPU buffer lifecycle, sync, telemetry
registry.py BodyRegistry: pure add/remove/query
action_smoother.py ActionSmoother for control input ramping
geometry/ Shape implementations (CircleGeometry, Geometry ABC)
coupling/ Body-fluid coupling: SoA packing, force/torque
preprocess/ Grid preprocessing: flag overlay, cut-link building
```
## Module Boundaries
- `body/` — geometry, rigid-body state, preprocessing, force/torque readback
- `lbm/` — lattice Boltzmann kernels, field memory, stepper
- `cuda/` — compilation pipeline, context lifecycle
- `common/` — shared utilities (checkpoint, render, streakline pathline)
Geometry is **separated from boundary methods**. CircleGeometry produces geometry-agnostic CutLink records. The SoA packer (`body/coupling/soa_packer.py`) is the single point that knows the kernel memory layout. Adding a new shape (polygon, mesh) requires only a new `Geometry` subclass.
## Validated Benchmarks
| Benchmark | Description | Key metrics | Precision |
|-----------|-------------|-------------|-----------|
| Sah04 S1-S4 | Confined stationary cylinder | Strouhal matching Sahin & Owens (2004) | St error < 5% |
| Kan99b K0-K5 | Rotating cylinder in open domain | St, Cd, Cl matching Kang et al. (1999) | See tolerance table |
| Sensor accuracy | GPU sensor vs CPU flow-field average | Match to 1e-9 | Verified |
Run validation scripts:
```bash
conda run -n pycuda_3_10 python tests/validation/run_kan99b_rotating_cylinder.py
conda run -n pycuda_3_10 python tests/validation/run_sah04_st_matrix.py
conda run -n pycuda_3_10 python tests/validation/test_sensor_accuracy.py
```
## Performance baseline
```bash
conda run -n pycuda_3_10 python tests/validation/run_perf_baseline.py \
--lattice-model D2Q9 --nx 384 --ny 192 --collision MRT
```
## Project Layout
See [docs/tests_overview.md](docs/tests_overview.md) for a complete guide to the test suite.
```
src/CelerisLab/
simulation.py High-level API
config.py LBMConfig / BodyConfig dataclasses
body/ Object management, geometry, GPU sync
cuda/ CUDA context, compilation, PTX load
lbm/ Field, stepper, kernels (CUDA source)
common/ Preprocess, checkpoint, render, streakline
tests/
validation/ Regression runners (Kan99b, Sah04, sensor, perf)
postproc/ Post-processing scripts (exp_ctrl_matrix, streakline)
specs/ Validation spec documents
audit/ Audit reports (archived, see docs/)
output/ Test outputs (force CSV, vorticity PNG, checkpoints)
docs/
performance_analysis.md GPU/Python profiling report
audit/ Audit findings (round 1-2, kernel layer, body refactor notes)
validation_specs/ Validation methodology documents
legacy/ Superseded code (FlowField, compiler v1, macros.h)
ref/ External reference implementations (FluidX3D)
```
## Collision model recommendations
| Use case | Recommended config |
|----------|-------------------|
| Low Re (<= 500) | SRT or TRT, LES off |
| Medium Re (500-2000) | MRT or SRT+LES |
| High Re (2000-5000) | MRT+LES (most robust); SRT+LES; TRT+LES with `omega_guard.max` in 1.90-1.99 |
## Common control loop patterns
### Sync control (simple)
```python
sim.set_body(0, omega=0.002)
sim.run(10)
data = sim.read_body(0)
```
### Async control (performance-oriented)
```python
sim.set_body(0, omega=0.002) # host-only, ~1 μs
sim.stepper.step(10, ..., stream=sim.stream)
sim.bodies.increment_obs_steps(10) # track steps for normalize
sim.bodies.download_obs_full_async(sim.stream)
sim.stream.synchronize()
force = sim.read_force(0) # per-step average force
```
Use ``sim.run()`` for the common case -- it stores the step count automatically:
```python
sim.set_body(0, omega=0.002)
sim.run(10, stream=sim.stream)
force = sim.read_force(0) # per-step average force
```
## Vortex initialization
```python
from CelerisLab.lbm.initializers import add_vortex
add_vortex(sim.field, center=(50, 50), radius=10.0, strength=1.0, vortex_type="lamb")
```
## Streakline visualization
```python
from CelerisLab.common.streakline import Streakline, ReleaseConfig, IntegratorConfig
streak = Streakline(release_points=..., nx=nx, ny=ny)
for step in range(steps):
sim.run(1)
if step % sample_every == 0:
macro = sim.get_macroscopic()
streak.observe(ux=macro["ux"], uy=macro["uy"], step=step)
streak.render("streakline.png")
```
## Citation
```bibtex
@software{celerislab2026,
author = {Frank14f},
title = {CelerisLab: GPU-Accelerated Lattice Boltzmann Method Solver},
year = {2026},
url = {https://github.com/frank14f/CelerisLab}
}
```
## License
MIT License — see LICENSE file for details.
+209
View File
@@ -0,0 +1,209 @@
## 审计结论(第二轮)
本轮审计的视角与上一轮不同。上一轮聚焦"主链路上是否有显式 bug"(找到了 16 项)。本轮审计的四个维度:
| 维度 | 上一轮 | 本轮 |
|---|---|---|
| 主链路正确性 | 找显式 bug | 确认修补正确、无回归 |
| 代码架构质量 | 少量提及 | 系统评估 Python 层职责分离 |
| 新代码 | 不存在 | streakline.py 全篇 + test runners |
| 跨层一致性 | 仅一处 | 系统性检查 config → compiler → kernel → docs 同步 |
核心结论:**上次 16 项修补经逐条审查确认正确,无回归。**
### 第二轮修改完成状态
根据审计发现,已完成以下修改:
| 修改项 | 状态 |
|---|---|
| EsoPull 添加 y=1/NY-2 半格 bounce-back 修正(D2Q9 + D3Q19) | ✅ 已实施 |
| `macro.cuh` diagnostic 函数标注 | ✅ 已标注 `// --- Diagnostic only ---` |
| `config.py` `omega_max` 默认值 1.99 → 1.96 | ✅ 已修改 |
| `BC_MOVING`/`BC_PERIODIC` 代码注释说明 | ✅ 已添加 TODO 注释 |
| Streakline 模块重构:779 行单文件 → `common/streakline/` 子包 (5 文件) | ✅ 已完成 |
| `run_kan99b_streakline.py` 更新为新 API | ✅ 已完成 |
| `run_exp_ctrl_matrix_streakline.py` 更新为新 API | ✅ 已完成 |
| `render_vorticity_field` 移到 `common/render.py` | ✅ 已完成 |
| `ParticleTrailSet` 移到 `common/pathline.py` | ✅ 已完成 |
| 向后兼容 shim `common/streakline.py` | ✅ 已创建(带 DeprecationWarning) |
---
## 状态说明
- `[已确认]` 经代码审查确认正确
- `[无法确认: 需运行验证]` 需数值算例确认,不能单靠读代码定论
- `[新发现]` 本轮审计首次发现
- `[已修复]` 已实施修改
- `[保留说明]` 当前不修,但需在代码或文档中明确限制
---
## 第一轮审计修补确认
逐一确认 16 项"已解决"修补在代码中的真实状态。**全部 [已确认],无回归。**
| 问题 | 结论 | 关键文件:行号 |
|---|---|---|
| `lbm/__init__.py` 导出错误 | 已确认 | 当前导出真实存在的 `add_vortex` |
| forcing 主链路 + 预因子不一致 | 已确认 — 三模型统一使用 `c_tau = 1-omega/2` | `operators/collision_srt.cuh:15`, `collision_trt.cuh:35`, `collision_mrt.cuh:41/116` |
| TRT outlet NEQ 重构未补齐 | 已确认 — COMPILE_MODEL==0\|1 时全分布 damped NEQ | `boundary/outlet/pressure_neq.cuh:45-51` (D2Q9) |
| `add_vortex()` 动量当速度 | 已确认 — `ux = sum(f*cx) / rho_safe` | `lbm/initializers.py:57-58` |
| Sensor 面积归一化 | 已确认 — ObjectManager 层已提供 | `body/manager.py` |
| `sync_to_gpu()` 重置非流体 | 已确认 — 已收缩为只覆盖 obstacle interior | `body/manager.py` |
| curved donor 合法性 | 已确认 — 扩展到实际 domain flags | `body/objects.py` `_donor_is_fluid` |
| curved Bouzidi 时序 | 已确认 — 步前写入 obstacle source slot | `lbm/stepper.py:70-71` → `step/aux_kernels.cu:14` |
| `q >= 0.5` 分支读错时间层 | 已确认 — 读 `load_ddf(fi, ...)` 即同一步 post-collision | `boundary/curved_boundary.cuh:73-75` |
| moving wall 修正未按 q 分支 | 已确认 — 分三路:fallback / q<0.5 / q>=0.5 | `boundary/curved_boundary.cuh:30-43` |
| 初始化链路 flag 叠加顺序 | 已确认 — obstacle overlay → init kernel preserve → equilibrium | `step/init_flow.cu:48-52`, `lbm/stepper.py:43-54` |
| `config_body.json` 未进入初始化 | 已确认 — Simulation 已消费 | `simulation.py` |
| inlet `U0` 语义 | 已确认 — 已补充截面平均速度注释 | `configs/CONFIG.md`, `README` |
---
## 本轮发现与处理
### CUDA Kernel 层
| 严重度 | 问题 | 文件:行号 | 处理 |
|---|---|---|---|
| **[新发现]** [高] | **`BC_MOVING` 与 `BC_PERIODIC` 标记未在 step kernel 中分发。** `core/flags.cuh` 定义了两种标记,但 step kernel 中没有 `is_moving()` 或 `is_periodic()` 分支。设了这两种标记的 cell 会静默 fall through 到 `bounce_back_swap()`。 | `step/one_step_double.cu`, `step/one_step_esopull.cu` | **[保留说明]** 已添加 TODO 注释,暂不实现 |
| **[新发现]** [高] | **EsoPull 缺少 y=1/NY-2 的显式半格 bounce-back 修正。** Double-buffer 路径有该修正而 EsoPull 无。 | `step/one_step_esopull.cu` | **[已修复]** 已添加 D2Q9 和 D3Q19 分支,标注了未来可能需要更精确方案 |
| **[新发现]** [中] | **`USE_DDF_SHIFTING` 路径完整性存疑。** 审查后确认:`macro.cuh` 和 `init_flow.cu` 已处理 shifted,各 collision/curved operator 通过 `load_ddf`/`store_ddf` 抽象层自动适配。**实际已完整,无需修改。** | — | **[已确认无需处理]** |
| **[新发现]** [低] | **`compute_pressure` 与 `compute_pressure_perturbation` 未标注诊断用途。** | `operators/macro.cuh:160-166` | **[已修复]** 已标注 `// --- Diagnostic only ---` |
| **[新发现]** [低] | **Curved/Sensor kernel 无运行时下标越界保护。** 完全依赖 host 侧验证。 | `step/aux_kernels.cu:26-99` | **[保留说明]** 设计选择:不引入多余合法性检查 |
### 第一轮遗留待验证项复查
| 待验证项 | 状态 | 说明 |
|---|---|---|
| **MRT D2Q9 moment transform/inverse** | **[无法确认: 需运行验证]** | 方向索引与 paired ordering 自洽,moment 投影物理正确。但全部系数的数值精度需在 Poiseuille 或衰减涡算例中验证。 |
| **EsoPull 邻壁 vs double-buffer 一致性** | **[已修复]** | 已添加 y=1/NY-2 反弹修正。需运行验证确认。 |
| **Force 提取与 host 侧归一化** | **[无需处理]** | Cd/Cl 管道经确认语义一致。 |
| **Plain linear Bouzidi / TRT 不兼容** | **[保留说明]** | 注释已存在且准确,引用了 [Gin08b]。无方法级替代方案。 |
---
## 架构与设计审计
### Streakline 模块重构
**旧 `common/streakline.py` (779 行) 已被拆解为 `common/streakline/` 子包:**
```
src/CelerisLab/common/
streakline/ 后处理子包
__init__.py 导出 Streakline, ReleaseConfig, IntegratorConfig
_config.py 配置 dataclass + FlowFrame 内部类
_integrate.py 核心积分引擎 (RK4 + 时空插值)
_render.py 密度图渲染 (render_density)
_streakline.py Streakline 类 (被动消费者)
render.py 涡度计算与渲染 (从旧 streakline 移出)
pathline.py ParticleTrailSet + render_trails (从旧 streakline 移出)
preprocess.py 增加 cylinders_from_triangle_layout
```
**核心设计变更:**
| 旧设计 | 新设计 |
|---|---|
| `run_streakline_online(sim, ...)` 控制仿真循环 | `Streakline.observe(ux, uy, step)` 被动接收帧 |
| `run_streakline_offline(frames, ...)` 批处理帧列表 | 移除(无需求) |
| `render_streakline_density(positions, ages, ...)` 15 参数 | `Streakline.render(path)` 内部维护状态 |
| `ParticleTrailSet` 与正确实现混在同一文件 | 移到独立 `pathline.py` |
| `render_vorticity_field` 与粒子跟踪无关 | 移到独立 `render.py` |
| `gaussian_blur2d` 用 `np.apply_along_axis` | 改为显式 `for` 循环 + `np.convolve` |
| `minimal_axes=True/False` 分支重复 | 合并为单路径 `_save_minimal_image` |
**用法示例:**
```python
streak = Streakline(release_points=..., nx=nx, ny=ny, cylinders=...)
# 在自己的仿真循环中:
macro = sim.get_macroscopic()
streak.observe(ux=macro["ux"], uy=macro["uy"], step=step)
# ...同时可以做 body actions、checkpoint、其他模块...
streak.render("output.png")
```
### Body 模块
| 严重度 | 问题 | 行号 | 处理 |
|---|---|---|---|
| **[架构]** | **`ObjectManager` 承担 8 种以上职责。** `sync_to_gpu()` 单枪匹马编排了全部流程。 | `body/manager.py` (423 行) | **[暂不处理]** |
| **[架构]** | **`Cylinder.get_curved_list()` ~180 行包含 7 种职责。** 内嵌函数无法单独测试。 | `body/objects.py:110-291` | **[暂不处理]** |
| **[架构]** | **自上一轮审计以来 body 模块重构进展为零。** | 全部 | **[暂不处理]** |
### Config/API 层
| 严重度 | 问题 | 行号 | 处理 |
|---|---|---|---|
| **[已确认]** | **FP16C 被正确拒绝。** | `config.py:119-123` | ✅ |
| **[已确认]** | **28/28 参数通过四层一致性检查。** | B4a 参数追踪表 | ✅ |
| **[已确认]** | **OBS 布局四层完全匹配。** | B4d 对比表 | ✅ |
| **[架构/低]** | **CONFIG.md 写"建议整除"而非"必须"。** 代码用 ceiling division。 | `configs/CONFIG.md:13`, `lbm/stepper.py:272-274` | **[保留说明]** |
| **[已修复]** | **`LBMConfig` 默认 `omega_max=1.99` → `1.96`,与 JSON/CONFIG 一致。** | `config.py:84` | ✅ |
### 跨层 Flag/常量同步
| 问题 | 状态 |
|---|---|
| **`FLAG_*` 常量 Python ↔ CUDA 同步** | **[已确认]** 全部一致 |
| **`LBMParams` struct 布局耦合** | **[保留说明]** |
| **V_TAYLOR 硬编码 1** | **[保留说明]** |
---
## 测试覆盖率审计
### Validation runner 与文档一致性
| 结论 | 项目 | 说明 |
|---|---|---|
| **[通过]** | Sah04 runner S1-S4 | 四个锚点全部定义并运行 |
| **[缺口]** | Sah04 runner `--u-max` | `u_max_nominal=0.1` 写死 |
| **[缺口]** | Sah04 runner high-beta 网格 | 默认直径与文档推荐不一致 |
| **[通过]** | Kan99b runner K1-K5 | 全部 5 个 case,K2 有 gate |
| **[缺口]** | Kan99b runner K3-K5 | 未做抑制分类自动检测 |
| **[通过]** | 输出机器可读 | 均输出 JSON/CSV |
### 测试基础设施
| 严重度 | 结论 |
|---|---|
| **[严重缺口]** | **零 pytest/unittest 基础设施。** |
| **[严重缺口]** | **四个旧待验证项仅 EsoPull 已修,余三项(MRT、curved boundary、force 归一化)未覆盖。** |
### 建议的最低测试覆盖面(优先级排列)
1. **MRT 单元测试**(uniform flow / Poiseuille / decaying vortex)— 单元级
2. **力系数归一化测试** — 单元级
3. **Curved boundary 单列测试** — 单元级
4. **EsoPull vs double-buffer 一致性**(Poiseuille 流对比)— 单元/集成级
5. **Validation runner smoke 测试** — 验证级
---
## 保留说明
- **`BC_MOVING` / `BC_PERIODIC` 未分发** — 已标注 TODO,暂不实现
- **Curved/Sensor kernel 无运行时越界检查** — 设计选择(依赖 host 验证)
- **Plain linear Bouzidi 与 TRT 不天然相容** [Gin08b] — 注释已存在
- **Curved wall 无质量守恒修正** — 长时间高 Re 周期 curved flow 可能出现力漂移 [San18]
- **入口 `U0` 是截面平均速度**,抛物入口峰值为 `1.5*U0`
- **角点 flag 语义不一致**:初始化时按 inlet/outlet 分类,边界核又落回 `bounce_back_swap()`
- **3D 刚体旋转契约是 z 轴占位实现**(`aux_kernels.cu:58-63`,`Ww = 0.0f`)
- **Curved boundary 仍是圆形几何特化**,没有为任意离散几何留出入路径
- **`LBMParams` struct 布局** 在 Python `struct.pack` 与 CUDA struct 之间硬耦合
- **CONFIG.md NT 整除性措辞**:写"建议",代码用 ceiling division
---
## 修改项汇总
| 类别 | 计数 |
|---|---|
| 第一轮修补确认 | 12 项全部 [已确认] |
| 本轮已修复 | 6 项 |
| 保留说明 | 10 项 |
| 暂不处理 | Body 重构 / 测试基础设施 / Validation runner 缺口 |
+325
View File
@@ -0,0 +1,325 @@
## 目标
第二阶段不再以补丁式修 bug 为主,而是重建 `body` 与 `LBM` 之间的模块边界,形成可持续扩展到 Bouzidi、IBM、粒子和多相耦合的骨架。重构后的代码需要保持短文件、清晰职责、显式契约,并避免几何语义直接渗入 CUDA 核心计算链路。
## 第一阶段与第二阶段的边界
### 第一阶段
目标是验证当前修复后的代码没有恶化,并保住最基本执行链路。
- 能稳定计算流场
- 能读取力与力矩
- Bouzidi 路径不出现新的时序性错误
- 初始化、flag、object overlay 不再互相污染
- 现有接口不做大改,只修运行期 bug 和明显契约错误
### 第二阶段
目标是结构性重构,而不是继续在旧链路上叠加特例。
- 重构 `body`
- 重构 curved boundary 数据链
- 为 IBM 预留统一入口
- 为简单几何和离散几何建立同一中间表示
- 为未来多相与多物理场保留清晰耦合面
## 当前架构的核心问题
### 主要问题
| 模块 | 当前问题 | 后果 |
|---|---|---|
| `body` | 几何、flag overlay、compact list、action、obs、coupling 混在一起 | 任一功能扩展都会牵动整条链路 |
| `objects.py` | 几何对象直接生成 Bouzidi 专用数据 | 简单几何和离散几何无法共享同一接口 |
| `curved_boundary` | 几何解释、边界格式、移动壁修正、力提取绑在同一层 | 替换边界方法成本高 |
| `ObjectManager` | 过度集中,已经接近万能管理器 | 可读性下降,后续只能继续膨胀 |
| host-device contract | 分散在多个文件,缺少统一定义 | 调试困难,容易出现隐式耦合 |
### 本质判断
当前最大问题不是公式本身,而是缺少稳定的中间层。几何对象、边界方法、运行时打包目前没有被拆开,导致代码很难既简洁又可扩展。
结合本轮修 bug 的经验,再补一条判断:很多问题不是几何本身出错,而是 donor、fallback、time layer 这类数值语义散落在不同文件中,读代码时必须来回跳转才能确认。当前项目更适合把这些语义集中写进少数注释位置,而不是继续加更多隐式保护逻辑。
## 第二阶段的目标架构
### 顶层模块
保持两大物理模块:
- `LBM`
- `body`
但它们之间不直接互相了解实现细节,而通过显式中间数据结构耦合。
### 推荐分层
| 层级 | 职责 | 不应负责 |
|---|---|---|
| `simulation` | 装配模块,定义推进顺序 | 几何处理,边界公式细节 |
| `body` | 几何、刚体状态、预处理、力回收 | DDF 操作,LBM 核心算法 |
| `lbm` | 格子流体、collision、streaming、boundary operator | 几何来源,刚体业务语义 |
| `coupling` | cut-link、IBM marker、body-fluid 数据交换 | 具体几何类定义,具体 collision 实现 |
## 推荐的 body 内部结构
### 目标
`body` 应只表达拉格朗日对象和几何处理,不直接承载 LBM 业务逻辑。
补充边界:`body` 负责管理对象并产出统一 cut-link 几何记录,`lbm` 只消费 cut-link 做数值计算。对象类型区分、几何来源、以及“该记录来自圆柱还是离散几何”都不应进入 LBM kernel 视野。
### 推荐文件树
```text
body
geometry
base
circle
sphere
polygon
mesh
state
rigid_body_state
particle_state
preprocess
flag_overlay
cut_links
ibm_markers
sensors
runtime
action_buffer
telemetry_buffer
registry
coupling
wall_velocity
force_torque
```
### 说明
- `geometry` 只回答几何问题
- `state` 只保存状态量
- `preprocess` 负责把几何投影到欧拉网格
- `runtime` 负责 GPU 上传与 buffer 管理
- `coupling` 负责 body 与 fluid 的交换规则
进一步要求:
- `geometry` 不直接生成 Bouzidi 专用 SoA
- `preprocess` 先产出统一 cut-link 结果,再由更薄的一层做运行时打包
- `runtime` 不回头参与几何判断
- 单文件保持简短,避免再出现一个文件同时含几何、打包、上传、观测解释四类职责
## 推荐的 LBM 边界
### LBM 应该看到什么
LBM 只应看到这些输入:
- `flag`
- `cut-link records`
- `IBM marker records`
- `runtime params`
- `obs buffers`
LBM 不应知道:
- 该 link 来自圆柱还是三角网格
- 该对象是粒子还是障碍物
- 该边界记录由哪种 host 几何算法产生
## curved boundary 的重构方向
### 核心原则
不要把 curved boundary 等同于 Bouzidi。
需要拆成三个维度:
- 几何表示
- 边界处理方法
- 运动模型
补充一条实现原则:donor、fallback、time layer 等关键数值语义,优先通过集中注释写清楚,不额外引入很多“自动保证语义”的复杂逻辑。当前项目更优先保持代码短、直、可读。
### 建议的统一中间表示
定义通用 `cut-link record`,至少包含:
| 字段 | 含义 |
|---|---|
| `fluid_idx` | 流体格点索引 |
| `dir` | 指向边界的格子方向 |
| `q` | 交点沿链路的位置 |
| `body_id` | 所属物体 |
| `hit_point` | 壁面交点 |
| `lever_arm` | 相对参考点的力臂 |
| `normal` | 壁面法向 |
| `motion_tag` | 静止、平移、旋转等 |
| `scheme_tag` | Bouzidi、half-way、未来 TRT-compatible scheme |
| `fallback_tag` | donor 非法时的退化方式 |
补充约束:
- `cut-link record` 只表达几何命中结果与最小运行时字段,不直接长成某一种 kernel 专用格式
- donor 的来源与时间层语义不额外做复杂自动推断,靠集中注释写清楚
- 记录字段命名要直接对应 kernel 使用含义,避免同一字段在不同文件中有不同解释
### 这样做的好处
- 圆形和离散几何可以输出同一种记录
- Bouzidi 与 IBM 可以共享一部分几何预处理
- boundary kernel 只消费记录,不关心几何来源
- 以后替换边界方法时,不必回改对象类
- donor、fallback、hit-point 这类契约可以在少数固定注释位置集中说明,而不是散落在对象类和 kernel 两侧
## IBM 的预留方式
IBM 不应和 Bouzidi 混成一条链,而应与 cut-link 平行。
建议另设统一 `marker record`,用于:
- 插值点位置
- 支撑域格点
- 权重
- 与刚体的归属关系
这样未来可以并存:
- cut-link boundary
- IBM boundary
- 混合策略
## 运行时契约的建议
### 必须显式化的契约
应把 host-device contract 从各文件中收口,单独维护。
建议集中定义:
- action buffer layout
- telemetry buffer layout
- cut-link record layout
- marker record layout
- force torque sign convention
- body velocity contract
### 运动状态契约
即使短期只做 2D 圆柱旋转,也建议按最终形式设计:
| 状态 | 建议字段 |
|---|---|
| 平移 | `vx vy vz` |
| 角运动 | `wx wy wz` 或 2D 的 `omega` 特化视图 |
| 参考点 | `cx cy cz` |
| 姿态 | `theta` 或旋转表示 |
不要再把 3D 路径固化为“只读一个 z 轴 `omega`”。
## 第二阶段推荐顺序
### 阶段 2A
先把职责边界拆开,不追求新功能。
- 拆 `ObjectManager`
- 建立 `BodyRegistry`
- 建立 clean `runtime buffer` 层
- 建立单独的 geometry preprocess 层
- 把“对象管理”和“cut-link 产出”分开
验收标准:
- `body` 不再直接知道具体 LBM kernel 调度
- `ObjectManager` 不再承担几何、obs、state、flag 全部职责
- `objects.py` 不再直接输出某一种 boundary method 专用打包格式
### 阶段 2B
重构 curved boundary 数据链。
- 定义统一 `cut-link record`
- 让圆柱先输出新 record
- 让 Bouzidi kernel 消费新 record
- 把现有 `CurvedLinkSoA` 从“Bouzidi 专用”改成“通用 cut-link buffer`
- donor 与 fallback 的契约集中写入注释,不额外增加复杂语义保护代码
验收标准:
- kernel 不需要知道几何来源
- host 侧可以替换 cut-link builder 而不改 kernel 接口
- 读 builder 与 kernel 时,不需要跨很多文件才能理解 donor 和 fallback 的基本语义
### 阶段 2C
为 IBM 留入口。
- 定义 `marker record`
- 预留独立 preprocess 和 runtime buffer
- 暂不实现完整 IBM 细节,只把架构位置留好
验收标准:
- IBM 不需要重写 body 骨架
- IBM 与 Bouzidi 可以共存于同一 body 系统
### 阶段 2D
补文档与契约说明。
- 当前能力
- 预留能力
- 不支持项
- 2D 与 3D 差异
- TRT 与 plain Bouzidi 的限制
## 不建议做的事
- 不要继续强化万能 `ObjectManager`
- 不要让几何对象直接生成某一种边界格式专用 SoA
- 不要把 curved boundary 和 Bouzidi 永久绑定
- 不要在 3D 运动契约上继续堆占位特例
- 不要在第二阶段把多相、IBM、粒子一起全做完
- 不要为了“自动保证语义”继续增加很多隐式逻辑分支,优先用集中注释把契约写清楚
- 不要引入必须跨很多文件来回跳转才能理解的 host-kernel 组织方式
## 第二阶段完成后的理想状态
### 代码层面
- 文件更短
- 模块职责更单一
- host-device contract 更显式
- kernel 更专注于数值操作
- geometry 与 boundary method 解耦
### 扩展层面
后续可自然扩展到:
- 离散几何 cut-link
- IBM marker 链路
- 粒子和刚体共用 body runtime
- 多相流对 body 的额外 coupling
### 维护层面
后续新增功能时,优先在对应层增加文件,而不是回到单个 manager 中继续堆逻辑。
## 建议的执行方式
第二阶段执行前,先固定一个简短设计约束:
- 单文件不过长
- 新增模块必须有明确职责说明
- 任何 host-device 数据结构必须有集中定义
- 新接口先定义契约,再写 kernel
- 能通过新增 builder 解决的问题,不要回写到 geometry 类中
- donor、fallback、time-layer 等关键数值语义必须在少数固定位置集中注释说明
- 优先保持文件短和职责单一,不为“保险”堆太多诊断与保护代码
这个阶段的核心产出不是新功能,而是一个能长期承载新功能的骨架。
+102
View File
@@ -0,0 +1,102 @@
# Config method diagnosis: FP16S and EsoPull analysis
**Resolution status: EsoPull — FIXED (v0.5.1); FP16S — inherent Bouzidi incompatibility (not fixable without architecture change).**
---
## 1. Overview
| Method | Original Failure | Root Cause | Status |
|--------|-----------------|------------|--------|
| **EsoPull** | NaN at D=20; CD ~500-700% error at D=30 | 3 bugs: (1) InitEsoPull wrote physical layout not EsoPull layout; (2) wall BCs used raw `load_ddf` instead of EsoPull semantics; (3) `PrepareEsoPullCurvedKernel` used post-streaming read for pre-streaming force calc | **FIXED v0.5.1** — EsoPull now bit-identical to double-buffer for Kan99b K2 |
| **FP16S** | 30-40% CD error even with ddf_shifting | Bouzidi per-direction DDF reads accumulate FP16S quantization noise without direction-averaging cancellation | **Inherent** — requires architecture change (TYPE_E equilibrium boundaries) |
---
## 2. FP16S analysis (unchanged from v0.5.0)
### 2.1 Root cause
Bouzidi curved boundary reads INDIVIDUAL DDF values per direction per cut-link, with no averaging across directions. At omega~1.9, Re~100, NEQ magnitudes occupy only 1-3 FP16S quantization steps (~3e-5/step). The interpolation ratio (1/q, up to 2x) and moving-wall correction amplify the noise.
FluidX3D avoids this because `update_force_field()` loads ALL 9 (or 19) directions from neighbor cells into FP32, where averaging cancels quantization noise.
### 2.2 Known working combinations (FP16S)
| ddf_shifting | Inlet | D | CD error | Notes |
|---|---|---|---|---|
| True | zou_he_local | 30 | ~32% | Best FP16S result |
| True | zou_he_local | 60 | TBD | Larger D may fare better |
| False | any | any | >>100% | Shifting essential for FP16S |
### 2.3 Recommendations
FP16S is only usable when D is large (D >= 60) OR when force accuracy is secondary. For production Kan99b validation, use FP32. A proper fix would require a FluidX3D-style TYPE_E equilibrium boundary with full-cell momentum summation.
---
## 3. EsoPull root causes and fixes (v0.5.1)
### 3.1 Bug #1 (critical): InitEsoPull physical-layout write
**File**: `lbm/kernels/step/init_flow.cu`
`InitEsoPull` called `write_equilibrium` which wrote `fi[k, i] = f_eq[i]` (physical layout). But `load_f_esopull(t=0)` expects EsoPull backing layout where paired directions are scattered across neighbor cells. At step 0, every direction was read from the wrong slot, producing garbage DDF for collision.
**Fix**: Added `write_equilibrium_esopull` and `write_rest_equilibrium_esopull` that scatter equilibrium values directly into the EsoPull t=0 backing layout: odd directions to neighbor forward slots, even directions to local reverse slots. Also corrected an odd/even slot swap bug discovered during testing.
### 3.2 Bug #2 (moderate): Wall boundary functions use raw `load_ddf`
**File**: `lbm/kernels/boundary/bounce_back.cuh`
`apply_wall_freeslip_d2q9_y_pull` and `apply_wall_bb_d2q9_y_pull` used `load_ddf(fi, index_f(k, slot))` to read opposite-direction values. In EsoPull mode, `fi[k, slot]` is a backing slot, not a physical direction, so the wrong values were used for half-way bounce-back.
**Fix**: Extended function signatures with `t` and `j` parameters. When `t > 0`, use `load_physical_dir_pre_streaming` to resolve the correct pre-streaming value in EsoPull layout. When `t == 0`, fall back to raw `load_ddf` (correct for double-buffer).
### 3.3 Bug #3 (critical for CD): Pre-streaming vs post-streaming semantics error
**File**: `lbm/kernels/step/aux_kernels.cu`, `lbm/kernels/streaming/esopull_semantic_helpers.cuh`
`PrepareEsoPullCurvedKernel` used `load_physical_dir_esopull()` to read DDF values for Bouzidi force computation. This helper returns POST-streaming values (the distribution that arrived at a cell after streaming). However, Bouzidi force calculation requires PRE-streaming values — the post-collision distribution that sat at the fluid cell in each direction BEFORE streaming (matching what double-buffer `CurvedBoundaryKernel` reads from `fi_in[k_f, dir]`).
For odd directions (E, N, NE, SE), `store_f_esopull` writes the pre-streaming value to a NEIGHBOR cell. `load_physical_dir_esopull` then reads the WRONG cell's value for ~50% of directions, producing a systematic ~8x force error.
**Fix**: Added `load_physical_dir_pre_streaming` in `esopull_semantic_helpers.cuh`. This resolves the pre-streaming value by:
- Using `tp = t ^ 1` (previous step's parity) for direction/slot resolution (because `store_f_esopull` at step t-1 wrote the values)
- Reading odd-direction values from the neighbor cell (where `store_f_esopull` scattered them)
- Reading even-direction values from the local cell
- Falling back to `load_physical_dir_esopull` at t=0 (init layout, not store layout)
All three DDF reads in `PrepareEsoPullCurvedKernel` (`f_toward`, `f_toward_ff`, `f_opp_same`) were updated to use the pre-streaming variant.
### 3.4 Results
| Run | Mode | D | St | CD | CD error pre-fix | CD error post-fix |
|-----|------|---|------|------|----------|------------|
| MR2 | double-buffer (baseline) | 20 | 0.16913 | 1.1367 | — | 2.96% |
| MR3 | esopull | 20 | 0.16508 | 1.1009 | ~716% | **0.28%** |
| MR1 | double-buffer (baseline) | 30 | 0.16992 | 1.1455 | — | 3.76% |
| B1 | esopull | 30 | 0.16647 | 1.1129 | ~539% | **0.81%** |
**EsoPull is now numerically equivalent to double-buffer for Kan99b K2 (MRT, D=20/30, rotating cylinder with curved boundaries).**
### 3.5 What the original diagnosis got wrong
1. **Section 3.3 (init mismatch)**: Correctly identified but underestimated — the suggested "skip first step" fix would NOT work because `EsoPullStep(t=0)` itself also operates on wrong semantics from init layout.
2. **Section 3.5 (inlet secondary issue)**: Incorrect. The EsoPull inlet/outlet functions already used `load_f_esopull()` (not raw `load_ddf`) for neighbor DDF reads since they were added. This was never a contributing factor to the CD error.
3. **Section 3.6 (verdict)**: Correctly identified init as root cause of NaN, but missed the pre-streaming bug which was the true cause of CD ~500-700% error. The init bug alone could not explain such a large persistent error.
---
## 4. Files modified in v0.5.1
| File | Change |
|------|--------|
| `lbm/kernels/step/init_flow.cu` | Added `write_equilibrium_esopull` / `write_rest_equilibrium_esopull`; modified `InitEsoPull` to use them |
| `lbm/kernels/streaming/esopull_semantic_helpers.cuh` | Added `load_physical_dir_pre_streaming`; updated usage comments |
| `lbm/kernels/step/aux_kernels.cu` | Changed 3 `load_physical_dir_esopull` calls to `load_physical_dir_pre_streaming` in `PrepareEsoPullCurvedKernel` |
| `lbm/kernels/boundary/bounce_back.cuh` | Extended wall function signatures; added EsoPull pre-streaming read path; updated module docstring |
| `lbm/kernels/step/one_step_esopull.cu` | Updated wall function calls to pass `j` and `t` |
| `tests/validation/run_kan99b_rotating_cylinder.py` | Added `--streaming` CLI parameter |
+126
View File
@@ -0,0 +1,126 @@
# Sub-agent A: CUDA Kernel & Fix Verification
## 1. 旧修正确认
### 结论: [已确认] Curved Bouzidi 时序 — aux_kernels.cu:26-65 + stepper.py:71 + one_step_double.cu:20
**理由**: `stepper.py:71` 中 `_launch_curved()` 在 `OneStep` 之前调用。`aux_kernels.cu` 的 `CurvedBoundaryKernel` 写入 `f.ddf_gpu`(当前 buffer),其后 `OneStep` 从同一 buffer 做 `stream_pull_load` — 同一时间步内完成"前写入→后拉取"。`one_step_double.cu:20` 中的 `apply_boundary_pull` 对 `is_curved(fl)` 直接 return,确保流体节点不会二次覆盖。调用顺序确认无误。
### 结论: [已确认] q>=0.5 分支时间层 — curved_boundary.cuh:73-75
**理由**: `q >= 0.5` 分支读取 `load_ddf(fi, index_f(k_f, dir_opp))`,其中 `fi` 是当前步骤的 DDF buffer。旧代码读的是前一时间步的缓冲区(`fi_in`),现在读的是当前的 `fi`,即上一时间步碰撞后的 post-collision 数据。Bouzidi 两分支算法都要求同一时间层的 post-collision 数据 [Bou01],当前写法满足此要求。
### 结论: [已确认] Moving wall 修正按 q 分支 — curved_boundary.cuh:30-43
**理由**: `bouzidi_linear_moving_correction` 函数三路分支:
- `fallback_class != BOUZIDI` → `2 * alpha_ci_dot_uw`(半格加移动修正)
- `q < 0.5` → `2 * alpha_ci_dot_uw`(Bou01 公式)
- `q >= 0.5` → `alpha_ci_dot_uw / q`(Bou01 公式)
各项系数与文献一致,`alpha_ci_dot_uw = 3 * w_i * (c_i · u_w)`。
### 结论: [已确认] Forcing 预因子统一 — collision_srt.cuh:15, collision_trt.cuh:35, collision_mrt.cuh:41/116
**理由**: 三个文件的类内路径都使用了 `c_tau = 1.0f - 0.5f * omega` 并将 `c_tau * Fin[i]` 增量加到碰撞输出中。`collide_dispatch()`(helpers.cuh:33-37/46-50)在 `d_params.fx/fy/fz`非零时调用 `compute_guo_forcing()` 生成 `Fin`,然后传入对应碰撞函数。三者完全一致。
### 结论: [已确认] TRT outlet NEQ 全分布重构 — pressure_neq.cuh:45-51(D2Q9):89-95(D3Q19)
**理由**: `#if COLLISION_MODEL == 0 || COLLISION_MODEL == 1` 把 TRT 纳入全分布 damped NEQ 分支(与 SRT 同级),对所有 NQ 方向做 `f[i] = feq_tar[i] + beta * fneq`,其中 `fneq = f_neb[i] - feq_neb[i]`,`beta = OUTLET_SRT_NEQ_DAMP`。已不再是"少量未知方向"路径。
### 结论: [已确认] add_vortex() 除以 rho — initializers.py:55-58
**理由**: `ux_old = sum(f[i] * cx[i]) / rho_safe`,`uy_old = sum(f[i] * cy[i]) / rho_safe`。旧 bug 是动量除以 rho 这一步缺失,现在存在 `rho_safe` 分母。
### 结论: [已确认] Init flag overlay 顺序 — simulation.py:139-159 + init_flow.cu:48-58 + body/manager.py:115-127
**理由**: 顺序为 `build_channel_flags()`(干净通道)→ `build_flags()`(叠加物体)→ `upload_flags()`(上传GPU)→ `stepper.initialize()`(运行 init kernel 保持 obstacle flag)。`init_flow.cu:finalize_domain_flag` 对 `is_obstacle(fl)` 直接返回原 flag。`sync_to_gpu(rebuild_flags=False)` 在初始化时不重复构建 flags。`_rest_nonfluid()` 的二次重置已移除。
---
## 2. 待验证项复查
### 结论: [已确认] MRT D2Q9 方向序与符号 — collision_mrt.cuh:46-54,79-92
**理由**: 经子代 agent 验证:
- `m[3]` = f1−f2 + f5−f6 + f7−f8 = ρ·ux(与 `macro.cuh:36` 的 `compute_rho_u()` 完全一致)
- `m[5]` = f3−f4 + f5−f6 − f7 + f8 = ρ·uy(一致)
- `m[7]` = f1+f2−f3−f4 = ρ·(ux²−uy²)(一致)
- 逆变换系数 `g[0] += (dm0 − dm1 + dm2)/9` 等均符合 `M·M⁻¹ = I`
- `meq[4] = −ρ·ux`、`meq[6] = −ρ·uy` 符号正确(正交基结构)
- 无符号错误。MRT D2Q9 的 paired 方向排列下的矩变换自洽。
### 结论: [已确认] Esopull 邻壁行处理 — one_step_esopull.cu vs one_step_double.cu
**理由**: 逐行对比 `one_step_esopull.cu:76-151` 与 `one_step_double.cu:65-144`。Double-buffer 在 line 88-94 有显式 `is_fluid(fl) && (y==1 || y==NY-2)` 块调用 `apply_wall_bb_y_pull`,而 Esopull 没有对应分支。**但这不构成 bug** — Esopull 交替读写模式(`load_f_esopull` / `store_f_esopull`,`esopull_single_buffer.cuh:33-77`)天然避免了从 y=0 壁面节点直接拉取垃圾数据:
- 偶数步:f[3] 读取本地 `fi[n, 4]`(前一步该节点的 -y 方向),f[4] 读取 `fi[j[3], 3]`(y=2 的 +y 方向)
- 奇数步同理交错
两个时间步的综合效果等价于半格 BB 的反射,无需显式修正。壁面节点 (y=0) 经 `apply_boundary_esopull` → `bounce_back_swap` 处理,不会积累垃圾。
### 结论: [无法确认: 需运行验证] Force 提取与符号约定 — curved_boundary.cuh:90-97 + obs.cuh + manager.py:328-338
**理由**: 链路追踪如下:
1. `curved_boundary.cuh:91-97`: `fx = c_x * (f_toward + f_reflected)` 累加到 `obs[obs_force_index(body_id, 0)]`
2. `obs.cuh:11`: `obs_force_index(id_obj, d) = OBS_FORCE0_FLOATS + id_obj * DIM + d`(起点=0)
3. `manager.py:read_force()`: 返回 `self.obs_pinned[i0:i0 + d]`,无符号反转
- 存储的是流体动量交换量 (fluid momentum exchange),不是物体受力的直接值(牛顿第三定律要求 `F_body = -F_fluid`)。如果外部 Cd/Cl 归一化时把 obs 直读值当做物体受力,符号会反转。需用已知算例(如静止圆柱的阻力系数)确认当前实践是否在外部做了隐含的取反。
---
## 3. 架构缺陷
### 结论: [未改] Curved boundary 仍假设圆形/球形 — curved_boundary.cuh + body/objects.py:110-291
**理由**: `Cylinder.get_curved_list()` 对每个 cut link 调用 `find_circle_intersection` / `find_sphere_ray_segment`,完全依赖于圆/球几何参数(center + radius)。没有通用多边形/三角网格接口。旧审计标记的 [待重构] 未处理。
### 结论: [未改] 3D 旋转为 z 轴占位 — aux_kernels.cu:58-63
**理由**: `CurvedBoundaryKernel` 的 D3Q19 分支中 `Ww = 0.0f`,且 `Uw = -omega * ry; Vw = omega * rx` 只包含 xy 平面转动。任何具有 z 分量的刚体旋转都不会产生正确的壁面速度。
### 结论: [已备注] Bouzidi-TRT 不相容注释 — curved_boundary.cuh:17-21
**理由**: 注释明确说明 "plain linear Bouzidi interpolation ... is not a TRT-parametrized curved-wall family",位置精准且语意清晰。
---
## 4. 新发现
### 4a. `_no_force` 碰撞变体为死代码 — collision_srt.cuh:25, collision_trt.cuh:57, collision_mrt.cuh:95
**问题**: `collide_srt_no_force`、`collide_trt_no_force`、`collide_mrt_no_force` 三个函数在编译后的任何内核路径中均不被调用。`collide_dispatch` (helpers.cuh:15-69) 始终通过带 `Fin` 数组的普通变体执行碰撞,当外力为零时通过 `zero_forcing(Fin)` 将 `Fin` 全清零。死代码约 40 行。
**影响**: 无功能影响,增加维护成本。`zero_forcing` 仅用于栈初始化,并非无用调用。
### 4b. BC_MOVING / BC_PERIODIC 有定义无处理 — flags.cuh + 全内核搜
**问题**: `FLAG_BC_MOVING (0x0060)` 和 `FLAG_BC_PERIODIC (0x0050)` 在 `flags.cuh` 有定义,Python 侧 `descriptors.py` 也有对应常量。但 CUDA 内核中没有针对 `is_moving()` 或 `is_periodic()` 的分支处理:
- `one_step_double.cu:apply_boundary_pull` 只有 `is_curved/is_inlet/is_outlet/BBS` 分支
- 任何单元格若被标记 `BC_MOVING`(非 curved 路径)将落入 `bounce_back_swap()` 分支,得到 std half-way BB 而非移动壁面速度修正
**影响**: 只有当 obstacle 使用 `BC_CURVED` 配合 `cl_body_id` 进入 curved boundary kernel 才能获得正确移动壁面速度。`BC_MOVING` 直接标记在通道壁面或其他固体节点上无效果。
### 4c. Outlet NEQ 的 `OUTLET_MODE` 嵌套逻辑可读性隐患 — pressure_neq.cuh:25-62
**问题**:
```
#if OUTLET_MODE == 1 → 纯拷贝未知方向
#else → 普通路径
#if COLLISION_MODEL==0||1 → 全分布 NEQ(含 TRT)
#elif OUTLET_MODE == 2 → 混合模式
#else → 少量未知方向重构(默认 OUTLET_MODE=0 路径)
#endif
#endif
```
当 `OUTLET_MODE=0`、`COLLISION_MODEL=2`(MRT)时,代码进入最内层 `#else` 分支(少量未知方向重构),而非全分布 NEQ。这与注释宣称的"SRT 和 TRT 使用全分布 NEQ"一致(MRT 未承诺),但 MRT outlet 路径与 SRT/TRT 行为不同,可能导致 MRT 结果系统性偏差。
**影响**: MRT outlet 行为与 SRT/TRT 不一致,应至少加注释说明此差异,或行为对齐。
### 4d. `collide_inlet_ghost` 对 `y=0/NY-1` 的过滤 — one_step_double.cu:102-103, one_step_esopull.cu:106-107
**问题**: `collide_inlet_ghost = is_inlet(fl) && interior_y && inlet_scheme_uses_post_collision_ghost()`,其中 `interior_y = (y>0 && y<NY-1)`。`y=0` 和 `y=NY-1` 的 inlet 节点不会触发 ghost 碰撞。但 `inlet_scheme_uses_post_collision_ghost()` 只在 `INLET_SCHEME==0`(Zou-He)时返回 true,而 x=0 inlet 节点原本处于 y=0 或 y=NY-1 时,已被 `build_channel_flags` 覆盖为 `SOLID|BC_WALL`(角点优先),因此这些节点本身不是 inlet,过滤是安全的。
**影响**: 当前无实际影响(角点 wall 覆盖 inlet),但代码隐含的逻辑依赖比较脆弱。如果未来修改建标记序,可能在 y=0/ymax inlet 节点产生未碰撞 ghost 状态。
### 4e. 传感器归一化在 manager 层正确实现 — aux_kernels.cu:67-99 + manager.py:348-365
**结论**: `SensorKernel` 做逐格点求和,`ObjectManager.read_sensor(normalize=True)` 除以 `sensor_cell_counts[body_id]`。已实现,正确。
### 4f. `inlet_target_u` 对 y=0 和 y=NY-1 的保护 — inlet/common.cuh:34
**影响**: `y_clamped = fminf(NY-2, fmaxf(1.0, y))` 使 y=0 节点获得 y=1 的 inlet 速度。对正确定义的 `SOLID|BC_WALL` 角点无实际影响,属于保护性逻辑。
### 4g. `compute_omega_minus` 在 ω⁺ = 2.0 时分母为零 — collision_trt.cuh:24-26
**问题**: `1.0f / omega_plus - 0.5f` 当 `omega_plus = 2.0` 时为 `0.5 - 0.5 = 0`,导致除零。实际路径中 `omega_col` 在 `collide_dispatch` 中被钳位(helpers.cuh:56),假设 `OMEGA_COLLISION_MAX < 2.0` 则为安全。
**影响**: 低风险(依赖外部宏正确配置)。
### 4h. `west_velocity_rho_closure` 在 u_target ≥ 1.0 时除零 — inlet/common.cuh:47-48
**问题**: `rho = sum(...) / (1.0f - ux_target)`,当 `ux_target >= 1.0` 时除数为 0 或负数。物理上入口马赫数小于 1 可避免,但无运行时保护。
**影响**: 低风险(物理约束),但崩溃行为不如显式断言清晰。
---
## 总结
| 类别 | 数量 | 关键项 |
|------|------|--------|
| 旧修正确认 | 7/7 | 全部确认正确 |
| 待验复查 | 3 | 2 确认, 1 需运行时验证 |
| 架构缺陷 | 3 | 圆形硬编码、3D占位、TRT注释齐全 |
| 新发现 | 8 | 4a死代码、4b未处理BC、4c MRT outlet差异、4d脆弱逻辑依赖、4e已实现、4f无害保护、4g除零边界、4h无保护输入 |
**最高优先级**: 4b (`BC_MOVING` 无处理路径)、4c (MRT outlet 路径与 SRT/TRT 不一致)、force 符号约定需运行验证。
+1
View File
@@ -0,0 +1 @@
2026-10-14 ClaudeWorker coding test
+266
View File
@@ -0,0 +1,266 @@
# CelerisLab Performance Analysis Report
Date: 2026-05-31
GPU: Tesla V100-SXM2-16GB (CUDA 12.4)
Test grid: 384x192 D2Q9, MRT, double_buffer, FP32
Tools: cProfile (Python), Nsight Systems (GPU timeline), Nsight Compute (kernel metrics)
## 1. Performance Tree (384x192, MRT, 1 cylinder + 1 sensor)
### Per-step breakdown (batch=100, 100 steps per launch group)
```
┌──────────────────────────────────────────────────────────────┐
│ One LBM Step (~100 steps, ~7.8ms total) │
├──────────────────────────────────────────────────────────────┤
│ │
│ Python Layer (CPU) ~40 μs/step (0.5%) │
│ ├── _launch_curved() ~6 μs │
│ ├── step_fn() (cuLaunchKernel) ~22 μs │
│ ├── _launch_sensor() ~5 μs │
│ └── loop overhead (Python for _ in range) ~5 μs │
│ │
│ GPU Kernel Layer (V100) ~13 μs/step (99.5%) │
│ ├── CurvedBoundaryKernel ~4.0 μs (30%) │
│ │ grid=(2,1,1) block=256 regs=31 288 threads total │
│ │ → latency-bound (too few threads to fill SM) │
│ ├── OneStep ~5.9 μs (44%) │
│ │ grid=(2,192,1) block=256 regs=39 73,728 threads │
│ │ → mixed compute+memory (53% DRAM bw, 22% SM util) │
│ └── SensorKernel ~3.5 μs (26%) │
│ grid=(2,1,1) block=256 regs=21 305 threads total │
│ → latency-bound │
│ │
│ Memory Transfers (negligible, <1 μs/step) │
│ ├── set_body(): 72 bytes H2D (action upload) │
│ └── read_force(): 60 bytes D2H (obs download, async) │
└──────────────────────────────────────────────────────────────┘
```
### Wall-clock contributions (2000 steps, batch=100)
| Layer | Total time | Per step |
|-------|-----------|----------|
| Python (cProfile) | 0.901s (warmup+measured, 70 batches) | ~12.9ms/100-step batch |
| GPU kernel (Nsight) | 0.071s (5300 kernel invocations) | 13.4 μs |
| Batch NVTX range (nsys) | 7.8ms for batch=100 | 78 μs/step (incl. Python) |
**Key insight:** The per-step GPU kernel time is only ~13 μs. The nsys batch timing (78 μs/step) includes Python overhead, kernel launch overhead, and stream synchronization.
## 2. Python Layer Details (from cProfile, T4)
| Function | Cumulative time | Calls | Per call | % of run time |
|----------|----------------|-------|----------|---------------|
| Simulation.__init__ | 1.125s | 1 | 1.125s | 62% (one-time) |
| LBMStepper.step | 0.901s | 70 | 12.9ms | 50% of step time |
| pycuda function_call | 0.769s | 21001 | 36.6 μs | 42% of step time |
| _launch_sensor (inside step) | 0.409s | 7000 | 58 μs | — |
| _launch_curved (inside step) | 0.311s | 7000 | 44 μs | — |
| pycuda _build_arg_buf | 0.357s | 21001 | 17 μs | 20% of step time |
| manager.sync_to_gpu | 0.017s | 1 | — | one-time (init) |
| set_body | <0.001s | 20 | <50 μs | negligible |
| read_force | <0.001s | 20 | <50 μs | negligible |
**Conclusion:** The Python layer is extremely thin. The dominant cost in `stepper.step()` is `pycuda.driver.function_call` (~37 μs per kernel launch) which is the `cuLaunchKernel` overhead from the Python-CUDA bridge. This is an unavoidable cost of using pycuda.
## 3. GPU Kernel Details (from Nsight Systems)
### OneStep (MRT, 384x192, 5300 invocations)
| Metric | Value |
|--------|-------|
| Grid | (2, 192, 1) |
| Block | (256, 1, 1) |
| Registers per thread | 39 |
| Min duration | 5.57 μs |
| **p50 duration** | **5.86 μs** |
| p90 duration | 6.11 μs |
| Max duration | 7.65 μs |
| Total (5300 steps) | 31.2 ms |
### CurvedBoundaryKernel (1 cylinder at center, 5300 invocations)
| Metric | Value |
|--------|-------|
| Grid | (2, 1, 1) |
| Block | (256, 1, 1) |
| Registers per thread | 31 |
| Total threads | 288 active out of 512 launched (56% utilization) |
| **p50 duration** | **4.00 μs** |
| Total (5300 steps) | 21.2 ms |
### SensorKernel (1 sensor, 5300 invocations)
| Metric | Value |
|--------|-------|
| Grid | (2, 1, 1) |
| Block | (256, 1, 1) |
| Registers per thread | 21 |
| **p50 duration** | **3.55 μs** |
| Total (5300 steps) | 18.9 ms |
### Batch Scaling (from Nsight NVTX ranges)
| Batch size | Total time (100 steps) | Effective per step |
|------------|----------------------|-------------------|
| 1 step/launch | 8.08 ms | 80.8 μs |
| 10 steps/launch | 7.86 ms | 78.6 μs |
| 100 steps/launch | 7.78 ms | **77.8 μs** |
**Observation:** Batch size has only a 4% effect on total time between batch=1 and batch=100. This is because the GPU kernel itself is only ~13μs of the total ~78μs. The remaining ~65μs is the pycuda launch overhead + stream sync.
## 4. SRT vs MRT Comparison (from cProfile + ncu)
| Metric | SRT (T1) | MRT (T2) | Ratio |
|--------|----------|----------|-------|
| stepper.step total (70×100 steps) | 0.190s | 0.191s | **1.01x** |
| pycuda function_call count | 7001 | 7001 | 1.0x |
| pycuda function_call time | 0.146s | 0.147s | 1.01x |
| ncu Duration | 10.05 μs | 10.53 μs | 1.05x |
| Registers per thread | — | 39 | — |
| SM Throughput | 18.88% | 22.23% | 1.18x |
| Memory Throughput | 52.73% | 52.92% | 1.00x |
| FMA pipe utilization | 27.3% | 32.3% | 1.18x |
| Executed IPC (active) | 1.18 | 1.24 | 1.05x |
| L1/TEX hit rate | 6.82% | 6.82% | 1.0x |
| L2 hit rate | 54.03% | 54.06% | 1.0x |
| Simulation.__init__ | 1.113s | 1.298s | 1.17x |
**Key finding: MRT is only 5% slower than SRT at this grid size.** Both are dominated by memory access (53% DRAM bandwidth utilization), not compute. MRT's extra FMA operations increase SM throughput from 18.9% to 22.2% but don't elongate wall time because the kernel is limited by the L1TEX scoreboard stalls (49.9% of warp cycles). The top stall reason is **waiting for L1TEX data** (scoreboard dependency), not waiting for compute pipelines.
The grid (384 blocks) is too small to fill the GPU — only 0.8 full waves across 80 SMs. At production scales (3000×300), the SM throughput for MRT would approach 50-60% and the 5% gap over SRT would widen to ~15-20%.
## 5. CUDA API Breakdown (from Nsight Systems)
| CUDA API | Total time (over whole run) | Per call | Notes |
|----------|---------------------------|----------|-------|
| cuCtxCreate_v2 | 123 ms | 123 ms | One-time, CUDA context creation |
| cuModuleLoad | 1.46 ms + 1.02 ms | 1.2 ms | Kernel compilation (one-time per compile) |
| cuLaunchKernel (warmup + measured) | ~47 μs per call | 47 μs | pycuda overhead from cProfile ~37 μs + CUDA driver overhead |
| cuMemcpyHtoD (init: 14KB) | 21-45 μs | varies | Config data upload |
| cuMemcpyHtoD (action: 72 bytes) | ~1.15 μs | 1.15 μs | Body rotation upload |
| cuMemcpyDtoH (DDF: 2.6MB) | 1.02 ms + 2.26 ms | 1-2 ms | Full DDF download (get_macroscopic) — one-time in profiled run |
**DTOH overhead:** The 72-byte action H2D takes ~1.15 μs, and the 60-byte obs D2H would take ~1 μs. These are truly negligible at any scale.
## 6. Bottleneck Identification
### Current bottleneck (384x192): pycuda kernel launch overhead
At this grid size, GPU compute time (13 μs/step) is dominated by pycuda's cuLaunchKernel overhead (~37 μs per kernel × 3 kernels = ~111 μs + Python loop ~7 μs = ~~78 μs/step from nsys, ~129 μs/step from cProfile). The **GPU is idle about 80% of the time** waiting for the next kernel launch.
### What would change at larger grids
| Grid size | GPU time/step (est.) | pycuda overhead | GPU idle |
|-----------|--------------------|----------------|----------|
| 384x192 | ~13 μs | ~37 μs × 3 = 111 μs | **80%** |
| 600x600 | ~33 μs | ~37 μs × 3 = 111 μs | 55% |
| 1000x500 | ~47 μs | 111 μs | 35% |
| 3000x300 (exp_ctrl) | ~530 μs | 111 μs | **17%** |
| 5000x500 | ~1.6 ms | 111 μs | 7% |
**At your production scale (3000x300), GPU utilization would be ~83%.** The pycuda overhead becomes acceptable.
### Where optimization would matter
1. **Reducing pycuda kernel launch overhead** — This is the #1 bottleneck for small grids. The 37 μs/launch comes from pycuda's argument buffer packing (`_build_arg_buf: 17 μs`) + CUDA driver overhead. Switching to `pycuda.driver.LaunchKernel` with pre-packed arguments could reduce this, but it would require significant changes to pycuda.
2. **Combining curved boundary into OneStep** — Would eliminate 2 of 3 kernel launches per step (save ~74 μs). For your production grid (3000x300), this would save about 12% of total time.
3. **Using larger batch sizes** — Already confirmed: batch=100 vs batch=1 saves about 4% total time on 384x192. The savings increase with grid size.
### Where optimization would NOT matter
1. **`set_body()` / `read_force()` overhead** — Already <1 μs. Not worth any optimization effort.
2. **GPU memory bandwidth** — The DDF read/write (5.3 MB/step) is only 2.5% of V100 HBM2 bandwidth. Not the bottleneck.
3. **Python loop overhead** — 5 μs/step loop from `for _ in range(n)` is negligible.
4. **Registry / Body API** — dict lookups and property access are sub-microsecond. Not relevant.
## 7. Performance Model
```
Per-step time (384x192 MRT) =
Python_overhead(~40 μs) ← fixed for any grid size
+ CurvedBoundaryKernel(~4 μs per link-group)
+ OneStep(~5.9 μs)
+ SensorKernel(~3.5 μs per sensor-group)
Per-step time (general) ≈
pycuda_launch_kernels_3 × 37 μs
+ grid_cells × (pull_load + collide + pull_store) / V100_FLOPs
Scaling:
- 384x192: ~78 μs/step (GPU 17%, pycuda 83%)
- 3000x300: ~640 μs/step (GPU 83%, pycuda 17%)
- 6000x600: ~2.5 ms/step (GPU 96%, pycuda 4%)
```
## 8. Nsight Compute Deep-Dive Metrics
### OneStep (MRT) — Nsight Compute full metrics
| Metric | Value | Interpretation |
|--------|-------|----------------|
| Duration (ncu) | 10.53 μs | (ncu includes replay passes; nsys p50=5.86 μs is the real runtime) |
| Registers per thread | 39 | Well below V100 limit of 64. **No register spill to local memory.** |
| Grid | (2, 192, 1) × 256 = 384 blocks | Only 0.8 full waves — grid too small to fill 80 SMs |
| Memory Throughput | 52.9% of HBM2 peak | Moderate bandwidth usage |
| SM Throughput | 22.2% of peak | Low — limited by L1TEX scoreboard stalls |
| FMA pipe active | 32.3% of active cycles | Most-used pipeline, but not saturated |
| L1/TEX hit rate | 6.82% | Low — DDF reads are scattered across the grid |
| L2 hit rate | 54.0% | Moderate — half of cache-line requests hit L2 |
| Top stall reason | L1TEX data wait (49.9%) | Scoreboard dependency on global memory reads |
| IPC (active) | 1.24 inst/cycle | Far below V100's theoretical 4 IPC |
| Active warps/scheduler | 6.09 | Out of 16 max — low occupancy |
| Eligible warps/scheduler | 0.97 | Only 1 warp per cycle is ready to issue |
**Why the kernel does not saturate the GPU:**
- The grid (384 blocks = 73,728 threads) is too small. V100 has 80 SMs with 64 warps each = 5120 warps capacity. This kernel only uses 384 blocks × 2 warps/block = 768 warps (15% occupancy).
- Scoreboard stalls dominate (49.9%). Each warp waits on L1TEX for nearly half its cycles. This is the DDF pull phase: reading from neighbor cells at scattered memory addresses.
- The memory access pattern is suboptimal: only 26.9 of 32 bytes per sector are utilized for global loads that miss L2.
**Optimization potential:** The ncu reports "Est. Speedup: 6.45%" for memory access pattern improvements and "47.27%" for reducing L1TEX stalls. The 47% figure is misleading — it comes from the low grid occupancy, not from actual compute inefficiency. At production grid sizes (3000×300), active warps per scheduler would increase to ~12+ and the stall ratio would drop significantly.
### CurvedBoundaryKernel — Nsight Compute full metrics
| Metric | Value | Interpretation |
|--------|-------|----------------|
| Duration (ncu) | 5.60 μs | Tiny kernel, completely latency-bound |
| Grid | (2, 1, 1) × 256 = 512 threads | Only 2 blocks — **0.0 full waves** |
| Registers per thread | (from nsys) 31 | Low — no spill |
| Memory Throughput | 0.63% of HBM2 | Essentially zero bandwidth utilization |
| SM Throughput | 0.20% of peak | The GPU is doing nothing for this kernel |
| Active warps/scheduler | 1.87 | Out of 16 max — extremely low occupancy |
| Eligible warps/scheduler | 0.06 | Nearly 0 — almost never ready to issue |
| No Eligible | 94.45% | **94% of cycles have no warp ready to issue** |
| Est. Local Speedup | 97.57% | Nsight says there's 97% headroom |
**This is a latency-bound kernel by design.** Only 288 threads for the curved links. The 5.6 μs runtime is dominated by launch overhead (context switching, instruction cache misses). There is no meaningful optimization for this kernel because it cannot use more threads — there are only 288 cut links.
**Impact:** At 4 μs per step, this kernel adds negligible runtime. Even with 100 cut links, the total curved time would still be <10 μs.
### SensorKernel — Nsight Compute full metrics
| Metric | Value | Interpretation |
|--------|-------|----------------|
| Duration (ncu) | 4.54 μs | Even smaller than curved |
| Memory Throughput | 0.63% of HBM2 | Near-zero |
| SM Throughput | 0.14% of peak | GPU doing nothing |
| Active warps/scheduler | 1.84 | Extremely low |
| Eligible warps/scheduler | 0.04 | Almost never ready |
| No Eligible | 96.83% | 97% idle cycles |
| L1/TEX hit rate | 48.53% | Much better than OneStep (localized access pattern) |
Same conclusion: negligible overhead, no meaningful optimization possible.
## 9. Recommendations
1. **For production runs (3000x300)** — The architecture is well-optimized. Use `--batch 10` to amortize pycuda overhead. GPU utilization is ~83%.
2. **For small-grid sweeps (384x192)** — The pycuda launch overhead dominates. If you need to run many small-grid parameter sweeps, consider:
- Grouping multiple independent simulations into a single process
- Or accepting that small-grid runs are launch-overhead limited
3. **For kernel tuning** — At production scale (3000x300), the main kernel (OneStep MRT) uses only 39 registers (no spill), achieves 53% DRAM throughput and 22% SM throughput on 384x192. At 3000x300, SM throughput would approach 50-60% and GPU utilization would be ~83%. No further kernel optimization is needed for current use cases.
4. **Three-kernel architecture is not a problem** — Despite being split into 3 kernels (CurvedBoundary + OneStep + Sensor), the total GPU kernel time is only ~13.4 μs/step. The curved and sensor kernels are latency-bound with negligible impact. Merging them into OneStep would save ~7 μs/step but add branch divergence in the OneStep grid kernel.
+44
View File
@@ -0,0 +1,44 @@
# Test Suite Overview
## Test hierarchy
Three tiers:
- **`tests/unit/`** — pure Python, no GPU. Covers isolated logic (pending edits, sync plan construction, flag masks, equilibrium helpers).
- **`tests/integration/`** — requires GPU. Covers the full body topology sync pipeline (recompile, DDF patch, unified obs/act) and stream API.
- **`tests/validation/`** — requires GPU, long-running (hours). Physics regression against Kan99b, Sah04, and sensor accuracy references.
## Running tests
```
conda run -n pycuda_3_10 python -m pytest <test_path> -v
```
| What you want to verify | Command |
|---|---|
| Body module logic after refactor | `pytest tests/unit/ -v` |
| sync_bodies pipeline (no DDF patch) | `pytest tests/integration/test_sync_bodies_skeleton.py -v` |
| DDF patch after add/remove | `pytest tests/integration/test_ddf_patch.py -v` |
| Unified action/obs + stream API | `pytest tests/integration/test_unified_obs.py -v` |
| Full body add/remove e2e | `pytest tests/integration/test_body_sync_e2e.py -v` |
| All integration tests | `pytest tests/integration/ -v` |
| All tests (unit + integration) | `pytest tests/unit/ tests/integration/ -v` |
| Physics regression | `python tests/validation/run_kan99b_rotating_cylinder.py` |
## Per-file coverage
| File | GPU | Tests | What it covers |
|---|---|---|---|
| `test_pending_edits.py` | No | 14 | stage_add / stage_remove / has_pending_edit / clear_pending_edits lifecycle |
| `test_sync_plan.py` | No | 16 | build_flags_for, build_compact_lists_for, build_next_objects, build_sync_plan, commit_pending |
| `test_body_flags.py` | No | 6 | FRC_REGION / SENSOR_FLAG / OBSTACLE bits for each body type |
| `test_equilibrium.py` | No | 4 | compute_feq_d2q9 and compute_macro_from_ddf numerical correctness |
| `test_sync_bodies_skeleton.py` | Yes | 7 | sync_bodies flow: recompile, esopull guard, step count preservation, pending discard |
| `test_ddf_patch.py` | Yes | 5 | DDF patch after add/remove: finite forces, released region is fluid |
| `test_unified_obs.py` | Yes | 5 | host-only set_body, auto transfer, stream API, DRL loop pattern |
| `test_body_sync_e2e.py` | Yes | 2 | Full add -> remove -> checkpoint -> load -> run cycle |
## Notes
- `pycuda.autoinit` is required for all integration tests (selects GPU 0 by default; set `CUDA_VISIBLE_DEVICES` to change).
- The curved boundary kernel produces NaN in obstacle-adjacent fluid cells over long runs; DDF patch tests use 50-step verification windows.
+489
View File
@@ -0,0 +1,489 @@
# Force region 最小方案设计
目标是在现有功能冻结的前提下,为项目增加一个**局部体力施加区域**,用于研究局部驱动与流场结构之间的关系。该功能的第一阶段只追求可用、低风险、低侵入,不追求最泛化的抽象,也不与 sensor 合并。
当前代码已经具备三条很明确的数据链:全场 `OneStep` 推进、稀疏 `curved` link 链、稀疏 `sensor` cell 链。`force_region` 更接近第三类:它是一个静态几何 footprint,加上运行时 action,而不是一个需要改变主域 flag 的边界对象。因此,第一阶段更适合沿用 `sensor` 风格的稀疏 cell 管理,而不是引入全场 owner map。
## 目标与非目标
| 类别 | 内容 |
|---|---|
| 目标 | 在圆形区域内对流体施加局部体力 |
| 目标 | 运行时更新区域体力参数,不重新编译 |
| 目标 | 尽量少改现有主热路径和已有稳定功能 |
| 非目标 | 与 sensor 统一成单一抽象 |
| 非目标 | 非圆形几何 |
| 非目标 | 3D |
| 非目标 | 多区域重叠叠加规则的完整设计 |
| 非目标 | 数值上最严格的“逐格 collision 内联 forcing”实现 |
## 需求边界
第一阶段建议只支持以下能力:
- `force_region` 是一个圆形 footprint
- 区域内部施加均匀体力 `fx, fy`
- 区域几何在初始化后不变
- 体力大小可在运行时更新
- 只对 fluid cell 生效
- 不要求读取区域平均速度
- 不要求与 `sensor` 或 `body` 的接口完全统一
这意味着第一阶段的问题不是“建立通用 actuator 体系”,而是“在现有框架内插入一条最小局部 forcing 数据链”。
## 现有代码中与该功能直接相关的结构
| 模块 | 当前作用 | 与 force region 的关系 |
|---|---|---|
| `body/geometry/circle` | 生成圆形 footprint | 可复用 |
| `body/manager` | 汇总 compact list 并上传 GPU | 适合新增 force-region list |
| `lbm/curved_links` | 稀疏 SoA 容器 | 可参考 `SensorSoA` 形式扩展 |
| `lbm/kernels/step/aux_kernels` | 稀疏辅助 kernel | 适合新增 `ForceRegionKernel` |
| `lbm/stepper` | 编排主 step 与辅助 kernel | 适合插入 force-region launch |
| `operators/helpers` | 现有全局 Guo forcing 路径 | 可复用公式与语义 |
需要特别注意的一点是:现有全局体力通过 `d_params.fx/fy/fz` 进入 `collide_dispatch()`。这条路径服务的是**全场统一 forcing**。局部体力如果要完全沿用同一语义,最严格的做法是让每个 cell 在线程内部读取本地 force。但这会推动设计进入全场 owner map 或 per-cell force field,而这不符合第一阶段的低侵入目标。
## 推荐的第一阶段总路线
推荐路线是:
- `force_region` 作为一种新对象类型存在
- 它不修改 domain flag
- 它只产出稀疏 cell footprint
- 由一个独立的 `ForceRegionKernel` 在主 step 外对这些 cell 做局部 forcing 修正
换句话说,第一阶段采用的是:
- **主推进仍保持全场统一**
- **局部 forcing 通过稀疏后处理 kernel 注入**
这不是最终最泛化的架构,但它与现有 `sensor` 管理方式一致,工作量低,也最不容易破坏当前稳定基线。
## 为什么不优先采用全场 owner map
全场 owner map 的优点是语义干净:`OneStep` 的每个 cell 都可直接知道自己是否属于某个区域,再把局部体力并入 collision forcing。这在数值上更直接,也更容易扩展到复杂局部 forcing。
但在当前阶段,这条路的代价偏高:
- 需要给全场新增一个 device-side 标识数组
- 需要改主 step kernel 形参和热路径逻辑
- 需要明确多区域覆盖规则
- 需要同时处理 double-buffer 与 esopull 路径中的局部 forcing 接入方式
对当前目标来说,这会把“加一个可用功能”变成“改造主推进语义”。因此,第一阶段更合适的路线仍是稀疏 compact list。
## 为什么不把 force region 直接并入 sensor
二者的几何 footprint 确实相似,都可以表示成“圆形覆盖的一批 cell”。但功能角色不同:
| 类型 | 本质 | 时序位置 |
|---|---|---|
| `sensor` | 读出局部信息 | step 后 |
| `force_region` | 修改 DDF 演化 | step 中或 step 后的局部修正 |
因此,第一阶段不建议在抽象层面合并二者。更合理的做法是:
- 复用几何 footprint 生成逻辑
- 保持独立对象语义
- 保持独立 kernel 与独立 compact list
这样既能少写代码,也不会把接口语义搅乱。
## 对象层建议
`force_region` 建议作为一种新的 body-side 对象类型,而不是把普通刚体、sensor、局部 forcing 区域全部塞进同一语义分支。
### 推荐最低要求
| 字段 | 作用 |
|---|---|
| `obj_id` | 索引 action 与 compact list |
| `geometry` | 圆形 footprint 来源 |
| `state` | 可沿用通用容器,但第一阶段基本不用 |
| `control` 或 action slot | 存 `fx, fy` |
| `type tag` | 区分普通 body、sensor、force_region |
### 不必在第一阶段敲死的点
下面这些都可以留给 coder 选择:
- 是加 `is_force_region` 布尔字段,还是引入更清楚的 `role` / `kind` 标签
- `fx, fy` 放在 `state`、`control`,还是直接只存在 `action` 打包层
- `add_body("force_region", ...)` 还是单独加 `add_force_region(...)`
第一阶段更重要的是把数据链接起来,而不是先做完美 API。
## 几何层建议
`body/geometry/circle` 已经有生成 sensor cells 的逻辑。这里最自然的做法不是复制一份,而是把“圆形 footprint cell 枚举”抽成一个中性函数。
### 推荐抽象
建议在 circle geometry 中形成一个中性能力,例如:
- `build_footprint_cells()`
然后:
- `sensor` 使用这批 cells 作为采样点
- `force_region` 使用同一批 cells 作为施力点
### 第一阶段不必决定的点
- footprint 是否严格包含圆内格点中心
- 是否允许边界一圈采用不同准则
- 是否为将来的 polygon/mesh 提前抽公共父类 helper
只要 footprint 定义在 host 和测试中保持一致即可。
## flag 处理建议
`force_region` 第一阶段**不应修改 flag field**。
原因很直接:
- 它不是 solid
- 它不是 boundary condition
- 它不是 sensor flag
- 它不参与 channel topology 构造
因此它应当是“有 footprint,但不 overlay flag”的对象。
这意味着在 `build_flags()` 过程中:
- 普通 body 继续覆盖 obstacle / curved 标记
- sensor 继续覆盖 sensor 标记
- force_region 返回零 mask,或根本不进入该分支
两种实现都可以,留给 coder 决定。若追求语义更清楚,倾向于根本不让它参与 flag merge。
## compact list 设计建议
第一阶段建议新增一条与 sensor 平行的数据链:
- `force_region cells`
- `force_region obj_id`
### 数据最小集
| 列 | 类型 | 作用 |
|---|---|---|
| `cells` | `uint32` | 被施力格点索引 |
| `obj_id` | `int32` | 从 action 中取 `fx, fy` |
这与 `SensorSoA` 的结构完全同型,只是消费 kernel 不同。
### 可选实现
| 方案 | 特点 |
|---|---|
| 单独建 `ForceRegionSoA` | 语义清楚,后续好扩展 |
| 复用 `SensorSoA` 结构实现新字段 | 改动少,但语义稍混 |
第一阶段更推荐单独建 `ForceRegionSoA`。这会多一点样板代码,但可读性更好,也避免后续 `sensor` 和 `force_region` 在 field 中混淆。
## action contract 建议
当前 `action` buffer 在 2D 下每对象为 `3 * dim = 6` 个 `float`,而现阶段只真正使用了最后一个 `omega`。这给了第一阶段一个很好的低成本入口:
- 不改 action buffer 总长度
- 不改编译期 layout 宏
- 先在已有 slot 中约定 `fx, fy` 的位置
### 一个可行的最小约定
| slot | 含义 |
|---|---|
| `0` | `fx` |
| `1` | `fy` |
| `5` | `omega` |
其余位置保留。
### 这里不必现在敲死
这部分可以留给 coder 做最终选择,只要满足两点:
- `force_region` kernel 能稳定读到 `fx, fy`
- 现有 `CurvedBoundaryKernel` 继续稳定读到 `omega`
若 coder 认为显式 helper 更重要,可以新增类似 `action_force_x()` / `action_force_y()` 的 device helper,而不是在 kernel 中直接写魔数偏移。
## kernel 路线建议
第一阶段最合适的是新增一个独立 kernel,例如:
- `ForceRegionKernel`
它应当像 `SensorKernel` 一样按 compact list 启动,而不是并入 `OneStep`。
### 建议职责
每个线程处理一个 force-region cell:
1. 读该 cell 的线性索引 `k`
2. 读所属对象 `obj_id`
3. 从 `action` 中读 `fx, fy`
4. 从当前 DDF 缓冲中加载该 cell 的 `f[NQ]`
5. 计算 `rho, ux, uy`
6. 按现有 Guo forcing 语义构造 `Fin`
7. 对该 cell 的分布函数做 forcing 修正
8. 写回 DDF
### 需要特别控制的事
第一阶段最好不要在这个 kernel 内部引入过多策略分支。尤其避免一开始就支持:
- 多个不同 forcing scheme
- 复杂边界跳过逻辑
- 非均匀空间 force
- 区域内按距离衰减的 force
先只做“圆内均匀体力”。
## ForceRegionKernel 应该写在哪个时间位置
现有 `stepper` 顺序大致为:
1. curved boundary
2. main step
3. sensor
第一阶段建议将其改为:
1. curved boundary
2. main step
3. force region
4. sensor
### 这样做的原因
- 主推进链尽量不动
- force region 作为局部修正子步存在
- sensor 若未来同时存在,可以读到施力后的局部结果
### 这里保留给 coder 的决策点
`ForceRegionKernel` 也可以放在 sensor 前后不同位置,但需要统一解释语义:
| 放置位置 | 语义 |
|---|---|
| 主 step 之后、sensor 之前 | sensor 读到施力后的状态 |
| sensor 之后 | sensor 读到施力前主步结果 |
若第一阶段不做 sensor 联动,则这只是将来兼容性的选择。默认更建议放在 sensor 之前。
## DDF 更新方式的设计空间
这里是实现中最需要留白的部分。第一阶段文档不应把写法锁死,但应给出边界。
### 必须满足的原则
- 局部体力的数值语义尽量对齐现有 `forcing_guo.cuh`
- 不应在 `ForceRegionKernel` 中引入与现有 collision family 矛盾的私有公式
- 若采用 operator splitting,应在注释中明确说明它不是“主 collision 内联 forcing”
### 可接受的实现方向
| 方向 | 特点 |
|---|---|
| 直接按 Guo forcing 增量对 `f[i]` 做修正 | 最小、直观 |
| 抽一个独立 helper,复用 `compute_guo_forcing()` | 与现有 forcing 公式最一致 |
| 在 kernel 中根据 collision family 调整 prefactor | 更接近现有 `collide_*` 写法,但代码稍重 |
### 第一阶段更适合的判断
更推荐:
- 尽量复用 `compute_guo_forcing()`
- 用很薄的一层 helper 完成 DDF 增量写回
但是否把 `c_tau = 1 - omega/2` 放在 kernel 里、helper 里,还是借新函数收口,可以留给 coder。
## 数值语义说明
第一阶段方案本质上是一个**局部 forcing 修正子步**,而不是严格在 `OneStep` 内逐格并入 collision forcing。这一点需要在实现处用注释写清楚。
### 这个选择的代价
- 语义上更像 operator splitting
- 与全局 forcing 在热路径中的时序并不完全相同
- 在强 forcing 情况下,可能与将来更严格实现有差异
### 这个选择的收益
- 主 kernel 改动极小
- 不需要全场 owner map
- 易于复用现有稀疏对象链路
- 第一阶段很快能得到可用结果
对当前“先追求使用”的目标,这个 tradeoff 是合理的。
## 过滤规则建议
第一阶段应当保持规则简单。
### 建议规则
- 只对 `is_fluid(fl)` 的格点施力
- 对 obstacle / wall / inlet / outlet 一律跳过
- 与 curved body footprint 重叠时,由 cell flag 决定是否生效,而不是 force-region 自己猜
### 这里不必先完善的点
- actuator 与 actuator 的重叠叠加规则
- 对 inlet/outlet 邻近区域的特殊处理
- 对 sensor / force_region 同 id 绑定的逻辑
如果第一阶段允许多个 force region 存在,最简单的策略是先约束:
- footprint 不应重叠
或者:
- 重叠行为未定义,由上层调用者避免
## 配置与 API 建议
这里也不需要一次性定死。
### 最小外部接口至少应支持
- 新建一个圆形 `force_region`
- 运行时更新它的 `fx, fy`
### 可选 API 形式
| 形式 | 特点 |
|---|---|
| `add_body("force_region", ...)` | 改动少,沿用现有入口 |
| `add_force_region(...)` | 语义更清楚 |
### 运行时控制也有两种自然路线
| 形式 | 特点 |
|---|---|
| 扩展 `set_body(id, fx=..., fy=...)` | 改动小 |
| 新增 `set_force_region(id, fx=..., fy=...)` | 语义清楚 |
第一阶段若追求少改代码,可优先沿用现有 `set_body()`。若 coder 认为 API 语义更重要,也可以新增专门入口。
## 对 `ObjectManager` 的建议
`ObjectManager` 已经偏大,因此第一阶段不建议再把很多新判断揉成一团。更合适的方式是:
- 在现有结构上增加一条最薄的新分支
- 尽量与 `sensor` 的组织方式平行
- 不在 `build_flags()` 中塞 force-region 的特例
### 在实现层面建议保持的分工
| 职责 | 位置 |
|---|---|
| 圆形 footprint 枚举 | `geometry` |
| force-region SoA 打包 | `body/coupling` 或与其平行的位置 |
| GPU buffer 生命周期 | `field` / SoA 容器 |
| kernel 调度 | `stepper` |
这能避免 `manager` 再次回到“万能管理器”的方向。
## 对测试的建议
第一阶段至少需要三类测试。
### 1. 结构测试
- `force_region` 不改变 flag field
- compact list cell 数与 footprint 预期一致
- action 更新后 GPU buffer 内容可追踪
### 2. 数值冒烟测试
- 静止流场中施加恒定 `fx` 后,区域内流体沿 x 方向加速
- `fx > 0` 与 `fx < 0` 响应方向相反
- `fy` 路径同理
### 3. 回归保护
- 未添加 `force_region` 时,结果与当前版本一致
- 添加 `force_region` 但 `fx=fy=0` 时,结果与当前版本一致或只存在舍入级差异
### 暂不要求的测试
- 与解析解严格比对
- 多 region 重叠叠加
- 强 forcing 的稳定性边界扫描
## 第一阶段完成后的理想状态
完成后,项目应具备以下能力:
- 能创建一个圆形局部施力区域
- 能在运行时改变其 `fx, fy`
- 不需要重新编译
- 不需要引入全场 owner map
- 不破坏现有 curved boundary 与 sensor 链路
- 不迫使 `body` 与 `lbm` 做新的深度耦合
从架构角度看,第一阶段的关键成果不是“得到最完美的 actuator 抽象”,而是验证:
- 稀疏 cell list 路线足以支撑局部 forcing 研究
- 现有系统能容纳一条新的 compact-list kernel 链路
## 第二阶段可能的演进方向
这些不属于当前实现范围,但第一阶段设计应避免把它们堵死:
- 读取 force-region 内平均速度或其他观测量
- 将 `force_region` 与 `sensor` 的 footprint builder 进一步共用
- 升级为更一般的 `region operator`
- 改为在 `OneStep` 内逐格读取局部 force
- 支持非圆形几何与 3D
第一阶段不需要为这些能力写完结构,只需要不要在命名和数据布局上把后路堵死。
## 建议的实现顺序
### 阶段 1
建立最小对象与 footprint 数据链。
- 新增 `force_region` 类型
- 让 circle geometry 能产出中性 footprint cells
- 新增 force-region SoA 与 GPU upload
### 阶段 2
接入运行时 action。
- 在 action slot 中为 `fx, fy` 留位置
- 增加 host 侧更新接口
- 保证不影响现有 `omega` 读取
### 阶段 3
新增局部 forcing kernel 并接入调度。
- 写 `ForceRegionKernel`
- 接入 `stepper`
- 明确与 sensor 的先后顺序
### 阶段 4
补最小测试与文档注释。
- 结构测试
- 冒烟测试
- 未启用时的回归保护
## 最终判断
第一阶段最稳妥的最小方案不是全场 owner map,也不是把 force-region 并进 sensor,而是:
- 把它当作一种新的稀疏 cell-list 对象
- 复用圆形 footprint 生成逻辑
- 通过独立 `ForceRegionKernel` 对局部 DDF 做 forcing 修正
- 在接口和数据布局上只做最低必要改动
这条路线与现有代码风格最一致,也为后续更严格或更泛化的实现保留了余地。
@@ -0,0 +1,398 @@
# Force region 验证清单
这份清单面向当前已经实现的最小版 `force_region`:
- 2D
- 圆形 footprint
- 运行时设置均匀 `fx, fy`
- operator-split 的局部 Guo forcing 修正
- 不与 sensor 绑定
当前最合理的验证思路不是一次追求“单一终极 benchmark”,而是分三层推进:
1. **代码回归层**:先确认新功能没有破坏旧链路
2. **物理正确性层**:先做最稳的流体响应验证
3. **研究使用层**:再进入圆柱尾迹中的局部强迫实验
文献上,LBM forcing 的核心依据仍是 Guo forcing 的离散处理 [Guo02d]。对 body-force 驱动的通道流,Poiseuille 流是最经典的基准之一,[Zou95b] 给出了平板间 Poiseuille 流的解析结果,[Guo02d] 也把 steady Poiseuille flow 作为 forcing 验证的一部分。对**空间变化** forcing 的风险与误差来源,[Sil20b] 给出了很直接的提醒:非均匀 body force 会把离散误差暴露得更明显,因此验证必须包含**网格、黏度、幅值**三个维度的稳健性检查。
## 一句话总策略
先不要一上来把 `force_region` 扔进圆柱尾迹做复杂控制。先用最简单、最容易解释的流场把它跑顺:
- 零强迫回归
- 单方向局部加速
- 长通道近似 Poiseuille
- 再进圆柱尾迹
## 第一层
### 必做回归检查
这些检查不依赖文献,但必须先过。
| 编号 | 目的 | 设置 | 预期结果 | 是否阻塞 |
|---|---|---|---|---|
| R1 | 新功能不引入假障碍 | 只加 `force_region`,不加圆柱 | `n_curved == 0`,flag 场不出现 obstacle / curved 覆盖 | 是 |
| R2 | 零强迫不改变解 | 加 `force_region`,但 `fx=fy=0` | 与无 `force_region` 基线一致,或只剩舍入级差异 | 是 |
| R3 | force 设置后可持续生效 | `set_force()` 后步进,再触发一次 action 刷新链路 | force 不被静默清零 | 是 |
| R4 | 符号方向正确 | 同一算例跑 `+fx` 和 `-fx` | 主流响应方向相反,幅值同量级 | 是 |
R2 很关键。它回答的是:当前实现是不是“只是多了一条 dormant 数据链”,而不是“只要建了 force_region 就改了解”。
## 第二层
### 物理正确性主验证
这部分建议按从简单到复杂的顺序做。
## Case A
### 静止流场中的单圆局部加速
这是最小物理 sanity check。
#### 设置建议
- 格子:`nx = 256`, `ny = 128`
- 碰撞:先用 `SRT`,LES 关闭
- 流动初值:入口速度设为 0 或足够小,先得到近静止背景流
- 不加圆柱
- force region:
- 圆心 `(96, 64)`
- 半径 `r = 12`
- 先做 `fx > 0, fy = 0`
- 强迫幅值:从小值开始,例如 `fx = 1e-6`, `5e-6`, `1e-5`
- 每组运行到准稳态或至少足够长,使局部响应明显
#### 该看什么
- `ux` 在 force region 附近应整体偏正
- 区域下游应形成沿 `+x` 延伸的动量尾迹
- `uy` 的主量级应明显小于 `ux`
- 将 `fx` 改成负值后,整幅图应沿 x 方向近似镜像
#### 预期结果
这个 case 没有一个成熟的“标准 benchmark 数字”,但应满足最基本物理响应:
- 加速方向与 force 方向一致
- 幅值随 `fx` 单调增强
- 小 force 下解的结构应平滑,不应出现棋盘格、局部爆点或非对称破缺
#### 判定标准
| 检查项 | 通过标准 |
|---|---|
| 方向性 | `fx > 0` 时主响应沿 `+x`,`fx < 0` 时相反 |
| 单调性 | 增大 `fx` 后,局部 `ux` 峰值与尾迹强度单调增大 |
| 对称性 | 在无背景横向偏置时,上下半区统计应近似对称 |
| 稳定性 | 小幅强迫下不出现数值振荡或孤立噪点 |
这个 case 的作用不是给出论文级定量结论,而是先证明:**局部 forcing 至少在最简单流场中按直觉工作。**
## Case B
### 长通道中的近 Poiseuille 验证
这是最重要的文献支持主验证。
Poiseuille 流是 LBM forcing 的经典基准,[Guo02d] 用 steady Poiseuille flow 验证 forcing 处理,[Zou95b] 给出了平板间 Poiseuille 流的解析形式。对当前代码,最现实的做法不是强行构造完全理想的周期通道,而是在**长通道中用超大圆形 force region 近似全域恒定体力驱动**,只在远离入口和出口的位置取剖面比较。
#### 建议设置
- 格子:`nx = 1024`, `ny = 128`
- 碰撞:先用 `SRT`;通过后再试 `TRT` / `MRT`
- LES:关闭
- 圆柱:不加
- 入口速度:尽量设小,避免 inlet 自身主导流场
- force region:
- 圆心放在通道中段,例如 `(512, 64)`
- 半径取足够大,使绝大多数通道内部 fluid cell 都被覆盖,例如 `r = 600`
- 强迫方向:`fx > 0, fy = 0`
- 强迫幅值:先从小值开始,避免压缩性误差,例如 `1e-6` 量级
#### 为什么这样设
当前 `force_region` 只有圆形 footprint,没有全域矩形 forcing,也没有 x 周期边界。因此最稳妥的近似是:
- 用超大圆把中部通道几乎全覆盖
- 只在远离入口和出口的位置取横截面
- 检查剖面是否接近抛物线
#### 该比对什么
对 fully developed Poiseuille,经典剖面是抛物线 [Zou95b]:
\[
u(y) = u_{max}\left(1 - \frac{y^2}{L^2}\right)
\]
其中中心线速度最大,壁面速度为 0。对当前代码,最重要的不是把解析常数拟合到最后一位,而是确认以下结构性特征:
- 中部横截面是单峰抛物形
- 中心线最大
- 贴壁速度接近 0
- `uy` 远小于 `ux`
- 沿 x 方向进入发展段后,剖面变化减小
#### 推荐取样方式
在以下几个 x 位置取横截面:
- `x = 256`
- `x = 512`
- `x = 768`
只要中后段两条剖面几乎重合,就说明流场已经接近 fully developed,可拿来与抛物线拟合。
#### 预期结果
- 中段与后段 `ux(y)` 应近似抛物线 [Guo02d, Zou95b]
- 若 `fx` 增大,剖面整体抬高,但形状仍保持单峰抛物型
- 中段以后,剖面随 x 的变化应减弱
#### 如何定量判定
建议做三个量:
| 指标 | 解释 | 通过建议 |
|---|---|---|
| 抛物线拟合残差 | 用最小二乘拟合 `u(y)=a-b(y-yc)^2` | 中后段残差明显小于入口附近 |
| 发展段一致性 | 比较两个下游截面 | 两条曲线基本重合 |
| 横向速度污染 | `max |uy| / max |ux|` | 远小于 1 |
#### 关于误差的解释
不要把这个 case 解释得过头。因为当前代码的边界条件并不是“理想周期 x + 纯 body-force 驱动”,所以更合理的表述是:
- 这是一个**近 Poiseuille** 验证
- 它主要验证 `force_region` 是否能在长通道里生成正确的 fully-developed 流动结构
- 它不是对解析解逐点 machine-accuracy 的测试
另外,[Zou95b] 指出 bounce-back 边界会引入一阶壁面误差。因此如果壁面附近有明显偏差,不必立刻把它归咎于 `force_region` 本身;重点看的是中部剖面形状与下游收敛行为 [Zou95b]。
## Case C
### 幅值扫描
这个 case 用来回答:当前 operator-split forcing 在多大范围内是“线性可解释”的。
#### 设置建议
复用 Case B,只扫描 `fx`:
- `1e-6`
- `2e-6`
- `5e-6`
- `1e-5`
- `2e-5`
#### 预期结果
在小 force 区间内:
- 中心线速度大致随 `fx` 单调增加
- 抛物剖面形状保持不变,仅幅值放大
- 若开始出现明显非对称、密度波动或剖面畸变,说明已进入“不再适合作为线性基准”的区间
#### 该记录的量
- 中心线最大速度
- 下游某截面的体积流量
- `rho` 偏离 1 的最大值
这一步的目的不是证明某个严格比例律,而是找到一个**数值上舒服的工作区间**。后面做圆柱尾迹控制时,应优先选这个区间内的 force 幅值。
## Case D
### 网格与黏度稳健性
这是空间变化 forcing 必须做的检查,[Sil20b] 对这一点尤其值得参考。该文的核心提醒不是“所有非均匀 forcing 都会错”,而是:**空间变化 body force 更容易把离散误差暴露出来**,因此需要明确看网格和黏度敏感性 [Sil20b]。
#### 推荐做法
选用 Case B 或 Case A 中一个已经表现稳定的设置,然后做:
### 网格扫描
- `256 x 64`
- `512 x 128`
- `1024 x 256`
保持物理几何比例一致。
### 黏度扫描
固定一个小 force 幅值,扫两到三个 `nu`。
#### 预期结果
- 网格加密后,主剖面与主流结构应收敛
- 黏度变化会改变速度幅值和扩散尺度,但不应引入新的奇怪畸变
- 如果某个设置对黏度特别敏感,优先检查强迫是否过强、局部 Mach 数是否过高、或 region 是否离边界太近
#### 如何解读
[Sil20b] 的重点是在 TRT 下讨论空间变化 force 的离散误差来源,并指出某些 force 展开会引入额外不一致项。当前实现采用的是一个 operator-split 的局部 Guo 修正,而不是把空间变化 force 直接并入 `OneStep` 的逐格 collision。因此这一步更应被视为:
- 对当前实现的**数值稳健性检查**
- 而不是与 [Sil20b] 的离散系统逐条同构比较
## 第三层
### 研究使用前的圆柱尾迹验证
在前两层都通过后,再进入最关心的 case:圆柱尾迹中的局部 forcing。
这里最重要的不是先追一个“标准答案数值”,而是先建立**可解释的响应地图**。
## Case E
### 圆柱后方局部推流
可用你已经验证过的固定圆柱 baseline,先选最稳的低 Re 工况,例如二维层流涡街基线。
#### 建议设置
- 使用你当前已经验证可靠的 2D 固定圆柱基线
- 先选一个自然涡街清晰、但还不太剧烈的 Re
- force region 放在圆柱后方近尾迹区
例如:
- 圆柱中心 `(xc, yc)`
- force region 中心可先试:
- `(xc + 2D, yc)`
- `(xc + 3D, yc)`
- 半径先从 `0.3D` 到 `0.8D` 扫
- 先做 `fx > 0, fy = 0`
#### 该看什么
- 尾迹中心线速度是否回升
- 近尾迹回流区是否缩短
- `Cl` 振幅是否降低
- `Cd_mean` 是否变化
- 涡脱落频率 `St` 是否偏移
- streakline / vorticity 图是否出现更对称或更拉长的尾迹结构
#### 预期结果
对于圆柱尾迹中的外加 forcing,不同 forcing 形式都说明了同一个大方向:**局部强迫会改写尾迹结构、拖曳、升力波动与脱落频率**。[Kim05b] 虽然研究的是壁面 blowing/suction 而不是体力区,但其结果清楚表明:分布式 forcing 可以显著抑制或改变 Kármán 涡街,从而改变 mean drag 与 lift fluctuation [Kim05b]。
对当前 `force_region`,更合理的预期是:
- 小 `fx > 0`:尾迹被顺流“拉长”,回流区可能缩短
- 足够合适的位置和幅值下:`Cl_rms` 下降,尾迹更接近对称
- 过强 forcing:可能引入新的不稳定结构,而不是单调“变好”
#### 判定方式
建议不要只看一张图,至少同时记录:
| 量 | 作用 |
|---|---|
| `Cd_mean` | 看平均阻力变化 |
| `Cl_rms` | 看升力波动是否被抑制 |
| `St` | 看脱落频率是否移动 |
| vorticity / streakline 图 | 看结构是否更对称、更拉长、或出现新模态 |
#### 这个 case 的定位
这是**研究型验证**,不是严格 benchmark。
更准确地说,它回答的是:
- `force_region` 是否足够稳定和可控,能够进入尾迹控制实验
- 不同位置、半径、幅值是否产生可解释的流场响应
而不是:
- 某个单一数字是否必须匹配文献到几个百分点
## 推荐的执行顺序
建议按下面顺序推进。
| 顺序 | 算例 | 作用 |
|---|---|---|
| 1 | R1-R4 | 先清掉实现错误 |
| 2 | Case A | 验证最基本物理响应 |
| 3 | Case B | 做文献支持最强的主验证 |
| 4 | Case C | 找到安全幅值区间 |
| 5 | Case D | 看网格与黏度稳健性 |
| 6 | Case E | 进入圆柱尾迹研究 |
## 每个算例建议保存的输出
为了后面快速回看,建议每个 case 固定保存下面这些量。
| 输出 | 是否必需 | 说明 |
|---|---|---|
| 配置文件快照 | 必需 | 保证能复现实验 |
| `fx, fy` 与 region 几何 | 必需 | force center, radius, amplitude |
| 一张 `ux` 场图 | 必需 | 看主流响应 |
| 一张 vorticity 图 | 推荐 | 看结构变化 |
| 一条下游横截面 `ux(y)` | 必需 | Poiseuille 与 channel 类验证最关键 |
| `rho` 最大偏离 | 推荐 | 监控压缩性污染 |
| 若有圆柱:`Cd_mean`, `Cl_rms`, `St` | 必需 | 尾迹控制最关键 |
## 最低通过线
如果时间紧,只要先达到下面这三条,就可以开始把 `force_region` 用进研究实验:
1. **零强迫回归通过**
2. **静止流场中局部加速方向正确、幅值单调**
3. **长通道中下游横截面能稳定收敛到近抛物剖面**
做到这三条,说明这个新功能至少已经:
- 不破坏旧功能
- 有正确方向性
- 能在最经典的 body-force 场景中生成合理结构
## 如何解读失败
### 若 Case A 失败
优先怀疑:
- action slot 读写
- force region footprint
- `is_fluid(flag[k])` 过滤
- `ForceRegionKernel` 写回 DDF 的路径
### 若 Case B 失败
优先怀疑:
- force region 是否真的覆盖了足够长的通道中段
- inlet/outlet 是否过强地主导了解
- force 幅值是否太大
- 取样截面是否还在入口发展段
### 若 Case D 失败
优先怀疑:
- spatially varying forcing 本身的离散误差被放大
- 当前 operator-split 修正对该参数区间不够稳
- 需要收缩到更小 force、更低 Mach、更细网格
## 最后的建议
当前 `force_region` 最适合先被当作一个**研究工具**,而不是一开始就当作“已严格 benchmark 的标准物理模块”。最稳妥的路线是:
- 用 [Guo02d] 和 [Zou95b] 支撑主验证思路
- 用 [Sil20b] 提醒自己必须做稳健性检查
- 用 [Kim05b] 作为圆柱尾迹控制的高层参考,理解应该关注哪些响应量
这样做,既能尽快把功能用于研究,也不会把验证叙事说得过头。
## 参考依据
- Guo, Zheng, Shi 讨论了 forcing term 的离散效应,并将 steady Poiseuille flow 作为数值验证的一部分 [Guo02d]
- Zou, Hou, Doolen 给出了平板间 Poiseuille 流的解析解,并指出 bounce-back 壁面会引入一阶误差 [Zou95b]
- Silva 分析了空间变化 body force 在 LBM 中的离散误差来源,说明非均匀 forcing 必须做网格与黏度稳健性检查 [Sil20b]
- Kim 和 Choi 表明分布式 forcing 可以显著改变圆柱尾迹、drag、lift fluctuation 和 shedding mode,可作为圆柱尾迹研究阶段的高层参照 [Kim05b]
+247
View File
@@ -0,0 +1,247 @@
# Rotating cylinder validation against [Kan99b]
## Goal
This validation should stay small, direct, and defensible.
The main design rules are:
- use the paper's direct numeric anchor at `Re = 100, alpha = 1.0` as the main hard benchmark
- use a low-rotation case to test the lift trend
- use suppression cases to test flow classification, not exact threshold fitting
- do not treat values read from figures near `alpha_L` as tight amplitude targets
This keeps the matrix representative without overfitting to sensitive threshold points.
## Strong numeric anchors from [Kan99b]
The strongest exact benchmark in the paper is the convergence case at `Re = 100, alpha = 1.0`.
| Quantity | Reference value |
|---|---:|
| `St` | 0.1655 |
| `mean C_L` | -2.4881 |
| `mean C_D` | 1.1040 |
| `C'_L` | 0.3631 |
| `C'_D` | 0.0993 |
For low rotation at `Re = 100`, the paper also gives the mean lift trend
\[
\overline{C_L} \approx -2.48\alpha
\]
which is a good secondary benchmark for small `alpha`.
The suppression thresholds are given as trends:
| Reynolds number | Expected `alpha_L` |
|---|---:|
| 60 | about 1.4 |
| 100 | about 1.8 |
| 160 | about 1.9 |
These threshold values should be used as regime guides, not as tight one-point numeric targets. In the suppression curve from [Kan99b] shown above, the boundary is exactly the kind of place where a small solver difference can change the observed state.
## Fixed solver setup
| Item | Setting |
|---|---|
| Dimension | 2D |
| Lattice | D2Q9 |
| Streaming | double buffer |
| Curved boundary | current Bouzidi moving wall implementation |
| Inlet profile | uniform |
| Top and bottom boundaries | free slip |
| Outlet | neq extrapolation |
| LES | off |
| Precision | FP32 |
| Cylinder diameter | `D = 30` lattice units |
| Cylinder radius | `R = 15` lattice units |
| Rotation input | update body omega only |
The baseline domain remains the current medium far field unless a later boundary sensitivity check shows otherwise.
## Inlet recommendation by collision model
Kan99b is an open-flow validation, not a confined-channel benchmark.
| Collision | Recommended inlet | Secondary choice | Avoid as primary |
|---|---|---|---|
| SRT | `equilibrium` | `regularized` | `zou_he_local` |
| TRT | `regularized` | `equilibrium` | `zou_he_local` until the anchor is stable |
| MRT | `regularized` or `zou_he_local` | `equilibrium` | `channel_stabilized` |
Keep one inlet family per collision model across the primary matrix.
## Lattice-unit mapping
Use
\[
U_\infty = 0.03
\]
With `D = 30`,
\[
\nu = \frac{U_\infty D}{Re} = \frac{0.9}{Re}
\]
| `Re` | `nu` | SRT equivalent `omega` |
|---|---:|---:|
| 60 | 0.015000 | 1.83486 |
| 100 | 0.009000 | 1.89753 |
| 160 | 0.005625 | 1.93470 |
The body rotation rate is
\[
\omega_{body} = \frac{2 \alpha U_\infty}{D} = 0.002\alpha
\]
| `alpha` | body omega |
|---|---:|
| 0.5 | 0.0010 |
| 1.0 | 0.0020 |
| 1.6 | 0.0032 |
| 2.0 | 0.0040 |
## Primary matrix
This is the recommended main validation set.
| Case | `Re` | `alpha` | Role |
|---|---:|---:|---|
| K1 | 100 | 0.5 | low-rotation lift trend check |
| K2 | 100 | 1.0 | strongest hard anchor |
| K3 | 60 | 1.6 | low-Re suppression classification |
| K4 | 100 | 2.0 | mid-Re suppression classification |
| K5 | 160 | 2.0 | high-Re suppression classification |
Optional baseline if needed for debugging or plots:
| Case | `Re` | `alpha` | Status |
|---|---:|---:|---|
| K0 | 100 | 0.0 | optional |
This matrix covers:
- one periodic low-rotation trend point
- one exact hard anchor with full force data
- suppression behavior at low, medium, and high Reynolds number
## How to judge each case
### K1
Use K1 to check the low-rotation lift law.
Target:
\[
\overline{C_L} \approx -2.48 \times 0.5 \approx -1.24
\]
This is a trend check, not a strict fluctuation-amplitude benchmark.
### K2
Use K2 as the hard benchmark case.
Preferred agreement band:
| Quantity | Preferred band |
|---|---:|
| `St` | within 3 percent |
| `mean C_L` | within 4 percent |
| `mean C_D` | within 5 percent |
| `C'_L` | within 8 percent |
| `C'_D` | within 10 percent |
### K3 to K5
Use K3 to K5 as suppression classification cases.
Primary success signature:
- `C'_L` collapses toward zero in the final window
- no sustained alternating wake remains
- flow classification agrees with the expected suppressed regime
These are not exact threshold-fitting cases. Do not over-interpret a small residual fluctuation if the wake is otherwise clearly in the suppressed class.
## Optional threshold bracket check
If later you want a more explicit threshold study, use pairs around `alpha_L` rather than a single point on the boundary.
Recommended pairs:
| `Re` | Lower point | Upper point |
|---|---:|---:|
| 60 | 1.3 | 1.5 |
| 100 | 1.7 | 1.9 |
| 160 | 1.8 | 2.0 |
These should still be treated as regime-location checks, not hard force targets.
## Run policy
| Case type | Total steps | Warmup | Statistics |
|---|---:|---:|---:|
| K1 and K2 | 180000 to 220000 | first 40 percent | last 60 percent |
| K3 to K5 | 220000 to 280000 | first 50 percent | last 50 percent |
The final statistics window should contain at least 20 shedding periods whenever the case remains periodic.
## TRT re-entry rule
Bring TRT back in this order:
1. K2 only
2. if K2 is stable and credible, run K1
3. only then run K3 to K5
This prevents TRT from expanding the matrix before the hard anchor is trustworthy.
## Deliverables
For each collision model, deliver:
- one table of run settings including collision, inlet scheme, wall type, `Re`, `alpha`, `nu`, and body omega
- one CSV per run with force history
- selected field images for wake classification
- one summary table with `mean C_D`, `mean C_L`, `C'_D`, `C'_L`, and `St`
- one short note stating whether suppression behavior matches [Kan99b]
## Recommended primary settings summary
| Collision | Wall | Inlet | Status |
|---|---|---|---|
| SRT | free slip | `equilibrium` | primary |
| TRT | free slip | `regularized` | primary if K2 is stable |
| MRT | free slip | `regularized` or `zou_he_local` | primary |
## MRT-only runner mapping
The current executable entrypoint is `tests/run_kan99b_rotating_cylinder.py`, and this round uses MRT-only scheduling:
- primary matrix is `K1-K5` with `MRT + regularized` inlet
- one extra control run is added at K2 with `MRT + zou_he_local`
- all runs keep `uniform` inlet profile, `free_slip` y-wall, `neq_extrap` outlet
- output rows include `case_id`, `variant`, `collision`, `inlet_scheme`, `grid`, `steps`, `burn_in`, `St`, `St_error_pct` (for K2), and force metrics
- K2 gate uses this document's per-metric tolerances for `St`, `mean C_L`, `mean C_D`, `C'_L`, `C'_D`
Example commands:
```bash
conda run -n pycuda_3_10 python tests/run_kan99b_rotating_cylinder.py \
--json-out tests/output/kan99b_validation/summary_runs.json
conda run -n pycuda_3_10 python tests/run_kan99b_rotating_cylinder.py \
--case K2 --save-vorticity
```
## Reference
[Kan99b] S. Kang, H. Choi, and S. Lee, “Laminar flow past a rotating circular cylinder,” 1999.
+243
View File
@@ -0,0 +1,243 @@
# Sah04 confined-cylinder validation against [Sah04]
## Goal
This validation should use a small set of direct periodic anchors from [Sah04], plus a small secondary block for near-onset flow-state checks.
The main design rules are:
- do not use interpolated values from figures as hard targets
- do not use points on or extremely near critical curves as primary pass fail anchors
- report realized blockage and realized Reynolds number, not just nominal inputs
- use finer grids for high blockage so the narrow wall gaps are not under-resolved
This keeps the primary matrix small but still representative across moderate and high confinement.
## What counts as a hard benchmark from [Sah04]
The strongest periodic-flow anchors are the direct DNS values stated in the paper for developed unsteady states.
| Case | Blockage `beta` | Reynolds number | `St` target | Why it is a hard anchor |
|---|---:|---:|---:|---|
| S1 | 0.3 | 100 | 0.2115 | direct periodic DNS value |
| S2 | 0.5 | 200 | 0.3513 | direct periodic DNS value |
| S3 | 0.8 | 160 | `T ≈ 1.806`, so `St ≈ 0.5537` | direct case given in the paper |
| S4 | 0.9 | 200 | 0.5314 | direct periodic DNS value |
These should be the primary Sah04 validation anchors.
## What should not be a hard target
The following are useful for qualitative or secondary checks, but not for the main validation gate:
- critical onset values from Table IV
- any `St` or force value obtained by reading or interpolating a plot
- cases chosen only to complete a rectangular parameter grid
- points too close to the codimension two region or nearby neutral stability boundaries
This matters because the paper's stability map has several sensitive regions, especially at high blockage and near symmetry breaking. In the stability figure from [Sah04] shown above, those boundaries are exactly where a small setup difference can change the observed state.
## Geometry and blockage mapping
Keep the confined-channel layout and no-slip walls.
The validation table must always report both nominal and realized blockage.
With `D = 30` lattice units, the recommended realizations are:
| Case | `beta_nominal` | Suggested `H` | `beta_real` | Notes |
|---|---:|---:|---:|---|
| S1 | 0.3 | 100 | 0.3000 | exact |
| S2 | 0.5 | 60 | 0.5000 | exact |
| S3 | 0.8 | 38 or 37 | 0.7895 or 0.8108 | pick one and report it explicitly |
| S4 | 0.9 | 33 | 0.9091 | use this, not `H = 35` |
Do not silently rename `beta_real` as the paper blockage.
## Grid density policy
High blockage cases need more wall-normal resolution than the base grid.
Minimum rule:
- for `beta < 0.8`, the baseline grid with `D = 30` is acceptable for the first pass
- for `beta >= 0.8`, increase grid density by at least 2 times in each spatial direction before treating the result as validation quality
A practical way to do this is to keep geometry similarity while doubling the characteristic resolution:
- base cases: `D = 30`
- high blockage validation cases: at least `D = 60`
Recommended high blockage realizations on the refined grid:
| Case | `beta_nominal` | Suggested refined `D` | Suggested refined `H` | `beta_real` |
|---|---:|---:|---:|---:|
| S3 | 0.8 | 60 | 75 | 0.8000 |
| S4 | 0.9 | 60 | 67 | 0.8955 |
The point of this refinement is not only bulk accuracy. It is also to resolve the narrow cylinder wall gaps and reduce the risk that blockage effects are dominated by lattice geometry error.
## Primary matrix
This is the main Sah04 validation set.
| Case | `beta_nominal` | Primary target | Role |
|---|---:|---|---|
| S1 | 0.3 | `Re = 100`, `St = 0.2115` | moderate blockage periodic anchor |
| S2 | 0.5 | `Re = 200`, `St = 0.3513` | medium blockage periodic anchor |
| S3 | 0.8 | `Re = 160`, `St ≈ 0.5537` | high blockage periodic anchor |
| S4 | 0.9 | `Re = 200`, `St = 0.5314` | very high blockage periodic anchor |
This matrix is smaller than the older grid, but it covers:
- moderate confinement
- stronger confinement
- high blockage periodic shedding
- very high blockage periodic shedding
## Secondary onset block
These cases are recommended as flow-state checks, not hard `St` benchmarks.
| Case | `beta_nominal` | Suggested `Re` | Why it is useful | How to judge it |
|---|---:|---:|---|---|
| SO1 | 0.5 | about 130 | safely above first onset without sitting on the boundary | confirm sustained periodic state |
| SO2 | 0.7 | about 120 | tests near-onset behavior in a more sensitive blockage range | confirm sustained periodic state |
These points exist to answer a different question from the primary matrix:
- does the solver enter and maintain the right flow regime once slightly above onset
For SO1 and SO2, judge by:
- persistent nonzero `C'_L`
- a clean dominant spectral peak
- repeatable periodic wake structure
Do not fail these runs because the measured `St` differs slightly from a value read from a nearby figure.
## Inlet and wall policy
Sah04 is a confined-channel benchmark, so inlet consistency matters more than inlet variety.
| Collision | Wall | Inlet | Status |
|---|---|---|---|
| SRT | no slip | `channel_stabilized` | primary |
| TRT | no slip | `channel_stabilized` | primary |
| MRT | no slip | `channel_stabilized` | primary |
Keep the inlet family fixed across collision models in the primary matrix.
Secondary inlet comparison, only after the primary set is working:
| Collision | Optional inlet | Status |
|---|---|---|
| MRT | `regularized` or `zou_he_local` | exploratory |
| SRT or TRT | `equilibrium` or `regularized` | exploratory |
## Realized Reynolds number check
This is mandatory for Sah04.
For each run, record:
- nominal inlet definition
- developed downstream velocity profile
- measured `U_max,real`
- measured bulk velocity if available
- `beta_nominal`
- `beta_real`
- `Re_nominal`
- `Re_real`
Use the paper-consistent label
\[
Re_{real} = \frac{U_{max,real} D}{\nu}
\]
for the final comparison table.
If `Re_real` drifts materially from the intended target, treat that as a setup problem before treating it as a Strouhal miss.
## Run policy
| Case block | Total steps | Burn | Statistics |
|---|---:|---:|---:|
| S1 and S2 | 100000 to 160000 | first 35 to 40 percent | last 60 to 65 percent |
| S3 and S4 | 180000 to 260000 | first 45 percent | last 55 percent |
| SO1 and SO2 | 140000 to 220000 | first 45 percent | last 55 percent |
For high blockage refined runs, prefer the longer end of the window.
## Evaluation rule
Use a two-layer rule.
### Primary periodic anchors
| Case | Hard target use |
|---|---|
| S1 to S4 | hard periodic benchmark anchors |
Preferred agreement band:
- within 5 percent when `Re_real` is close to target and the spectrum is clean
- within 10 percent still acceptable if the run is clearly periodic and the residual mismatch is explainable by `Re_real` drift or geometry realization
### Secondary onset block
| Case | Hard target use |
|---|---|
| SO1 and SO2 | no hard `St` gate |
Success means:
- the flow is clearly unsteady and periodic
- the dominant frequency is stable over long windows
- the wake classification is consistent with being above onset
## Deliverables
For each run, deliver:
- one row with `beta_nominal`, `beta_real`, `Re_nominal`, `Re_real`, `nu`, collision, wall type, inlet scheme, and grid resolution
- one downstream velocity-profile plot
- one force-history CSV
- one `St` estimate with the exact analysis window stated
- selected wake images for flow classification
## Recommended minimum set
If compute budget is tight, run this order first:
| Priority | Runs |
|---|---|
| 1 | MRT on S1 to S4 |
| 2 | SRT on S2 and S4 |
| 3 | TRT on S2 and S4 |
| 4 | SO1 and SO2 only after the primary anchors are behaving |
## MRT-only runner mapping
The current executable entrypoint is `tests/run_sah04_st_matrix.py`, and it is now aligned to this document's primary S1-S4 matrix:
- collision is fixed to `MRT`
- inlet is fixed to `parabolic + channel_stabilized`
- case set is `S1-S4` only
- output rows include `case_id`, `collision`, `inlet_scheme`, `grid`, `steps`, `burn_in`, `St`, `St_error_pct`, `Re_real`, `beta_real`
- default hard gate is 5% (`--gate-pct` can relax it to 10%)
Example commands:
```bash
conda run -n pycuda_3_10 python tests/run_sah04_st_matrix.py \
--json-out tests/output/sah04_mrt/summary.json
conda run -n pycuda_3_10 python tests/run_sah04_st_matrix.py \
--case S3 --gate-pct 10 --final-vorticity-dir tests/output/sah04_mrt/vorticity
```
## Reference
[Sah04] M. Sahin and R. G. Owens, “A numerical investigation of wall effects up to high blockage ratios on two-dimensional flow past a confined circular cylinder,” 2004.
+181
View File
@@ -0,0 +1,181 @@
229:无控制:
```
SIGNAL_FEATURES0 = {
'action1': {
'mean': 0.0,
'components': [
(0.1354, 0.0, 1.600),
]
},
'action2': {
'mean': -0.0,
'components': [
(0.1354, 0.0, 2.099),
]
},
'action3': {
'mean': 0.0,
'components': [
(0.1354, 0.0, 1.639),
]
}
}
```
234:隐身:
```
SIGNAL_FEATURES1 = {
'action1': {
'mean': 0.0,
'components': [
(0.1354, 0.0, 1.600),
]
},
'action2': {
'mean': -0.01806,
'components': [
(0.1354, 0.0, 2.099),
]
},
'action3': {
'mean': 0.01806,
'components': [
(0.1354, 0.0, 1.639),
]
}
}
```
欺骗:
237 238 253:
```
SIGNAL_FEATURES2 = {
'action1': {
'mean': 0.0,
'components': [
(0.1354, 0.0026, 1.600), # 主频
]
},
'action2': {
'mean': -0.008730,
'components': [
(0.1354, 0.0045, 2.099), # 主频
(0.2708, 0.0010, 0.612),
]
},
'action3': {
'mean': 0.008730,
'components': [
(0.1354, 0.0045, 1.639), # 主频
(0.2708, 0.0010, -2.962),
]
}
}
```
257:
```
SIGNAL_FEATURES3 = {
'action1': {
'mean': 0.0,
'components': [
(0.1354, 0.0029, -2.619), # 主频
(0.2708, 0.0008, 2.856),
]
},
'action2': {
'mean': -0.0140,
'components': [
(0.1354, 0.0050, -0.933), # 主频
(0.2708, 0.0010, 0.801),
(0.1806, 0.0003, 1.854),
]
},
'action3': {
'mean': 0.014,
'components': [
(0.1354, 0.0050, -1.398), # 主频
(0.2708, 0.0010, 2.208),
(0.1806, 0.0003, 1.810),
]
}
}
```
260 (f*1.5):
```
SIGNAL_FEATURES4 = {
'action1': {
'mean': 0.0,
'components': [
(0.2031, 0.0026, 1.600), # 主频
]
},
'action2': {
'mean': -0.008730,
'components': [
(0.2031, 0.0045, 2.099), # 主频
(0.4062, 0.0010, 0.612),
]
},
'action3': {
'mean': 0.008730,
'components': [
(0.2031, 0.0045, 1.639), # 主频
(0.4062, 0.0010, -2.962),
]
}
}
```
262: (f*1.5):
```
SIGNAL_FEATURES5 = {
'action1': {
'mean': 0.0,
'components': [
(0.2031, 0.0029, -2.619), # 主频
(0.4062, 0.0008, 2.856),
]
},
'action2': {
'mean': -0.0140,
'components': [
(0.2031, 0.0050, -0.933), # 主频
(0.4062, 0.0010, 0.801),
(0.2709, 0.0003, 1.854),
]
},
'action3': {
'mean': 0.014,
'components': [
(0.2031, 0.0050, -1.398), # 主频
(0.4062, 0.0010, 2.208),
(0.2709, 0.0003, 1.810),
]
}
}
```
270 (f*2):
```
SIGNAL_FEATURES6 = {
'action1': {
'mean': 0.0,
'components': [
(0.2708, 0.0044, -2.619), # 主频
(0.8124, 0.0012, 2.856),
]
},
'action2': {
'mean': -0.014,
'components': [
(0.2708, 0.0075, -0.933), # 主频
(0.8124, 0.0015, 0.801),
(0.5418, 0.0005, 1.854),
]
},
'action3': {
'mean': 0.014,
'components': [
(0.2708, 0.0075, -1.398), # 主频
(0.8124, 0.0015, 2.208),
(0.5418, 0.0005, 1.810),
]
}
}
```
+493
View File
@@ -0,0 +1,493 @@
## Streakline postprocessing design
这份说明面向一个最小可实现的离线后处理程序。输入是按时间保存的二维速度场序列,输出是接近实验染色图的 streakline 图像。核心路线是连续释粒,因为 streakline 正是“固定位置持续释放染料后,在某个时刻所有已释放粒子的位置集合” [Lan96]。对非定常尾迹,这比单帧 streamline 更贴近实验图像 [Lan96]。
搜索和全文阅读给出的信息已经足够支撑第一版实现。最直接的方案是按保存时刻连续注入粒子,用时空插值后的速度场推进粒子,再将粒子云渲染为图像 [Lan96, Ken96]。如果纯粒子结果过于尖锐,再在推进后加入一个很小的随机扩散项,作为对真实染色液扩散的近似。更完整的被动标量法当然更物理,但实现成本更高,不适合作为第一版 [Kim04]。
## Core recommendation
| 方法 | 与实验染色图的对应 | 实现复杂度 | 适合作为第一版 |
|---|---|---:|---|
| 单帧 streamline | 弱 | 很低 | 不推荐 |
| 连续释粒 streakline | 强 | 低 | 最推荐 |
| streakline 加少量扩散 | 很强 | 低到中 | 推荐作为第二步 |
| 被动标量对流扩散 | 最强 | 中到高 | 暂不作为第一版 |
最小可实现路线如下:
- 从 CelerisLab 导出一串二维速度场快照 `u_x(x,y,t_k), u_y(x,y,t_k)`
- 选定一个固定释放点或一小段释放线
- 在每个保存时刻都注入新粒子
- 在两个相邻快照之间,用时间插值和空间插值计算粒子速度
- 用二阶或四阶时间积分推进粒子
- 删去出域粒子与进入固体的粒子
- 将当前时刻存活粒子按位置和年龄渲染成图像
这个程序逻辑直接对应 [Lan96] 的 streakline 算法,插值与推进细节由 [Ken96] 和 [Dar96] 支撑。
## Data contract
默认输入是规则 Cartesian 网格上的二维时间序列速度场。对当前项目,最自然的输入约定是:
| 名称 | 含义 |
|---|---|
| `t_k` | 第 `k` 个保存时刻 |
| `ux[k, j, i]` | 时刻 `t_k` 的 x 方向速度 |
| `uy[k, j, i]` | 时刻 `t_k` 的 y 方向速度 |
| `mask[j, i]` | 可选,固体与流体标记 |
| `x_i, y_j` | 网格坐标 |
第一版最好满足下面三条:
- 时间快照间隔固定或至少已知
- 网格坐标固定不动
- 固体几何位置已知,至少能判断粒子是否进入圆柱内部
如果输出来自 CelerisLab,本质上只需要把每个保存时刻的 `ux, uy` 和对应时间写出来即可。算法本身是通用的,并不依赖 LBM 本身。
## Mathematical model for the base streakline
### Particle motion
粒子位置满足拉格朗日运动方程 [Lan96]:
\[
\frac{d \boldsymbol{x}}{dt} = \boldsymbol{u}(\boldsymbol{x}, t)
\]
其中
\[
\boldsymbol{x} = (x, y), \qquad \boldsymbol{u} = (u_x, u_y)
\]
积分形式为 [Lan96]:
\[
\boldsymbol{x}(t + \Delta t) = \boldsymbol{x}(t) + \int_t^{t+\Delta t} \boldsymbol{u}(\boldsymbol{x}(\tau), \tau) \, d\tau
\]
streakline 在观察时刻 \(t_n\) 的定义是:从固定释放位置 \(\boldsymbol{x}_s\) 在过去各时刻持续注入的粒子,在 \(t_n\) 时刻的全部位置集合 [Lan96]。
### Time interpolation
速度场只在离散时刻存储,所以必须做时间插值。对位于 \(t_k \le t \le t_{k+1}\) 的任意子步,最简单的做法是线性时间插值 [Ken96]:
\[
\delta = \frac{t - t_k}{t_{k+1} - t_k}
\]
\[
\boldsymbol{u}(\boldsymbol{x}, t) = (1 - \delta) \, \boldsymbol{u}_k(\boldsymbol{x}) + \delta \, \boldsymbol{u}_{k+1}(\boldsymbol{x})
\]
这里 \(\boldsymbol{u}_k(\boldsymbol{x})\) 和 \(\boldsymbol{u}_{k+1}(\boldsymbol{x})\) 仍需通过空间插值得到。
### Spatial interpolation
在规则网格上,第一版直接用双线性插值即可。虽然 [Ken96] 讨论的是非结构网格上的点定位与线性插值,但其一般原则完全适用于规则网格:
- 先定位粒子所在单元
- 再用单元顶点速度插值得到粒子点速度 [Ken96]
若粒子位于单元局部坐标 \((\xi, \eta) \in [0,1]^2\),四个角点速度为 \(\boldsymbol{u}_{00}, \boldsymbol{u}_{10}, \boldsymbol{u}_{01}, \boldsymbol{u}_{11}\),则
\[
\boldsymbol{u}(\xi, \eta) = (1-\xi)(1-\eta) \boldsymbol{u}_{00}
+ \xi (1-\eta) \boldsymbol{u}_{10}
+ (1-\xi)\eta \boldsymbol{u}_{01}
+ \xi\eta \boldsymbol{u}_{11}
\]
## Time integration choice
[Lan96] 和 [Ken96] 都直接使用四阶 Runge Kutta。对你的第一版程序,推荐两个选项:
| 积分器 | 优点 | 缺点 | 建议 |
|---|---|---|---|
| RK2 | 简洁,容易调试 | 精度一般 | 最小原型可用 |
| RK4 | 文献最一致,精度更稳 | 每步插值次数更多 | 默认推荐 |
RK4 的更新式为 [Lan96, Ken96]:
\[
\boldsymbol{x}_{n+1} = \boldsymbol{x}_n + \frac{1}{6}(\boldsymbol{a} + 2\boldsymbol{b} + 2\boldsymbol{c} + \boldsymbol{d})
\]
其中
\[
\boldsymbol{a} = \Delta t \, \boldsymbol{u}(\boldsymbol{x}_n, t_n)
\]
\[
\boldsymbol{b} = \Delta t \, \boldsymbol{u}(\boldsymbol{x}_n + \tfrac{1}{2}\boldsymbol{a}, t_n + \tfrac{1}{2}\Delta t)
\]
\[
\boldsymbol{c} = \Delta t \, \boldsymbol{u}(\boldsymbol{x}_n + \tfrac{1}{2}\boldsymbol{b}, t_n + \tfrac{1}{2}\Delta t)
\]
\[
\boldsymbol{d} = \Delta t \, \boldsymbol{u}(\boldsymbol{x}_n + \boldsymbol{c}, t_n + \Delta t)
\]
[Ken96] 特别强调,RK4 的每一个子步都要重新做点定位与时空插值。这在规则网格上不难实现,只是意味着一次完整步进需要四次速度查询 [Ken96]。
## Practical timestep guidance
第一版不必上自适应步长,但步长不能随意设大。搜索里最重要的精度提醒来自 [Dar96]:
- 非定常粒子积分的误差常常由时间离散控制,而不是概念本身
- 合理步长必须不大于流动主要非定常时间尺度的同量级 [Dar96]
- 若时间步过大,粒子轨迹会在拓扑上都出错,而不仅是位置略偏 [Dar96]
对当前项目,最简单的工程准则是:
\[
\Delta t_{trace} \le \min \bigl(\alpha_t \, \Delta t_{save},\; \alpha_x \, \frac{\Delta x}{\max |u|} \bigr)
\]
其中 \(\Delta t_{save}\) 是两个保存快照之间的时间间隔,\(\Delta x\) 是网格尺度。第一版可取:
- \(\alpha_t = 0.1 \sim 0.25\)
- \(\alpha_x = 0.25 \sim 0.5\)
这不是文献中的严格上界,而是结合 [Dar96] 的结论给出的实现准则:粒子推进子步既要显著小于保存间隔,也不要一子步跨过太多网格。
[Ken96] 还给了一个很实用的自适应思路:根据相邻速度方向夹角调节步长。如果速度方向变化太快就减半,变化很小就加倍 [Ken96]。这很适合后续增强版,但不属于第一版必需项。
## Base streakline algorithm
### Release strategy
最符合染色实验的是连续释粒 [Lan96]。第一版可用两种释放方式:
| 方式 | 适用场景 | 建议 |
|---|---|---|
| 单点释放 | 针头式染料入口 | 最简单 |
| 短线段释放 | 更像细缝或细带注入 | 更稳健 |
如果实验是在圆柱上游某一点持续释放染色液,第一版就直接使用单点释放。
### Particle state
每个粒子只需保存:
| 字段 | 含义 |
|---|---|
| `x, y` | 当前坐标 |
| `t_birth` | 释放时刻 |
| `age` | 当前年龄 |
| `alive` | 是否仍在域内 |
第一版不需要保存整条历史轨迹。因为你要的是当前时刻的 streakline 图,而不是每个粒子的 pathline 曲线。
**常见误区(务必区分)**
| 概念 | 画什么 | 是否等于水洞染色迹线 |
|---|---|---|
| **Streakline(迹线)** | 固定源点**持续释粒**,在观察时刻 \(t_n\) 画出**所有仍存活粒子的当前位置**(可带年龄衰减权重) | 是 |
| **Pathline(迹线/轨道)** | 单个粒子从释放到当前的**整条历史轨迹** | 否 |
| **错误实现** | 每隔一段时间放一个粒子,再把**所有粒子走过的路径段**全部叠加到图上 | 否(这是 pathline 叠加,不是 streakline) |
水洞实验:针头在固定点连续注 dye → 某一时刻拍照 → 看到的是“此刻染料粒子在流场里的分布”,一条下游色带由**不同释放时刻、当前仍在本流场中的粒子**共同构成,而不是把每个粒子从出生到现在的轨迹都画出来。
### Main loop pseudocode
```text
given velocity snapshots U[k] = {ux[k], uy[k]} at times t[k]
given seeding point or seeding segment S
initialize empty particle list P
for k = 0 to N-2:
inject new particles at source S at time t[k]
set t_local = t[k]
while t_local < t[k+1]:
dt = min(dt_trace, t[k+1] - t_local)
for each particle p in P with p.alive:
v = interpolate_velocity(p.position, t_local)
advance p by one integration step using RK2 or RK4
update p.age
if p leaves domain:
p.alive = false
if p enters solid body:
p.alive = false
t_local = t_local + dt
optionally remove very old particles
optionally render current particle cloud
```
这个结构与 [Lan96] 的离散 streakline 算法一致,只是把“从 `t_k` 到 `t_{k+1}` 的一次推进”细化成多个更小的粒子子步,以满足 [Dar96] 对精度的要求。
### Velocity query pseudocode
```text
function interpolate_velocity(position x, time t):
find k such that t[k] <= t <= t[k+1]
compute delta = (t - t[k]) / (t[k+1] - t[k])
u_k = bilinear_interpolation(U[k], x)
u_k1 = bilinear_interpolation(U[k+1], x)
return (1 - delta) * u_k + delta * u_k1
```
这是第一版最核心的数值部件。只要这部分实现正确,streakline 程序主体就很直接。
## Small diffusion particle model
当纯 streakline 太细、太锐利、不像染色液图像时,可以给每个粒子加一个很小的随机扩散项。这不是严格的被动标量求解,但能以很低代价增加染色带宽度。
### Guiding idea
[Kim04] 表明,染料图像更接近一个被动标量浓度场,其基本控制方程是对流扩散方程:
\[
\frac{\partial c}{\partial t} + \boldsymbol{u} \cdot \nabla c = D \nabla^2 c
\]
其中 \(c\) 是染料浓度,\(D\) 是扩散系数。对第一版粒子法,一个常见近似是将每个粒子的位置更新写成“对流加随机扩散”:
\[
\boldsymbol{x}_{n+1} = \boldsymbol{x}_n + \Delta \boldsymbol{x}_{adv} + \Delta \boldsymbol{x}_{diff}
\]
其中 \(\Delta \boldsymbol{x}_{adv}\) 由 RK2 或 RK4 给出,扩散项取二维各向同性随机增量:
\[
\Delta \boldsymbol{x}_{diff} = \sqrt{2 D \Delta t}
\begin{bmatrix}
\eta_x \\
\eta_y
\end{bmatrix}
\]
这里 \(\eta_x, \eta_y \sim \mathcal{N}(0,1)\)。
这个形式本身是对扩散过程的标准随机游走近似。搜索结果提醒,随机游走模型如果处理不当会产生假漂移与错误浓度偏置 [Mac92]。因此第一版的使用原则应当很克制:
- 只用于加入少量模糊和厚度
- 不把粒子密度当成严格浓度
- 不在强近壁统计上过度解读结果
### Diffusive particle update pseudocode
```text
for each particle p in P with p.alive:
x_adv = RK4_step(p.position, t_local, dt)
sigma = sqrt(2 * D * dt)
dx_rand = sigma * normal(0, 1)
dy_rand = sigma * normal(0, 1)
x_new = x_adv + [dx_rand, dy_rand]
if x_new leaves domain:
p.alive = false
else if x_new enters solid:
p.alive = false
else:
p.position = x_new
p.age += dt
```
### Choosing the diffusion level
第一版不必试图从真实染料物性严格标定 \(D\)。更实用的做法是把 \(D\) 当作视觉匹配参数,并保持它足够小,使图像结构仍主要由对流控制。
[Kim04] 用 Schmidt 数控制扩散强弱。若已有参考速度 \(U\) 和长度尺度 \(L\),则
\[
Sc = \frac{\nu}{D}
\]
也可写成
\[
D = \frac{\nu}{Sc}
\]
对第一版,可以用下面的思路选扩散强度:
| 目标效果 | 建议 |
|---|---|
| 只想让线条略微变厚 | 取较大 `Sc`,即很小的 `D` |
| 想模拟明显洗开和模糊 | 取较小 `Sc`,即较大的 `D` |
| 不确定 | 先从几乎看不出的弱扩散开始 |
因为当前目标是“少量扩散”,所以推荐先把扩散当成弱修饰,而不是主导机制。
## Rendering logic
最终图像不需要把每个粒子的完整轨迹都画出来。更像实验染色图的做法是把当前存活粒子投影到图像网格上,生成粒子密度图或带年龄权重的强度图。
### Minimal rendering choices
| 方法 | 图像风格 | 实现难度 |
|---|---|---:|
| 直接散点 | 最简陋 | 很低 |
| 网格计数直方图 | 像浓度图 | 低 |
| 高斯核累积 | 更平滑 | 低到中 |
第一版推荐:
- 把每个粒子投到像素网格
- 对像素做计数或加权累积
- 最后做一次轻微 Gaussian blur
这与先做完整被动标量相比便宜很多,但视觉上已经会很接近实验染色图。
### Optional particle weighting
可以给粒子一个简单权重:
\[
I = \sum_p w_p K(\boldsymbol{x} - \boldsymbol{x}_p)
\]
其中 \(K\) 是像素核或 Gaussian 核。第一版里,权重 \(w_p\) 可直接取 1,也可对年龄做衰减,例如:
\[
w_p = \exp\left(- \frac{\mathrm{age}_p}{\tau_f} \right)
\]
这样旧粒子会逐渐淡出,图像不会无限堆积。
## Boundary handling
这部分先按最小原则处理即可。
| 情况 | 第一版处理 |
|---|---|
| 粒子出计算域 | 直接删除 |
| 粒子进入圆柱内部 | 直接删除 |
| 粒子贴近边界滑动 | 暂不专门处理 |
| 扩散后跨入固体 | 直接删除 |
这样做的优点是简单稳妥。后续若发现近壁 streakline 误差明显,再考虑反射、投影或更物理的壁面处理。
## Minimal implementation plan
### Version 1
目标是尽快得到可信的 streakline 图:
- 读取 `ux, uy, t`
- 单点连续释粒
- 双线性空间插值
- 线性时间插值
- RK4 粒子推进
- 出域删除与入固体删除
- 粒子计数成图
### Version 2
在不改变主体架构的前提下增强视觉效果:
- 增加短线段释放
- 增加年龄衰减
- 增加弱随机扩散
- 用 Gaussian 核代替简单计数
### Version 3
若后续发现实验图像明显受扩散与混合主导,再转向更重的模型:
- 被动标量对流扩散
- 用 \(Sc\) 或 \(D\) 做参数标定 [Kim04]
## Design decisions that are already justified by the literature
下面这些设计已经有足够文献支撑,可以直接采用:
- 用 streakline 而不是 streamline 对应持续染色实验 [Lan96]
- 用连续释放粒子离线重构 streakline [Lan96]
- 用时空插值从离散速度快照查询粒子速度 [Ken96]
- 用 RK4 作为默认推进器 [Lan96, Ken96]
- 把步长取得明显小于保存时间间隔,并避免一次跨过太多网格 [Dar96]
- 若需要更像染料图,可以加入弱扩散,或后续上升到被动标量 [Kim04]
## Recommended default choices
| 项目 | 默认选择 |
|---|---|
| 释放方式 | 单点连续释粒 |
| 空间插值 | 双线性 |
| 时间插值 | 线性 |
| 积分器 | RK4 |
| 粒子子步 | 保存步长的 0.1 到 0.25 |
| 固体处理 | 入固体即删除 |
| 输出图像 | 粒子密度图加轻微模糊 |
| 扩散 | 默认关闭,作为第二步 |
## Bottom line
对当前项目,最简洁且足够准确的程序逻辑不是去解新的染料场,而是先做一个离线连续释粒 streakline 后处理器。它只依赖时间序列速度场,程序结构清楚,数值风险也集中在可控的几个环节:时空插值、积分步长和边界删除 [Lan96, Dar96, Ken96]。在此基础上,再增加一个弱随机扩散项,就能以很小代价把图像从“几何上正确的粒子线”推进到“更像实验染色照片”的粒子云 [Kim04]。
## CelerisLab implementation mapping
Current implementation lives in:
- library: `src/CelerisLab/common/streakline.py`
- Kan99b demo CLI: `tests/run_kan99b_streakline.py`
- experiment notebook: `tests/experiment.ipynb` (CLEAN 5/6)
Available runtime modes:
- `online`: sample `Simulation.get_macroscopic()` directly in memory (no velocity snapshot files).
- `offline`: replay from an existing snapshot directory and run the same streakline integrator.
Dense release support:
- base upstream points are expanded by `release_mode` (`point|line|strip`).
- `strip` mode densifies both cross-stream (`line_count`, `line_span`) and downstream (`downstream_count`, `downstream_spacing`) directions.
### Performance notes (why it can feel slow)
Streakline post-processing is **CPU-side** in the current stack:
1. **GPU→host velocity copies** dominate for large grids (`nx=6000, ny=1200`). Each `get_macroscopic()` pulls full `ux/uy` arrays.
2. Particle RK4 + bilinear interpolation runs in NumPy on CPU (vectorized over particles, not GPU).
3. Rendering accumulates polylines into an image (optionally multi-threaded via `ThreadPoolExecutor`).
Practical tuning:
| knob | effect |
|---|---|
| `sample_every` | larger → fewer host copies, faster, coarser streaks |
| `max_particle_age` | `None` → no hard cutoff; trails survive until boundary/solid |
| `num_threads` | `0` = auto; sets OpenBLAS/OMP threads for blur/host ops |
| `blur_sigma` | `0` disables Gaussian blur pass |
For `experiment.ipynb` triangle case, use **`render_streakline_density(..., minimal_axes=True)`** on the **final alive particle cloud** (`positions`, `ages`). Do **not** accumulate and draw full path history (`render_snapshot_trails` is pathline-style debug only).
### Clean render style (experiment)
`render_snapshot_trails` defaults:
- white background
- red streaks, brighter toward the downstream end (`fade_along_trail=True`)
- black filled cylinders
- no axes, labels, colorbar, or release-point markers
Example commands:
```bash
# Online in-memory streakline (no snapshot write)
conda run -n pycuda_3_10 python tests/run_kan99b_streakline.py \
--mode online --domain M --re 100 --alpha 1.0 \
--sample-every 300 --n-snapshots 20 \
--release-mode strip --line-count 7 --downstream-count 6
# Offline replay from existing velocity snapshots
conda run -n pycuda_3_10 python tests/run_kan99b_streakline.py \
--mode offline \
--snapshot-dir tests/output/final_validation_round/streakline_kan99b_k2/velocity_snapshots \
--release-mode strip --line-count 7 --downstream-count 6
```
+78
View File
@@ -0,0 +1,78 @@
# Round 3: FP16S and ddf_shifting compatibility
Date: 2026-06-03
Duration: 8+ hours of code + testing
## Summary of work
This round added and verified FP16S store precision and ddf_shifting mode compatibility across the body module, curved boundary, and diagnostics pipeline.
## Primary achievements
### 1. MRT shifting fix (critical)
**Problem discovered:** D2Q9 MRT is NOT shift-invariant in moment space because M(w) produces non-zero entries in m[1] (energy) and m[2] (energy^2). Previous assumption that "f - feq cancels weights pairwise" only holds for SRT/TRT (per-direction collision), not for MRT (moment-space collision).
**Fix applied:** When `USE_DDF_SHIFTING=1`, `collide_mrt` now:
1. Unshifts `g[i] += w[i]` at entry (physical space)
2. Performs full MRT collision in physical space
3. Reshifts `g[i] -= w[i]` at exit
**Verified:** `MRT + ddf_shifting + zou_he_local` produces K2 results with `amp_CL` recovering from 0.007 to 0.476.
**Note on D3Q19:** Has a `compute_feq` inconsistency (shifted feq applied to unshifted g) that needs fixing before D3Q19 shifting is usable.
### 2. ddf_shifting code fixes
| Fix | File | Status |
|-----|------|--------|
| Inlet west_velocity_rho_closure +5/6 correction | `inlet/common.cuh` | Verified, both D2Q9 and D3Q19 |
| Curved force/torque +2*w_i correction | `curved_boundary.cuh`, `aux_kernels.cu` | Verified |
| Host upload_ddf() asymmetry (subtract weights before upload) | `field.py` | Verified |
| Checkpoint streaming and ddf_shifting match check | `checkpoint.py` | Implemented |
### 3. Inlet knowns repair generalization (partial)
The `repair_zou_he_west_knowns_d2q9` function was moved from Zou-He-only to all west inlet schemes in `inlet_outlet.cuh`. This fixes free-slip y-wall contamination of ghost-node populations. However, this alone was insufficient to fix the regularized+shifting issue.
### 4. EsoPull curved boundary (from Round 2, documented here for posterity)
Verified against Kan99b K2: **bit-identical metrics** between double_buffer and esopull streaming.
Key architectural decisions:
- `streaming/esopull_semantic_helpers.cuh` -- single source of truth for physical-value semantics
- `MacroscopicEsoPullKernel` -- GPU-side diagnostics (not host raw decode)
- `Prepare + Apply` two-phase curved boundary
## Current compatibility matrix
### Verified (passes K2/Sah04 benchmarks)
| Config | Details |
|--------|---------|
| FP32 + MRT + double_buffer | Full validation (all Kan99b, Sah04) |
| FP32 + MRT + esopull | K2 bit-identical to double_buffer |
| FP16S + MRT + double_buffer | Sah04 S2 passes |
| ddf_shifting + MRT + zou_he_local | K2 amp_CL recovered, full validation pending |
### Known limitations
| Issue | Severity | Status |
|-------|----------|--------|
| FP16S K2 St deviation (0.170 vs 0.142) | Medium -- quantization noise in curved region | Documented, acceptable for low-Re research |
| FP16S S4 divergence at step 71420 | Medium -- high-blockage quantization + wall-gap | Use FP32 for high-blockage |
| ddf_shifting + regularized inlet + MRT | High -- suppressed shedding even after inlet repair | Regularized in shifting needs root cause. Use zou_he_local for now. |
| D3Q19 MRT shifting patch incomplete | Medium -- shifted feq applied to unshifted g | Not in 2D scope, TODO noted in code |
| ddf_shifting + esopull combined | Not verified | Both paths validated separately but not together |
## Key lessons recorded
1. **SRT/TRT are shift-invariant; MRT is NOT.** The weight vector w has non-zero moment space projection. Always shift/unshift around MRT.
2. **Repair_zou_he_west_knowns is NOT Zou-He-specific.** Every west inlet scheme using `west_velocity_rho_closure_d2q9()` needs it under free-slip y-walls.
3. **FP16S failure modes are specific:** Low-blockage (S2) is fine; rotating cylinder (K2) shows quantization sensitivity; high-blockage (S4) can diverge. Test all three regimes before claiming FP16S works.
4. **`compute_feq` in shifting mode returns `feq - w`, not `feq`.** This is correct for SRT/TRT (NEQ terms cancel w), but causes a bias when paired with an unshifted `g` (D3Q19 MRT case).
5. **Host DDF path is not symmetric under shifting.** `download_ddf()` adds back w; `upload_ddf()` (before fix) did not subtract w. This breaks host-side initialization, snapshot/restore, and add_vortex under shifting.
+45
View File
@@ -0,0 +1,45 @@
[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"
[project]
name = "CelerisLab"
version = "0.5.1"
description = "GPU-accelerated Lattice Boltzmann Method (LBM) CFD solver using CUDA"
readme = "README.md"
requires-python = ">=3.8"
license = {text = "MIT"}
authors = [
{name = "Frank14f"}
]
keywords = ["cfd", "lattice-boltzmann", "cuda", "gpu", "fluid-dynamics", "lbm"]
classifiers = [
"Development Status :: 3 - Alpha",
"Intended Audience :: Science/Research",
"Topic :: Scientific/Engineering :: Physics",
"License :: OSI Approved :: MIT License",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.8",
"Programming Language :: Python :: 3.9",
"Programming Language :: Python :: 3.10",
"Programming Language :: Python :: 3.11",
]
dependencies = [
"pycuda>=2020.1",
"numpy>=1.19.0",
"scipy>=1.5.0",
]
[project.urls]
Homepage = "https://github.com/frank14f/CelerisLab"
Repository = "https://github.com/frank14f/CelerisLab.git"
[tool.setuptools]
package-dir = {"" = "src"}
[tool.setuptools.packages.find]
where = ["src"]
[tool.setuptools.package-data]
"CelerisLab" = ["lbm/kernels/**/*.cu", "lbm/kernels/**/*.cuh", "lbm/kernels/**/*.h", "configs/*.json"]
+41
View File
@@ -0,0 +1,41 @@
from setuptools import setup, find_packages
with open("README.md", "r", encoding="utf-8") as fh:
long_description = fh.read()
setup(
name='CelerisLab',
version='0.5.1',
author='Frank14f',
description='GPU-accelerated Lattice Boltzmann Method (LBM) CFD solver using CUDA',
long_description=long_description,
long_description_content_type="text/markdown",
url='https://github.com/frank14f/CelerisLab',
packages=find_packages(where='src'),
package_dir={'': 'src'},
package_data={
'CelerisLab': [
'lbm/kernels/**/*.cu',
'lbm/kernels/**/*.cuh',
'lbm/kernels/**/*.h',
'configs/*.json',
],
},
install_requires=[
'pycuda>=2020.1',
'numpy>=1.19.0',
'scipy>=1.5.0',
],
python_requires='>=3.8',
classifiers=[
'Development Status :: 3 - Alpha',
'Intended Audience :: Science/Research',
'Topic :: Scientific/Engineering :: Physics',
'License :: OSI Approved :: MIT License',
'Programming Language :: Python :: 3',
'Programming Language :: Python :: 3.8',
'Programming Language :: Python :: 3.9',
'Programming Language :: Python :: 3.10',
'Programming Language :: Python :: 3.11',
],
)
+28
View File
@@ -0,0 +1,28 @@
# CelerisLab/__init__.py
"""
CelerisLab: GPU-Accelerated Computational Physics Simulation Library
Usage::
from CelerisLab import Simulation
sim = Simulation("configs/config_lbm.json")
sim.add_body("circle", center=(100, 50), radius=10)
sim.initialize()
sim.run(1000)
data = sim.get_macroscopic()
force = sim.read_force(0)
"""
__version__ = "0.5.0"
from . import common, cuda, lbm, body, config
try:
from .simulation import Simulation
__all__ = ["Simulation", "lbm", "body", "common", "cuda", "config",
"__version__"]
except ImportError as e:
import warnings
warnings.warn(f"Simulation not available: {e}", ImportWarning)
__all__ = ["lbm", "body", "common", "cuda", "config", "__version__"]
+21
View File
@@ -0,0 +1,21 @@
# CelerisLab/body/__init__.py
"""
Body / object management for immersed and rigid objects.
"""
from .objects import SimObject, ObjectState, ObjectControl
from .manager import ObjectManager
from .registry import BodyRegistry
from .sync_plan import BodySyncPlan
from .geometry.base import CutLink, SensorCell, Geometry
from .geometry.circle import CircleGeometry
from .coupling.soa_packer import pack_cut_links_to_soa, pack_sensor_to_soa
__all__ = [
"SimObject", "ObjectState", "ObjectControl",
"ObjectManager",
"BodyRegistry",
"BodySyncPlan",
"CutLink", "SensorCell", "Geometry",
"CircleGeometry",
"pack_cut_links_to_soa", "pack_sensor_to_soa",
]
+63
View File
@@ -0,0 +1,63 @@
# CelerisLab/body/action_smoother.py
"""
ActionSmoother — ramp object actions (velocity/force) to avoid
instantaneous jumps that cause lattice instability.
Modes:
NONE — no smoothing (default)
LINEAR_RAMP — linear ramp from 0 to target over [n_min, n_max] steps
EXPONENTIAL — exponential approach: a(t) = target * (1 - exp(-t/tau))
Usage::
smoother = ActionSmoother(mode="LINEAR_RAMP", n_min=0, n_max=500)
for step in range(total):
scaled = smoother.scale(raw_action, step)
# pass scaled action to kernel
"""
import numpy as np
from dataclasses import dataclass
from enum import Enum
class SmoothMode(Enum):
NONE = "NONE"
LINEAR_RAMP = "LINEAR_RAMP"
EXPONENTIAL = "EXPONENTIAL"
@dataclass
class ActionSmoother:
"""Scale actions with a ramp profile."""
mode: str = "NONE"
n_min: int = 0 # step at which ramp begins
n_max: int = 500 # step at which ramp reaches 1.0
tau: float = 100.0 # exponential time constant (steps)
def scale(self, action: np.ndarray, step: int) -> np.ndarray:
"""Return action * alpha(step)."""
alpha = self._alpha(step)
if alpha >= 1.0:
return action
return action * np.float32(alpha)
def _alpha(self, step: int) -> float:
if self.mode == "NONE" or self.mode == SmoothMode.NONE.value:
return 1.0
if self.mode == "LINEAR_RAMP" or self.mode == SmoothMode.LINEAR_RAMP.value:
if step <= self.n_min:
return 0.0
if step >= self.n_max:
return 1.0
return float(step - self.n_min) / float(self.n_max - self.n_min)
if self.mode == "EXPONENTIAL" or self.mode == SmoothMode.EXPONENTIAL.value:
if step <= self.n_min:
return 0.0
t = float(step - self.n_min)
return 1.0 - float(np.exp(-t / max(self.tau, 1.0)))
return 1.0
+4
View File
@@ -0,0 +1,4 @@
# CelerisLab/body/coupling/__init__.py
"""
Body-fluid coupling: SoA packing, force/torque exchange.
"""
+152
View File
@@ -0,0 +1,152 @@
# CelerisLab/body/coupling/soa_packer.py
"""
SoA packer -- transforms CutLink records into kernel-consumable SoA arrays.
Responsibilities:
- Pack CutLink[] -> 8-column SoA for CurvedLinkSoA.assign_host()
- Pack SensorCell[] -> 2-column SoA for SensorSoA.assign_host()
- Document the host-kernel SoA contract in one concentrated location.
Design:
This is the single host-side function that knows the kernel SoA layout.
Geometry builders (circle, polygon, mesh) produce CutLink[] and call this
function -- they do NOT know the SoA format. If the kernel SoA layout
changes in the future, only this file needs updating.
"""
from __future__ import annotations
from typing import List, Tuple
import numpy as np
from ..geometry.base import CutLink, SensorCell
# Convenience aliases kept for backward compat during refactoring.
# Geometry callers now produce CutLink[] which is packed here.
# The constants remain for the fallback classification used during
# cut-link enumeration in circle.py.
FALLBACK_CLASS_BOUZIDI = np.uint8(0)
FALLBACK_CLASS_HALFWAY_BOUNCEBACK = np.uint8(1)
def pack_cut_links_to_soa(
links: List[CutLink],
) -> Tuple[np.ndarray, np.ndarray, np.ndarray,
np.ndarray, np.ndarray, np.ndarray,
np.ndarray, np.ndarray]:
"""Pack CutLink list into 8-column SoA arrays for CurvedLinkSoA.
Output order matches CurvedLinkSoA.assign_host() signature::
fluid_idx (uint32), dir (uint8), q (float32),
body_id (int32), rx (float32), ry (float32),
rz (float32), fallback (uint8)
This is the single host-side SoA packing point.
All geometry builders (circle, polygon, mesh) call this same
function, isolating the kernel SoA layout from geometry logic.
Semantic contract for each column (reference for host and kernel readers):
fluid_idx
Linear index of the fluid cell whose lattice link crosses into solid.
This cell receives the Bouzidi-interpolated population on the next
pull step.
dir
Lattice direction from fluid_idx toward the solid neighbor (1..NQ-1).
q
Fractional distance fluid -> hit_point / fluid -> neighbor, in (0, 1].
Used by the kernel for Bouzidi interpolation weighting.
body_id
Object id used to look up wall velocity from the action buffer
(action[body_id * slot + slot - 1] = omega).
rx, ry, rz
Lever arm from body center to wall hit point (hit_point - center),
used by the kernel for torque accumulation:
torque_z = rx * fy - ry * fx (2D).
fallback
0 = Bouzidi linear interpolation is legal (donor cell is fluid and
in-domain). 1 = donor is invalid; use half-way bounce-back
fallback [Gin08b].
Args:
links: List of CutLink records from any geometry builder.
Returns:
8-element tuple of numpy arrays matching CurvedLinkSoA.assign_host().
"""
n = len(links)
if n == 0:
return (
np.zeros(0, dtype=np.uint32),
np.zeros(0, dtype=np.uint8),
np.zeros(0, dtype=np.float32),
np.zeros(0, dtype=np.int32),
np.zeros(0, dtype=np.float32),
np.zeros(0, dtype=np.float32),
np.zeros(0, dtype=np.float32),
np.zeros(0, dtype=np.uint8),
)
fluid_idx = np.empty(n, dtype=np.uint32)
directions = np.empty(n, dtype=np.uint8)
q_vals = np.empty(n, dtype=np.float32)
body_ids = np.empty(n, dtype=np.int32)
rx_vals = np.empty(n, dtype=np.float32)
ry_vals = np.empty(n, dtype=np.float32)
rz_vals = np.empty(n, dtype=np.float32)
fallback_vals = np.empty(n, dtype=np.uint8)
for i, cl in enumerate(links):
fluid_idx[i] = np.uint32(cl.fluid_idx)
directions[i] = np.uint8(cl.dir)
q_vals[i] = np.float32(cl.q)
body_ids[i] = np.int32(cl.body_id)
rx_vals[i] = np.float32(cl.rx)
ry_vals[i] = np.float32(cl.ry)
rz_vals[i] = np.float32(cl.rz)
fallback_vals[i] = np.uint8(cl.fallback)
return (fluid_idx, directions, q_vals, body_ids,
rx_vals, ry_vals, rz_vals, fallback_vals)
def pack_sensor_to_soa(
cells: List[SensorCell],
) -> Tuple[np.ndarray, np.ndarray]:
"""Pack SensorCell list into 2-column SoA arrays for SensorSoA.
Returns:
cells (uint32), obj_ids (int32) -- empty arrays if *cells* is empty.
"""
n = len(cells)
if n == 0:
return np.zeros(0, dtype=np.uint32), np.zeros(0, dtype=np.int32)
idx_arr = np.empty(n, dtype=np.uint32)
id_arr = np.empty(n, dtype=np.int32)
for i, sc in enumerate(cells):
idx_arr[i] = np.uint32(sc.idx)
id_arr[i] = np.int32(sc.body_id)
return idx_arr, id_arr
def pack_force_region_to_soa(
cells: List[SensorCell],
) -> Tuple[np.ndarray, np.ndarray]:
"""Pack SensorCell list into 2-column SoA for ForceRegionSoA.
Reuses SensorCell records since the footprint enumeration is identical
to sensor cells. Returns:
cells (uint32), obj_ids (int32) -- empty arrays if *cells* is empty.
"""
n = len(cells)
if n == 0:
return np.zeros(0, dtype=np.uint32), np.zeros(0, dtype=np.int32)
idx_arr = np.empty(n, dtype=np.uint32)
id_arr = np.empty(n, dtype=np.int32)
for i, sc in enumerate(cells):
idx_arr[i] = np.uint32(sc.idx)
id_arr[i] = np.int32(sc.body_id)
return idx_arr, id_arr
+239
View File
@@ -0,0 +1,239 @@
# CelerisLab/body/ddf_patch.py
"""
Host-side DDF patching for runtime body topology sync. (D2Q9 only)
When bodies are added or removed at runtime, the host DDF must be
patched so that newly-solid cells contain equilibrium (not stale
fluid values) and newly-fluid cells initialise from their neighbours.
Called by ``Simulation.sync_bodies()`` after topology rebuild and
before GPU upload.
All equilibrium calculations use ``lbm/equilibrium.py`` which is D2Q9-only.
D3Q19 DDF patching is not yet implemented on the host side.
"""
from __future__ import annotations
from typing import Optional
import numpy as np
import pycuda.driver as cuda
from ..lbm.descriptors import FLUID
from ..lbm.equilibrium import compute_feq_d2q9, compute_macro_from_ddf
def patch_ddf_for_body_sync(
field,
old_ddf: np.ndarray,
old_flags: np.ndarray,
new_flags: np.ndarray,
added_solid_mask: np.ndarray,
released_fluid_mask: np.ndarray,
curved_fluid_indices: np.ndarray | None = None,
) -> None:
"""Patch host-side DDF after a body topology change.
Operates on physical DDF (``field.ddf``). After patching, the caller
should call ``upload_patched_ddf()`` to push only the changed cells
to both GPU buffers.
Three patch types:
* ``old_fluid -> new_solid``: Write equilibrium at rest (rho=RHO, u=0)
so stale fluid values do not linger inside new solid cells.
* ``old_solid -> new_fluid``: BFS inward fill from surrounding old-fluid
cells. Layer-0 cells average their old-fluid neighbours; deeper layers
average the previously filled layer. Fallback: equilibrium at inlet
velocity.
* **Boundary fluid cells** (new curved boundary neighbours): If new
solid cells appear, the fluid cells just outside them (on curved
boundary links) are also set to equilibrium at their local velocity
(or rest if NaN), preventing abrupt-boundary instability.
Args:
field: LBMField instance (``field.ddf`` is modified in-place).
old_ddf: Physical DDF snapshot before topology change (n*NQ, float32).
old_flags: Flag array before topology change.
new_flags: Flag array after topology change.
added_solid_mask: Bool array -- True where fluid became solid.
released_fluid_mask: Bool array -- True where obstacle became fluid.
curved_fluid_indices: Optional array of fluid cell indices on curved
boundary links. When *added_solid_mask* has any True entries,
these cells are set to equilibrium at local velocity (or rest).
"""
_patch_added_solid(field, added_solid_mask)
_patch_boundary_fluid(field, curved_fluid_indices, added_solid_mask)
_patch_released_fluid(field, old_ddf, old_flags, released_fluid_mask)
def upload_patched_ddf(
field,
added_solid_mask: np.ndarray,
released_fluid_mask: np.ndarray,
curved_fluid_indices: np.ndarray | None = None,
) -> None:
"""Upload only the DDF cells that changed during patching.
Uses per-cell ``cuda.memcpy_htod`` for both ``ddf_gpu`` and
``temp_gpu``. Leaves all other cells (especially boundary cells
with NaN) untouched on the GPU, preserving their streaming-
compatible values from before the sync.
"""
changed_indices: set[int] = set()
changed_indices.update(np.where(added_solid_mask)[0].tolist())
changed_indices.update(np.where(released_fluid_mask)[0].tolist())
if curved_fluid_indices is not None:
changed_indices.update(curved_fluid_indices.tolist())
if not changed_indices:
field.invalidate_host_ddf_cache()
field._host_ddf_step = None
return
nq = field.nq
cell_bytes = nq * 4
ddf_ptr = int(field.ddf_gpu)
temp_ptr = int(field.temp_gpu)
for idx in sorted(changed_indices):
offset = idx * cell_bytes
cell_data = field.ddf[idx * nq:(idx + 1) * nq].tobytes()
cuda.memcpy_htod(ddf_ptr + offset, cell_data)
cuda.memcpy_htod(temp_ptr + offset, cell_data)
field.invalidate_host_ddf_cache()
field._host_ddf_step = None
# -- Internal helpers ---------------------------------------------------------
def _patch_added_solid(field, added_solid_mask: np.ndarray) -> None:
"""Write resting equilibrium for cells that became solid."""
if not np.any(added_solid_mask):
return
rho0 = field.cfg.rho
feq = compute_feq_d2q9(rho0, 0.0, 0.0)
indices = np.where(added_solid_mask)[0]
nq = field.nq
for idx in indices:
field.ddf[idx * nq:(idx + 1) * nq] = feq
def _patch_boundary_fluid(
field,
curved_fluid_indices: np.ndarray | None,
added_solid_mask: np.ndarray,
) -> None:
"""Patch fluid cells on new curved boundary links to local equilibrium."""
if curved_fluid_indices is None or len(curved_fluid_indices) == 0:
return
if not np.any(added_solid_mask):
return
nq = field.nq
feq_fallback = compute_feq_d2q9(field.cfg.rho, 0.0, 0.0)
for idx in curved_fluid_indices:
f = field.ddf[idx * nq:(idx + 1) * nq]
if np.any(np.isnan(f)):
field.ddf[idx * nq:(idx + 1) * nq] = feq_fallback
continue
rho, ux, uy = compute_macro_from_ddf(f)
feq = compute_feq_d2q9(float(rho), float(ux), float(uy))
field.ddf[idx * nq:(idx + 1) * nq] = feq
def _patch_released_fluid(
field,
old_ddf: np.ndarray,
old_flags: np.ndarray,
released_fluid_mask: np.ndarray,
) -> None:
"""BFS inward fill for cells that became fluid after body removal."""
if not np.any(released_fluid_mask):
return
nx, ny = field.nx, field.ny
nq = field.nq
old_is_fluid = (old_flags & FLUID) != 0
released = np.where(released_fluid_mask)[0]
filled = np.zeros(field.n, dtype=bool)
offsets = [
(-1, -1), (-1, 0), (-1, 1),
(0, -1), (0, 1),
(1, -1), (1, 0), (1, 1),
]
# Precompute macroscopic from old_ddf for old-fluid cells
# Skip cells with NaN (pre-existing body curvature may have
# contaminated boundary-fluid DDF values).
old_macro: dict[int, tuple[float, float, float]] = {}
fluid_indices = np.where(old_is_fluid)[0]
for idx in fluid_indices:
f = old_ddf[idx * nq:(idx + 1) * nq]
if np.any(np.isnan(f)):
continue
rho, ux, uy = compute_macro_from_ddf(f)
old_macro[idx] = (rho, ux, uy)
def _neighbours(idx: int):
x = idx % nx
y = idx // nx
for dx, dy in offsets:
xn, yn = x + dx, y + dy
if 0 <= xn < nx and 0 <= yn < ny:
yield xn + yn * nx
prev_layer_filled: dict[int, tuple[float, float, float]] = {}
remaining = set(released.tolist())
for idx in released:
nbrs = list(_neighbours(idx))
fluid_nbrs = [n for n in nbrs if n in old_macro]
if not fluid_nbrs:
continue
rho_avg = np.mean([old_macro[n][0] for n in fluid_nbrs])
ux_avg = np.mean([old_macro[n][1] for n in fluid_nbrs])
uy_avg = np.mean([old_macro[n][2] for n in fluid_nbrs])
feq = compute_feq_d2q9(float(rho_avg), float(ux_avg), float(uy_avg))
field.ddf[idx * nq:(idx + 1) * nq] = feq
filled[idx] = True
prev_layer_filled[idx] = (
float(rho_avg), float(ux_avg), float(uy_avg))
remaining.discard(idx)
# BFS layers
max_layers = max(nx, ny)
for _ in range(max_layers):
if not remaining:
break
current_layer: dict[int, tuple[float, float, float]] = {}
for idx in list(remaining):
nbrs = list(_neighbours(idx))
filled_nbrs = [n for n in nbrs if n in prev_layer_filled]
if not filled_nbrs:
continue
rho_avg = np.mean([prev_layer_filled[n][0] for n in filled_nbrs])
ux_avg = np.mean([prev_layer_filled[n][1] for n in filled_nbrs])
uy_avg = np.mean([prev_layer_filled[n][2] for n in filled_nbrs])
feq = compute_feq_d2q9(
float(rho_avg), float(ux_avg), float(uy_avg))
field.ddf[idx * nq:(idx + 1) * nq] = feq
filled[idx] = True
current_layer[idx] = (
float(rho_avg), float(ux_avg), float(uy_avg))
remaining.discard(idx)
prev_layer_filled = current_layer
# Fallback for any remaining unfilled cells
u_inlet = field.cfg.velocity
for idx in remaining:
y = idx // nx
ux_fallback = (
u_inlet * 4.0 * y * (ny - 1 - y) / ((ny - 1) ** 2)
if ny > 2 else u_inlet)
feq = compute_feq_d2q9(field.cfg.rho, float(ux_fallback), 0.0)
field.ddf[idx * nq:(idx + 1) * nq] = feq
+4
View File
@@ -0,0 +1,4 @@
# CelerisLab/body/geometry/__init__.py
"""
Geometry shape implementations for immersed / rigid bodies.
"""
+153
View File
@@ -0,0 +1,153 @@
# CelerisLab/body/geometry/base.py
"""
Geometry shape interface: uniform intermediate representation for all shapes.
Design:
Geometry is an abstract base that defines the interface for shape-specific
cut-link enumeration, sensor cell discovery, and flag mask generation.
The output is geometry-agnostic CutLink and SensorCell records -- no
boundary-method-specific fields leak into the geometry layer.
"""
from __future__ import annotations
from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import List, Optional, Tuple
import numpy as np
@dataclass
class CutLink:
"""One cut link: fluid node -> wall -> solid neighbor.
Geometry-agnostic intermediate record. Produced by circle/polygon/mesh
builders, consumed by the SoA packer. No Bouzidi-specific fields.
Fields:
fluid_idx: linear index of the fluid-side cell.
dir: lattice direction towards wall (1..NQ-1).
q: fractional distance along link, in (0, 1].
body_id: owning body id.
hit_x: wall hit-point x (lattice).
hit_y: wall hit-point y.
hit_z: wall hit-point z (0 for 2D).
rx: hit_x - center_x (torque lever arm).
ry: hit_y - center_y.
rz: hit_z - center_z (0 for 2D).
normal_x: inward-facing surface normal x at hit point (0 for 2D stub).
normal_y: inward-facing surface normal y at hit point (0 for 2D stub).
fallback: 0 = Bouzidi legal; 1 = half-way bounce-back required.
scheme_tag: reserved for future boundary-scheme selection (0 = Bouzidi).
motion_tag: reserved for future motion type (0 = stationary, 1 = rotating, 2 = translating).
"""
fluid_idx: int
dir: int
q: float
body_id: int
hit_x: float = 0.0
hit_y: float = 0.0
hit_z: float = 0.0
rx: float = 0.0
ry: float = 0.0
rz: float = 0.0
normal_x: float = 0.0
normal_y: float = 0.0
fallback: int = 0
scheme_tag: int = 0
motion_tag: int = 0
@dataclass
class SensorCell:
"""One sensor sampling cell."""
idx: int # linear cell index
body_id: int # owning body id
class Geometry(ABC):
"""Abstract geometry shape.
Subclasses implement shape-specific grid projection (cut links, sensor cells,
flag masks). The output is a list of CutLink / SensorCell records --
geometry-agnostic, boundary-method-agnostic.
"""
@property
@abstractmethod
def center(self) -> Tuple[float, ...]:
...
@abstractmethod
def build_cut_links(
self, nx: int, ny: int,
domain_flags: Optional[np.ndarray] = None,
) -> List[CutLink]:
"""Enumerate cut links for this shape.
Args:
nx, ny: Grid dimensions.
domain_flags: Optional uint16 flags array for donor-cell
fluid/solid classification. None = all donors assumed fluid.
Returns:
List of CutLink records (empty if zero links found).
"""
...
@abstractmethod
def build_sensor_cells(self, nx: int, ny: int) -> List[SensorCell]:
"""Enumerate sensor cells for this shape.
Args:
nx, ny: Grid dimensions.
Returns:
List of SensorCell records (empty if zero cells found).
"""
...
@abstractmethod
def build_flag_mask(self, nx: int, ny: int) -> np.ndarray:
"""Return (nx*ny,) uint16 flag mask with bits set for this shape.
This variant marks obstacle cells (``SOLID|OBSTACLE|BC_CURVED``).
Args:
nx, ny: Grid dimensions.
Returns:
uint16 array of shape (nx*ny,) with flag bits set for obstacle cells.
"""
...
@abstractmethod
def build_sensor_flag_mask(self, nx: int, ny: int) -> np.ndarray:
"""Return (nx*ny,) uint16 flag mask for sensor cells.
This variant marks sensor cells (``FLUID|SENSOR_FLAG``).
Args:
nx, ny: Grid dimensions.
Returns:
uint16 array of shape (nx*ny,) with flag bits set for sensor cells.
"""
...
def build_force_region_flag_mask(self, nx: int, ny: int) -> np.ndarray:
"""Return (nx*ny,) uint16 flag mask for force-region cells.
This variant marks force-region cells (``FLUID|FRC_REGION``).
Default implementation calls ``build_sensor_flag_mask`` for
subclasses that treat sensor and force-region identically.
Args:
nx, ny: Grid dimensions.
Returns:
uint16 array of shape (nx*ny,) with flag bits set for
force-region cells.
"""
return self.build_sensor_flag_mask(nx, ny)
+196
View File
@@ -0,0 +1,196 @@
# CelerisLab/body/geometry/circle.py
"""
Circle geometry: cut-link enumeration, sensor cells, flag mask.
2D only. For 3D, a separate SphereGeometry would be added.
"""
from __future__ import annotations
import math
from typing import List, Optional, Tuple
import numpy as np
from .base import CutLink, Geometry, SensorCell
from ...lbm.descriptors import (
FLUID, SOLID, OBSTACLE, BC_CURVED, SENSOR_FLAG, FRC_REGION,
D2Q9_EX, D2Q9_EY,
)
class CircleGeometry(Geometry):
"""Circular geometry for 2D immersed bodies and sensors."""
def __init__(self, cx: float, cy: float, radius: float) -> None:
self._cx = cx
self._cy = cy
self._radius = radius
@property
def center(self) -> Tuple[float, float]:
return (self._cx, self._cy)
# ------------------------------------------------------------------
# Cut-link enumeration
# ------------------------------------------------------------------
def build_cut_links(
self, nx: int, ny: int,
domain_flags: Optional[np.ndarray] = None,
) -> List[CutLink]:
"""Enumerate cut links for this circle.
Iterates the AABB bounding box around the circle, walks D2Q9
directions from each fluid cell, records links that cross the
circle boundary into solid.
Args:
nx, ny: Grid dimensions.
domain_flags: Optional uint16 flags array for donor-cell
fluid/solid classification. None = all donors assumed fluid.
Returns:
List of CutLink records (empty if zero links found).
"""
from ...common.preprocess import find_circle_intersection
cx, cy = self._cx, self._cy
r = self._radius
r_sq = r * r
# AABB clip
x0 = max(1, int(cx - r) - 2)
x1 = min(nx - 2, int(cx + r) + 2)
y0 = max(1, int(cy - r) - 2)
y1 = min(ny - 2, int(cy + r) + 2)
def _donor_is_fluid(xd: int, yd: int) -> bool:
if domain_flags is None:
return True
idx = xd + yd * nx
return (int(domain_flags[idx]) & FLUID) != 0
def _fallback_class(
q_val: float, donor_inside: bool,
donor_in_domain: bool, donor_is_fluid: bool,
) -> int:
if not (0.0 < q_val <= 1.0):
raise ValueError(
f"q must satisfy 0 < q <= 1, got {q_val}")
if q_val >= 0.5:
return 0
if (not donor_in_domain) or donor_inside or (not donor_is_fluid):
return 1
return 0
links: List[CutLink] = []
for x in range(x0, x1 + 1):
for y in range(y0, y1 + 1):
if (x - cx) ** 2 + (y - cy) ** 2 < r_sq:
continue
for i in range(1, 9): # D2Q9 non-zero directions
xn, yn = x + D2Q9_EX[i], y + D2Q9_EY[i]
if not (0 <= xn < nx and 0 <= yn < ny):
continue
if (xn - cx) ** 2 + (yn - cy) ** 2 >= r_sq:
continue
hit = find_circle_intersection(
float(x), float(y),
float(xn), float(yn),
cx, cy, r,
)
if hit is None:
continue
dx = hit[0] - x
dy = hit[1] - y
norm = math.sqrt(
float(D2Q9_EX[i]) ** 2 + float(D2Q9_EY[i]) ** 2)
q = (math.sqrt(dx * dx + dy * dy) / norm
if norm > 0 else 0.5)
q = max(0.01, min(q, 1.0))
xff = x - D2Q9_EX[i]
yff = y - D2Q9_EY[i]
donor_in_domain = (0 <= xff < nx and 0 <= yff < ny)
donor_inside = False
donor_is_fluid = False
if donor_in_domain:
donor_inside = (
(xff - cx) ** 2 + (yff - cy) ** 2
) < r_sq
donor_is_fluid = _donor_is_fluid(xff, yff)
links.append(CutLink(
fluid_idx=x + y * nx,
dir=i,
q=float(q),
body_id=0, # assigned during packing
hit_x=float(hit[0]),
hit_y=float(hit[1]),
hit_z=0.0,
rx=float(hit[0] - cx),
ry=float(hit[1] - cy),
rz=0.0,
normal_x=0.0,
normal_y=0.0,
fallback=_fallback_class(
q, donor_inside, donor_in_domain, donor_is_fluid),
scheme_tag=0,
motion_tag=1,
))
return links
# ------------------------------------------------------------------
# Sensor cells
# ------------------------------------------------------------------
def build_sensor_cells(self, nx: int, ny: int) -> List[SensorCell]:
"""Enumerate sensor cells inside the circular footprint.
Returns:
List of SensorCell records.
"""
cx, cy = self._cx, self._cy
r = self._radius
r_sq = r * r
x0 = max(1, int(cx - r) - 1)
x1 = min(nx - 2, int(cx + r) + 1)
y0 = max(1, int(cy - r) - 1)
y1 = min(ny - 2, int(cy + r) + 1)
cells: List[SensorCell] = []
for x in range(x0, x1 + 1):
for y in range(y0, y1 + 1):
if (x - cx) ** 2 + (y - cy) ** 2 < r_sq:
cells.append(SensorCell(idx=x + y * nx, body_id=0))
return cells
# ------------------------------------------------------------------
# Flag mask
# ------------------------------------------------------------------
def build_flag_mask(self, nx: int, ny: int) -> np.ndarray:
"""Return (nx*ny,) uint16 flag mask with OBSTACLE|SOLID|BC_CURVED."""
return self._build_flag_mask_inner(nx, ny, SOLID | OBSTACLE | BC_CURVED)
def build_sensor_flag_mask(self, nx: int, ny: int) -> np.ndarray:
"""Return (nx*ny,) uint16 flag mask with FLUID|SENSOR_FLAG."""
return self._build_flag_mask_inner(nx, ny, FLUID | SENSOR_FLAG)
def build_force_region_flag_mask(self, nx: int, ny: int) -> np.ndarray:
"""Return (nx*ny,) uint16 flag mask with FLUID|FRC_REGION."""
return self._build_flag_mask_inner(nx, ny, FLUID | FRC_REGION)
def _build_flag_mask_inner(self, nx: int, ny: int, flag_val: int) -> np.ndarray:
n = nx * ny
mask = np.zeros(n, dtype=np.uint16)
cx, cy = self._cx, self._cy
r = self._radius
r_sq = r * r
x0 = max(1, int(cx - r) - 1)
x1 = min(nx - 2, int(cx + r) + 1)
y0 = max(1, int(cy - r) - 1)
y1 = min(ny - 2, int(cy + r) + 1)
for x in range(x0, x1 + 1):
for y in range(y0, y1 + 1):
if (x - cx) ** 2 + (y - cy) ** 2 < r_sq:
mask[x + y * nx] = np.uint16(flag_val)
return mask
+765
View File
@@ -0,0 +1,765 @@
# CelerisLab/body/manager.py
"""
ObjectManager -- batch management of SimObjects.
Responsibilities:
- Add / remove / query objects (delegated to ``BodyRegistry``)
- Pending edit state for runtime body topology changes
- Build merged flag masks and compact cut-link / sensor lists
- Allocate packed telemetry ``obs_gpu`` + pagelocked mirror ``obs_pinned``
- Sync geometry to :class:`~CelerisLab.lbm.field.LBMField`
Design::
Packed ``obs`` layout matches ``generate_config(..., n_objects=count)`` and
``config_obs.h`` macros. Host sizing uses :func:`~CelerisLab.cuda.compiler_v2.obs_layout`.
Pending edits are lightweight: only the "intent" (add / remove) is stored.
All derived quantities (flags, compact lists, GPU buffers) are built at
``sync_bodies()`` time from the formal registry + pending edits.
"""
from __future__ import annotations
from typing import Dict, List, NamedTuple, Optional, TYPE_CHECKING
import numpy as np
import pycuda.driver as cuda
from .objects import SimObject
from .registry import BodyRegistry
from .preprocess.flag_overlay import merge_flag_masks
from ..cuda.compiler_v2 import obs_layout
from ..cuda.obs_layout import ObsLayout
from ..lbm.descriptors import (
D2Q9_EX,
D2Q9_EY,
D3Q19_EX,
D3Q19_EY,
D3Q19_EZ,
)
if TYPE_CHECKING:
from .sync_plan import BodySyncPlan
class BodyTelemetry(NamedTuple):
"""Unified telemetry for one body, read from the pinned obs buffer.
After ``run(sync_obs=True)``, all fields are populated from GPU results.
``sensor`` is a dim-length array — zeros for non-sensor bodies.
"""
force: np.ndarray
torque: np.ndarray
sensor: np.ndarray
class ObjectManager:
"""Central registry for all simulation objects.
Frozen telemetry layout::
``obs`` packs force, torque, then sensor segments.
Segment offsets and sizes come from :func:`obs_layout(dim, count)`.
Device macros ``OBS_*`` in ``config_obs.h`` must match ``obs_layout(dim, count)``.
"""
def __init__(self, nx: int, ny: int, nz: int, nq: int, cfg=None):
self.nx = nx
self.ny = ny
self.nz = nz
self.nq = nq
self.cfg = cfg
self._registry = BodyRegistry()
self.action_gpu: Optional[cuda.DeviceAllocation] = None
self.obs_gpu: Optional[cuda.DeviceAllocation] = None
self._action_nbytes: int = 0
self._obs_alloc_nbytes: int = 0
self.action = np.zeros(0, dtype=np.float32)
self.obs_pinned: Optional[np.ndarray] = None
self.obs_force_view: Optional[np.ndarray] = None
self.obs_torque_view: Optional[np.ndarray] = None
self.obs_sensor_view: Optional[np.ndarray] = None
self.sensor_cell_counts = np.zeros(0, dtype=np.int32)
self.slot_stride_floats: int = 0
self.torque_stride_floats: int = 0
self.torque_components: int = 0
self.torque0_floats: int = 0
self.sensor0_floats: int = 0
self.obs_total_floats: int = 0
self.obs_nbytes: int = 0
# -- Accumulated step count (for obs time-normalization) --------------
self._obs_accum_steps: int = 0
self._telemetry_field: Optional[object] = None
# -- Pending edit state (runtime body topology sync) -------------------
self._edit_active: bool = False
self._pending_add: List[SimObject] = []
self._pending_remove: set[int] = set()
# Ensure host action buffer is non-empty so CUDA alloc never sees 0 bytes
# when bodies.count == 0 (matches _resize_buffers sizing for n=0).
self._resize_buffers()
# -- Registry delegation -------------------------------------------------
def add(self, obj: SimObject) -> int:
"""Register an object and return its id."""
body_id = self._registry.add(obj)
self._resize_buffers()
return body_id
def remove(self, obj_id: int):
self._registry.remove(obj_id)
self._resize_buffers()
def get(self, obj_id: int) -> SimObject:
return self._registry.get(obj_id)
@property
def objects(self) -> List[SimObject]:
return self._registry.objects
@property
def count(self) -> int:
return self._registry.count
# -- Buffer sizing -------------------------------------------------------
def _resize_buffers(self):
n = self.count
dim = self.cfg.dim if self.cfg else 2
action_slot_floats = 3 * dim
new_action = np.zeros(max(n * action_slot_floats, 1), dtype=np.float32)
if self.action.size > 0:
copy_n = min(self.action.size, new_action.size)
new_action[:copy_n] = self.action[:copy_n]
self.action = new_action
new_sensor_counts = np.zeros(max(n, 1), dtype=np.int32)
if self.sensor_cell_counts.size > 0:
copy_n = min(self.sensor_cell_counts.size, new_sensor_counts.size)
new_sensor_counts[:copy_n] = self.sensor_cell_counts[:copy_n]
self.sensor_cell_counts = new_sensor_counts
# -- Pending edit state (runtime body topology sync) ---------------------
def stage_add(self, obj: SimObject) -> None:
"""Stage an object for addition at the next ``sync_bodies()``.
The object is not added to the formal registry until ``commit_pending()``
is called. This implicitly activates the edit window.
"""
self._edit_active = True
self._pending_add.append(obj)
def stage_remove(self, obj_id: int) -> None:
"""Stage removal of a formal object at the next ``sync_bodies()``.
Args:
obj_id: Id of a currently registered formal object.
Raises:
IndexError: If *obj_id* is not in the formal registry.
"""
self._validate_body_id(obj_id)
self._edit_active = True
self._pending_remove.add(obj_id)
def has_pending_edit(self) -> bool:
"""Return True if there are uncommitted staged edits."""
return self._edit_active and bool(self._pending_add or self._pending_remove)
def clear_pending_edits(self) -> None:
"""Discard all staged edits without applying them."""
self._pending_add.clear()
self._pending_remove.clear()
self._edit_active = False
# -- Sync plan construction (runtime body topology sync) -----------------
def build_next_objects(self) -> List[SimObject]:
"""Merge formal objects with pending edits into a new object list.
Formal objects whose id is in ``_pending_remove`` are excluded.
Objects in ``_pending_add`` are appended. All returned objects
receive consecutive ``obj_id = 0..n-1``.
Returns:
New list of SimObject copies with reassigned ids.
"""
def _copy(obj, oid):
new = SimObject(obj_id=oid, geometry=obj.geometry,
center=obj.center, radius=obj.radius,
is_sensor=obj.is_sensor,
is_force_region=obj.is_force_region)
new.state = obj.state
new.control = obj.control
return new
result: List[SimObject] = []
next_id = 0
for obj in self._registry.objects:
if obj.obj_id in self._pending_remove:
continue
result.append(_copy(obj, next_id))
next_id += 1
for obj in self._pending_add:
result.append(_copy(obj, next_id))
next_id += 1
return result
def build_sync_plan(self, field) -> 'BodySyncPlan':
"""Construct a full topology transition plan from pending edits.
Args:
field: ``LBMField`` instance (used for old flags and channel base).
Returns:
:class:`BodySyncPlan` describing the transition.
"""
from .sync_plan import BodySyncPlan
from ..lbm.descriptors import FLUID, OBSTACLE
old_flags = field.flag.copy()
next_objects = self.build_next_objects()
next_count = len(next_objects)
# Build new flags from clean channel base + new object set
base_flags = field.build_channel_flags()
next_flags = self.build_flags_for(
next_objects, base_flags,
nx=self.nx, ny=self.ny, nz=self.nz,
)
# Build compact lists for new object set
new_sensor_counts = np.zeros(max(next_count, 1), dtype=np.int32)
(
cl_fluid_idx, cl_dir, cl_q, cl_body_id,
cl_rx, cl_ry, cl_rz, cl_fallback_class,
sensor_cells, sensor_obj_id,
fr_cells, fr_obj_id,
) = self.build_compact_lists_for(
next_objects, domain_flags=next_flags,
sensor_cell_counts_out=new_sensor_counts,
)
# Compute change masks
old_is_solid = (old_flags & 0x0002) != 0
new_is_solid = (next_flags & 0x0002) != 0
old_is_obstacle = (old_flags & OBSTACLE) != 0
new_is_fluid = (next_flags & FLUID) != 0
added_solid_mask = (~old_is_solid) & new_is_solid
released_fluid_mask = old_is_obstacle & new_is_fluid
return BodySyncPlan(
next_objects=next_objects,
next_count=next_count,
next_flags=next_flags,
curved_host=(cl_fluid_idx, cl_dir, cl_q, cl_body_id,
cl_rx, cl_ry, cl_rz, cl_fallback_class),
sensor_host=(sensor_cells, sensor_obj_id),
force_region_host=(fr_cells, fr_obj_id),
added_solid_mask=added_solid_mask,
released_fluid_mask=released_fluid_mask,
new_sensor_counts=new_sensor_counts,
)
def commit_pending(self, next_objects: List[SimObject],
sensor_counts: np.ndarray) -> None:
"""Replace the formal registry with *next_objects* and clear pending edits.
Args:
next_objects: New formal object list with ``obj_id = 0..n-1``.
sensor_counts: New per-object sensor cell counts.
"""
self._registry.clear()
for obj in next_objects:
self._registry.add(obj)
self.sensor_cell_counts = sensor_counts.copy()
self._resize_buffers()
self.clear_pending_edits()
def apply_sync_plan(self, field, plan) -> None:
"""Apply topology data from a ``BodySyncPlan`` to the field.
Sets ``field.flag``, assigns compact list host arrays, uploads
compact lists, and refreshes action buffer from object state.
Args:
field: LBMField instance.
plan: BodySyncPlan from ``build_sync_plan()``.
"""
field.flag = plan.next_flags
field.upload_flags()
cl_host = plan.curved_host
field.curved.assign_host(*cl_host)
s_cells, s_ids = plan.sensor_host
field.sensors.assign_host(s_cells, s_ids)
fr_cells, fr_ids = plan.force_region_host
field.force_regions.assign_host(fr_cells, fr_ids)
field.upload_compact_lists()
field.update_params(n_objects=plan.next_count)
# -- Flag composition ----------------------------------------------------
def build_flags(self, base_flags: np.ndarray) -> np.ndarray:
"""Merge formal object flag masks onto a clean domain base."""
return self.build_flags_for(
self._registry.objects, base_flags,
nx=self.nx, ny=self.ny, nz=self.nz,
)
@staticmethod
def build_flags_for(objects: List[SimObject],
base_flags: np.ndarray,
*, nx: int, ny: int, nz: int) -> np.ndarray:
"""Merge object flag masks onto a clean domain base.
Args:
objects: List of SimObject instances.
base_flags: Fresh channel-layout flag array.
nx, ny, nz: Grid dimensions.
Returns:
New uint16 array with object overlays applied.
"""
masks = [obj.get_flag_mask(nx, ny, nz) for obj in objects]
return merge_flag_masks(base_flags, masks)
# -- Compact list building -----------------------------------------------
def build_compact_lists(self, domain_flags: np.ndarray | None = None):
"""Build cut-link SoA columns, sensor lists, and force-region lists
from the formal registry objects.
"""
return self.build_compact_lists_for(
self._registry.objects, domain_flags,
sensor_cell_counts_out=self.sensor_cell_counts,
)
def build_compact_lists_for(
self,
objects: List[SimObject],
domain_flags: np.ndarray | None = None,
*,
sensor_cell_counts_out: np.ndarray | None = None,
):
"""Build cut-link SoA columns, sensor lists, and force-region lists.
Args:
objects: List of SimObject instances to process.
domain_flags: Optional uint16 flags for donor-cell classification.
sensor_cell_counts_out: Int array to fill with per-object sensor
cell counts. If provided, ``fill(0)`` is called first.
Returns:
cl_fluid_idx, cl_dir, cl_q, cl_body_id, cl_rx, cl_ry, cl_rz,
cl_fallback_class,
sensor_cells, sensor_obj_id,
fr_cells, fr_obj_id
"""
cl_idx, cl_dir, cl_q, cl_bid = [], [], [], []
cl_rx, cl_ry, cl_rz, cl_fallback = [], [], [], []
s_cells, s_ids = [], []
fr_cells, fr_ids = [], []
if sensor_cell_counts_out is not None:
sensor_cell_counts_out.fill(0)
ez = None
if self.cfg and self.cfg.is_d3q19:
ex, ey, ez = D3Q19_EX, D3Q19_EY, D3Q19_EZ
else:
ex, ey = D2Q9_EX, D2Q9_EY
for obj in objects:
if (not obj.is_sensor) and (not obj.is_force_region) and hasattr(obj, 'get_curved_list'):
(
fluid_idx, dirs, q_vals, body_ids,
rx_vals, ry_vals, rz_vals, fallback_vals
) = obj.get_curved_list(
self.nx, self.ny, self.nq,
nz=self.nz, ex=ex, ey=ey, ez=ez,
domain_flags=domain_flags,
)
if len(fluid_idx) > 0:
cl_idx.append(fluid_idx)
cl_dir.append(dirs)
cl_q.append(q_vals)
cl_bid.append(body_ids)
cl_rx.append(rx_vals)
cl_ry.append(ry_vals)
cl_rz.append(rz_vals)
cl_fallback.append(fallback_vals)
if obj.is_sensor and hasattr(obj, 'get_sensor_list'):
cells, ids = obj.get_sensor_list(self.nx, self.ny, self.nz)
if len(cells) > 0:
s_cells.append(cells)
s_ids.append(ids)
if (sensor_cell_counts_out is not None
and 0 <= obj.obj_id < sensor_cell_counts_out.size):
sensor_cell_counts_out[obj.obj_id] = int(len(cells))
if obj.is_force_region and hasattr(obj, 'get_sensor_list'):
cells, ids = obj.get_sensor_list(self.nx, self.ny, self.nz)
if len(cells) > 0:
fr_cells.append(cells)
fr_ids.append(ids)
r_idx = np.concatenate(cl_idx) if cl_idx else np.zeros(0, dtype=np.uint32)
r_dir = np.concatenate(cl_dir) if cl_dir else np.zeros(0, dtype=np.uint8)
r_q = np.concatenate(cl_q) if cl_q else np.zeros(0, dtype=np.float32)
r_bid = np.concatenate(cl_bid) if cl_bid else np.zeros(0, dtype=np.int32)
r_rx = np.concatenate(cl_rx) if cl_rx else np.zeros(0, dtype=np.float32)
r_ry = np.concatenate(cl_ry) if cl_ry else np.zeros(0, dtype=np.float32)
r_rz = np.concatenate(cl_rz) if cl_rz else np.zeros(0, dtype=np.float32)
r_fallback = (
np.concatenate(cl_fallback) if cl_fallback
else np.zeros(0, dtype=np.uint8)
)
sensor_cells = np.concatenate(s_cells) if s_cells else np.zeros(0, dtype=np.uint32)
sensor_obj_id = np.concatenate(s_ids) if s_ids else np.zeros(0, dtype=np.int32)
r_fr_cells = np.concatenate(fr_cells) if fr_cells else np.zeros(0, dtype=np.uint32)
r_fr_ids = np.concatenate(fr_ids) if fr_ids else np.zeros(0, dtype=np.int32)
return (
r_idx, r_dir, r_q, r_bid,
r_rx, r_ry, r_rz, r_fallback,
sensor_cells, sensor_obj_id,
r_fr_cells, r_fr_ids,
)
# -- GPU sync ------------------------------------------------------------
def sync_to_gpu(self, field, *, rebuild_flags: bool = True):
"""Upload compact lists, action buffer, and packed ``obs`` GPU buffer.
Args:
rebuild_flags: Rebuild ``field.flag`` from the clean channel base and
upload it before constructing compact lists. Pass ``False`` when
the caller has already prepared and uploaded the final flag field
for this geometry, such as during initialization.
"""
self._telemetry_field = field
if rebuild_flags:
field.flag = self.build_flags(field.build_channel_flags())
field.upload_flags()
(
cl_fluid_idx, cl_dir, cl_q, cl_body_id,
cl_rx, cl_ry, cl_rz, cl_fallback_class,
sensor_cells, sensor_obj_id,
fr_cells, fr_obj_id,
) = self.build_compact_lists(domain_flags=field.flag)
field.curved.assign_host(
cl_fluid_idx, cl_dir, cl_q, cl_body_id,
cl_rx, cl_ry, cl_rz, cl_fallback_class,
)
field.sensors.assign_host(sensor_cells, sensor_obj_id)
field.force_regions.assign_host(fr_cells, fr_obj_id)
field.upload_compact_lists()
field.update_params(n_objects=self.count)
self._refresh_action_from_objects()
self._allocate_packed_telemetry()
assert self.obs_pinned is not None
self.obs_pinned.fill(0)
cuda.memcpy_htod(self.obs_gpu, self.obs_pinned)
def _allocate_packed_telemetry(self) -> None:
"""Resize ``action_gpu`` / ``obs_gpu`` / ``obs_pinned`` when layout changes."""
dim = self.cfg.dim if self.cfg else 2
lay = obs_layout(dim, self.count)
self._apply_obs_layout(lay)
# Buffer re-allocation implies a fresh start -- reset step counter.
self._obs_accum_steps = 0
action_nbytes = int(self.action.nbytes)
if self.action_gpu is None or self._action_nbytes != action_nbytes:
if self.action_gpu is not None:
self.action_gpu.free()
self.action_gpu = None
self.action_gpu = cuda.mem_alloc(action_nbytes)
self._action_nbytes = action_nbytes
# Initialise with host action (zeros until first run() upload).
cuda.memcpy_htod(self.action_gpu, self.action)
if self.obs_gpu is None or self._obs_alloc_nbytes != self.obs_nbytes:
if self.obs_gpu is not None:
self.obs_gpu.free()
self.obs_gpu = None
self.obs_gpu = cuda.mem_alloc(self.obs_nbytes)
self._obs_alloc_nbytes = self.obs_nbytes
self.obs_pinned = cuda.pagelocked_empty(lay.total_floats, np.float32)
self.obs_pinned.fill(0)
n_slots = max(self.count, 1)
self.obs_force_view = self.obs_pinned[
lay.force0_floats: lay.force0_floats + lay.force_floats
].reshape(
n_slots, dim)
self.obs_torque_view = self.obs_pinned[
lay.torque0_floats: lay.torque0_floats + lay.torque_floats
].reshape(n_slots, lay.torque_components)
self.obs_sensor_view = self.obs_pinned[
lay.sensor0_floats: lay.sensor0_floats + lay.slot_stride_floats
].reshape(n_slots, dim)
def _apply_obs_layout(self, lay: ObsLayout) -> None:
self.slot_stride_floats = lay.slot_stride_floats
self.torque_stride_floats = lay.torque_floats
self.torque_components = lay.torque_components
self.torque0_floats = lay.torque0_floats
self.sensor0_floats = lay.sensor0_floats
self.obs_total_floats = lay.total_floats
self.obs_nbytes = lay.total_floats * 4
def ensure_packed_buffers(self) -> None:
"""Allocate ``action_gpu`` and packed ``obs`` when there are zero objects.
Call after ``generate_config(..., n_objects=0)`` so ``config_obs.h`` matches
:func:`obs_layout(dim, 0)`.
"""
if self.cfg is None:
return
self._allocate_packed_telemetry()
assert self.obs_pinned is not None
self.obs_pinned.fill(0)
cuda.memcpy_htod(self.obs_gpu, self.obs_pinned)
def zero_force_segment_async(self, stream: cuda.Stream):
"""Zero body telemetry (force + torque) of ``obs_gpu``.
Deprecated: prefer :meth:`zero_obs_async` which zeros all three
obs segments (force + torque + sensor) in a single memset.
"""
n_floats = self.sensor0_floats
cuda.memset_d32_async(self.obs_gpu, 0, n_floats, stream)
def zero_sensor_segment_async(self, stream: cuda.Stream):
"""Zero the sensor segment (second stride-sized block of floats).
Deprecated: prefer :meth:`zero_obs_async` which zeros all three
obs segments (force + torque + sensor) in a single memset.
"""
offset_bytes = self.sensor0_floats * 4
ptr = int(self.obs_gpu) + offset_bytes
cuda.memset_d32_async(ptr, 0, self.slot_stride_floats, stream)
def zero_obs_async(self, stream: cuda.Stream):
"""Zero ALL obs segments (force + torque + sensor) on GPU.
One ``memset`` covers the entire ``obs_gpu`` buffer.
Resets the step accumulator so that ``read_*(normalize=True)``
returns raw values (dividing by zero is avoided -- see read methods).
"""
n_floats = self.obs_total_floats
cuda.memset_d32_async(self.obs_gpu, 0, n_floats, stream)
self._obs_accum_steps = 0
def increment_obs_steps(self, n: int):
"""Accumulate *n* LBM steps for time-normalization."""
self._obs_accum_steps += n
def download_obs_full_async(self, stream: cuda.Stream):
"""Enqueue full DTOH copy ``obs_gpu`` -> ``obs_pinned``."""
assert self.obs_pinned is not None
cuda.memcpy_dtoh_async(self.obs_pinned, self.obs_gpu, stream)
def _upload_action_async(self, stream: cuda.Stream) -> None:
"""Async H2D of host action array to action_gpu."""
if self.action_gpu is None or self.action.size == 0:
return
cuda.memcpy_htod_async(self.action_gpu, self.action, stream)
@property
def obs_n_slots(self) -> int:
"""At-least-one slot count ``max(count, 1)`` matching ``config_obs.h``."""
return max(self.count, 1)
@property
def obs_slot_stride_floats(self) -> int:
"""Floats per telemetry segment (``obs_n_slots * DIM``)."""
return self.slot_stride_floats
@property
def obs_sensor_base_floats(self) -> int:
"""Float index where the sensor segment begins."""
return self.sensor0_floats
@property
def obs_torque_base_floats(self) -> int:
"""Float index where the torque segment begins."""
return self.torque0_floats
def read_force(self, body_id: int, *, normalize: bool = True) -> np.ndarray:
"""Return the DIM-vector force on body ``body_id`` from ``obs_pinned``.
When *normalize* is ``True`` (default), divides by the number of
accumulated LBM steps since the last zero so the result is the
**average force per step**. When ``False``, returns the raw
GPU-accumulated sum (no time-normalisation).
Caller must have synchronised the CUDA stream before reading.
"""
self._validate_body_id(body_id)
assert self.cfg is not None
assert self.obs_pinned is not None
d = self.cfg.dim
i0 = body_id * d
values = np.array(self.obs_pinned[i0:i0 + d], dtype=np.float32)
if normalize and self._obs_accum_steps > 0:
values /= np.float32(self._obs_accum_steps)
return values
def read_torque(self, body_id: int, *, normalize: bool = True) -> np.ndarray:
"""Return torque vector for ``body_id`` from ``obs_pinned``.
See :meth:`read_force` for the *normalize* semantics.
"""
self._validate_body_id(body_id)
assert self.obs_pinned is not None
i0 = self.torque0_floats + body_id * self.torque_components
values = np.array(
self.obs_pinned[i0:i0 + self.torque_components], dtype=np.float32)
if normalize and self._obs_accum_steps > 0:
values /= np.float32(self._obs_accum_steps)
return values
def read_sensor(self, body_id: int, *, normalize: bool = True) -> np.ndarray:
"""Return sensor accumulation for ``body_id``.
**Area-normalisation is always applied internally** -- the raw GPU
sum is divided by the number of sensor cells in the body footprint.
When *normalize* is ``True`` (default), the result is further divided
by the number of accumulated LBM steps, giving a **per-step
area-averaged velocity**. Set ``normalize=False`` to obtain the
area-averaged value without time-normalisation.
Caller must have synchronised the CUDA stream before reading.
"""
self._validate_body_id(body_id)
assert self.obs_pinned is not None
assert self.cfg is not None
d = self.cfg.dim
i0 = self.sensor0_floats + body_id * d
values = np.array(self.obs_pinned[i0:i0 + d], dtype=np.float32)
# Always area-normalise
count = int(self.sensor_cell_counts[body_id]) if body_id < self.sensor_cell_counts.size else 0
if count > 0:
values /= np.float32(count)
# Optionally time-normalise
if normalize and self._obs_accum_steps > 0:
values /= np.float32(self._obs_accum_steps)
return values
def read_body(self, body_id: int, *, normalize: bool = True) -> BodyTelemetry:
"""Return unified telemetry for one body from the pinned obs buffer.
See :meth:`read_force`, :meth:`read_torque`, and :meth:`read_sensor`
for the *normalize* semantics applied to each field.
The caller must ensure ``run(sync_obs=True)`` or an explicit
``download_obs_full_async + synchronize`` has completed.
"""
force = self.read_force(body_id, normalize=normalize)
torque = self.read_torque(body_id, normalize=normalize)
sensor = self.read_sensor(body_id, normalize=normalize)
return BodyTelemetry(force=force, torque=torque, sensor=sensor)
def _obs_array(self) -> np.ndarray:
"""Return the full pinned obs buffer as a flat float32 array.
Shape: ``(total_floats,)`` with layout ``[force|torque|sensor]``.
Efficient for DRL batch reads.
"""
assert self.obs_pinned is not None
return self.obs_pinned.copy()
def set_body_state(self, body_id: int, omega: float = 0.0) -> None:
"""Set runtime body state (host action array only, no H2D).
The GPU action buffer is updated at the next ``run()`` call.
"""
self._validate_body_id(body_id)
dim = self.cfg.dim if self.cfg else 2
slot = 3 * dim
base = body_id * slot
self.action[base + slot - 1] = np.float32(omega)
def set_force_state(self, body_id: int, fx: float = 0.0, fy: float = 0.0) -> None:
"""Set force density on a force_region object (host action only, no H2D).
The GPU action buffer is updated at the next ``run()`` call.
"""
self._validate_body_id(body_id)
dim = self.cfg.dim if self.cfg else 2
slot = 3 * dim
base = body_id * slot
self.action[base + 0] = np.float32(fx)
self.action[base + 1] = np.float32(fy)
def _validate_body_id(self, body_id: int) -> None:
if body_id < 0 or body_id >= self.count:
raise IndexError(
f"body_id {body_id} out of range for {self.count} objects")
def _refresh_action_from_objects(self) -> None:
"""Populate action slots from object state using the runtime contract.
Slot layout per object (DIM=2 in this example, slots derived from 3*DIM):
[0] = vx (= fx for force_region objects; 0 for bodies/sensors)
[1] = vy (= fy for force_region objects; 0 for bodies/sensors)
[5] = omega (= body rotation for circle objects; 0 for sensors/force_region)
Slot 0/1 are consumed by ForceRegionKernel for force_region objects.
Slot -1 is consumed by CurvedBoundaryKernel for body rotation (action_omega).
Sensors do not consume action slots.
"""
if self.count == 0:
return
dim = self.cfg.dim if self.cfg else 2
slot = 3 * dim
self.action.fill(0)
for obj in self._registry.objects:
base = obj.obj_id * slot
if base + slot > self.action.size:
continue
self.action[base + 0] = np.float32(getattr(obj.state, "vx", 0.0))
self.action[base + 1] = np.float32(getattr(obj.state, "vy", 0.0))
self.action[base + slot - 1] = np.float32(
getattr(obj.state, "omega", 0.0))
def fallback_link_count(self) -> int:
"""Return number of curved links marked for fallback bounce-back."""
if self._telemetry_field is None:
return 0
curved = self._telemetry_field.curved
if curved.count == 0:
return 0
return int(np.count_nonzero(curved.fallback_class[:curved.count] != 0))
def low_q_link_count(self, threshold: float = 0.5) -> int:
"""Return count of links where q is below ``threshold``."""
if self._telemetry_field is None:
return 0
curved = self._telemetry_field.curved
if curved.count == 0:
return 0
return int(np.count_nonzero(
curved.q[:curved.count] < np.float32(threshold)))
# -- Placeholders for future use -----------------------------------------
def update_states(self, dt: float):
"""Integrate object motion (placeholder)."""
pass
def detect_collisions(self):
"""Multi-body collision detection (placeholder)."""
pass
def exchange_forces(self, obs: np.ndarray):
"""Distribute fluid forces to objects (placeholder)."""
pass
+164
View File
@@ -0,0 +1,164 @@
# CelerisLab/body/objects.py
"""
SimObject -- container wrapping geometry, state, and control.
Design:
SimObject is a thin container that holds a Geometry instance (shape),
an ObjectState (position/velocity), and an ObjectControl (control input).
Concrete geometry logic lives in ``body/geometry/*.py``.
The ``get_curved_list()`` / ``get_sensor_list()`` methods exist for
backward compatibility with ``ObjectManager.build_compact_lists()``.
They delegate to the Geometry's build methods and the SoA packer.
"""
from __future__ import annotations
from dataclasses import dataclass
from typing import Optional, Tuple
import numpy as np
from .geometry.base import Geometry
# ---------------------------------------------------------------------------
# Constants
# ---------------------------------------------------------------------------
FALLBACK_CLASS_BOUZIDI = np.uint8(0)
FALLBACK_CLASS_HALFWAY_BOUNCEBACK = np.uint8(1)
# ---------------------------------------------------------------------------
# State / Control containers
# ---------------------------------------------------------------------------
@dataclass
class ObjectState:
"""Position, velocity, orientation (z reserved for 3D layouts)."""
x: float = 0.0
y: float = 0.0
z: float = 0.0
theta: float = 0.0
vx: float = 0.0
vy: float = 0.0
omega: float = 0.0
@dataclass
class ObjectControl:
"""Control input (force / velocity / displacement target)."""
ax: float = 0.0
ay: float = 0.0
alpha: float = 0.0
mode: int = 0 # 0=force, 1=velocity, 2=displacement
# ---------------------------------------------------------------------------
# SimObject container
# ---------------------------------------------------------------------------
class SimObject:
"""Container for a simulation object: geometry, state, control.
The Geometry instance handles shape-specific operations (cut-link
enumeration, flag mask generation). SimObject wraps it with runtime
state and an id for bookkeeping.
The *is_sensor* flag selects the flag mask variant for sensors
(``FLUID|SENSOR_FLAG``) vs. obstacle bodies (``SOLID|OBSTACLE|BC_CURVED``).
"""
obj_type: str = "generic"
def __init__(
self,
obj_id: int,
geometry: Optional[Geometry] = None,
center: Optional[Tuple[float, ...]] = None,
radius: float = 0.0,
is_sensor: bool = False,
is_force_region: bool = False,
) -> None:
self.obj_id = obj_id
self.center = center if center is not None else (0.0, 0.0)
self.radius = radius
self._geometry = geometry
self._is_sensor = is_sensor
self._is_force_region = is_force_region
c = self.center
z0 = float(c[2]) if len(c) > 2 else 0.0
self.state = ObjectState(
x=float(c[0]), y=float(c[1]), z=z0,
)
self.control = ObjectControl()
@property
def geometry(self) -> Geometry:
if self._geometry is None:
raise RuntimeError(
f"SimObject id={self.obj_id} has no geometry assigned.")
return self._geometry
@geometry.setter
def geometry(self, g: Geometry) -> None:
self._geometry = g
@property
def is_sensor(self) -> bool:
return self._is_sensor
@property
def is_force_region(self) -> bool:
return self._is_force_region
# ------------------------------------------------------------------
# Methods consumed by ObjectManager.build_compact_lists() / build_flags()
# ------------------------------------------------------------------
def get_flag_mask(self, nx: int, ny: int, nz: int = 1) -> np.ndarray:
"""Return (nx*ny,) uint16 array with flag bits set for this object.
Sensors produce ``FLUID|SENSOR_FLAG``; bodies produce
``SOLID|OBSTACLE|BC_CURVED``; force-region objects produce
``FLUID|FRC_REGION``.
"""
if self._is_force_region:
return self.geometry.build_force_region_flag_mask(nx, ny)
if self._is_sensor:
return self.geometry.build_sensor_flag_mask(nx, ny)
return self.geometry.build_flag_mask(nx, ny)
def get_curved_list(
self, nx: int, ny: int, nq: int,
nz: int = 1, ex=None, ey=None, ez=None,
domain_flags=None,
):
"""Return 8-column SoA arrays for curved-boundary kernel.
Delegates to the geometry object for cut-link enumeration and
to ``pack_cut_links_to_soa`` for SoA packing.
Returns:
8-tuple matching CurvedLinkSoA.assign_host().
"""
from .coupling.soa_packer import pack_cut_links_to_soa
links = self.geometry.build_cut_links(nx, ny, domain_flags=domain_flags)
for cl in links:
cl.body_id = self.obj_id
return pack_cut_links_to_soa(links)
def get_sensor_list(self, nx: int, ny: int, nz: int = 1):
"""Return compact sensor list (cells, obj_ids).
Returns:
cells (uint32), obj_ids (int32).
"""
if self._is_force_region:
from .coupling.soa_packer import pack_force_region_to_soa as packer
else:
from .coupling.soa_packer import pack_sensor_to_soa as packer
cells = self.geometry.build_sensor_cells(nx, ny)
for sc in cells:
sc.body_id = self.obj_id
return packer(cells)
@@ -0,0 +1,4 @@
# CelerisLab/body/preprocess/__init__.py
"""
Grid preprocessing: flag overlay, cut-link packing, sensor mapping.
"""
@@ -0,0 +1,34 @@
# CelerisLab/body/preprocess/flag_overlay.py
"""
Flag overlay: merge per-object flag masks onto a clean domain base.
"""
from __future__ import annotations
from typing import List
import numpy as np
def merge_flag_masks(
base: np.ndarray,
masks: List[np.ndarray],
) -> np.ndarray:
"""Merge object flag masks onto a clean domain base.
For each mask in *masks*, non-zero entries overwrite the corresponding
positions in *base*. Callers should pass a fresh channel-layout flag
array to prevent stale obstacle bits from surviving after geometry edits.
Args:
base: uint16 domain flag array (e.g. from build_channel_flags()).
masks: List of uint16 mask arrays from each object's get_flag_mask().
Returns:
New uint16 array with object overlays applied.
"""
merged = np.array(base, copy=True)
for mask in masks:
nonzero = mask != 0
merged[nonzero] = mask[nonzero]
return merged
+49
View File
@@ -0,0 +1,49 @@
# CelerisLab/body/registry.py
"""
BodyRegistry -- pure add/remove/query for simulation objects.
No GPU or LBM knowledge.
"""
from __future__ import annotations
from typing import Dict, List
from .objects import SimObject
class BodyRegistry:
"""Registry for SimObject instances. No GPU or LBM knowledge."""
def __init__(self) -> None:
self._objects: Dict[int, SimObject] = {}
self._next_id = 0
def add(self, obj: SimObject) -> int:
"""Register a new object and return its assigned id."""
obj.obj_id = self._next_id
self._objects[self._next_id] = obj
self._next_id += 1
return obj.obj_id
def remove(self, obj_id: int) -> None:
"""Unregister an object by id."""
del self._objects[obj_id]
def get(self, obj_id: int) -> SimObject:
"""Return the registered object by id."""
return self._objects[obj_id]
def clear(self) -> None:
"""Remove all objects and reset id counter."""
self._objects.clear()
self._next_id = 0
@property
def objects(self) -> List[SimObject]:
"""List of all registered objects in insertion order."""
return list(self._objects.values())
@property
def count(self) -> int:
"""Number of registered objects."""
return len(self._objects)
+52
View File
@@ -0,0 +1,52 @@
# CelerisLab/body/sync_plan.py
"""
BodySyncPlan -- topology change descriptor for runtime body sync. (D2Q9 only)
Design:
A ``BodySyncPlan`` is constructed by ``ObjectManager.build_sync_plan()``
and consumed by ``Simulation.sync_bodies()``. It describes the full
topology transition from the current formal object set to the next one,
including flags, compact lists, and cell-level change masks.
The plan does NOT hold DDF data -- that must be read from ``LBMField``
at sync time. Keeping the plan free of large array copies makes it
cheap to construct and discard.
Change masks use D2Q9 neighbour offsets. D3Q19 support would require
extending ``released_fluid_mask`` neighbour enumeration.
"""
from __future__ import annotations
from dataclasses import dataclass, field
from typing import List
import numpy as np
from .objects import SimObject
@dataclass
class BodySyncPlan:
"""Topology transition plan produced by ``ObjectManager.build_sync_plan()``.
Attributes:
next_objects: New formal object list with ``obj_id = 0..n-1``.
next_count: Length of *next_objects*.
next_flags: Merged uint16 flag array for the new topology.
curved_host: 8-tuple of SoA arrays for CurvedLinkSoA.assign_host().
sensor_host: 2-tuple (cells, obj_id) for SensorSoA.assign_host().
force_region_host: 2-tuple (cells, obj_id) for ForceRegionSoA.assign_host().
added_solid_mask: Bool array -- True where ``old_fluid -> new_solid``.
released_fluid_mask: Bool array -- True where ``old_obstacle -> new_fluid``.
new_sensor_counts: Int array of sensor cell counts per object.
"""
next_objects: List[SimObject]
next_count: int
next_flags: np.ndarray
curved_host: tuple
sensor_host: tuple
force_region_host: tuple
added_solid_mask: np.ndarray
released_fluid_mask: np.ndarray
new_sensor_counts: np.ndarray
+8
View File
@@ -0,0 +1,8 @@
# CelerisLab/common/__init__.py
"""
Common utilities and preprocessing functions.
"""
from . import preprocess, pathline, checkpoint, render, streakline
__all__ = ["preprocess", "pathline", "checkpoint", "render", "streakline"]
+9
View File
@@ -0,0 +1,9 @@
# CelerisLab/common/_types.py
"""
Shared type aliases for the ``common`` package.
"""
from typing import Tuple
CylinderSpec = Tuple[Tuple[float, float], float]
"""A cylinder defined by ``((cx, cy), radius)`` in lattice units."""
+200
View File
@@ -0,0 +1,200 @@
# CelerisLab/common/checkpoint.py
"""HDF5 checkpoint save and load for CelerisLab simulations.
Responsibilities:
Serialize GPU distribution functions, cell flags, simulation step count,
and rigid-body states to HDF5; on load, validate lattice geometry and
storage precision before restoring device buffers.
Usage::
Call ``save_checkpoint`` / ``load_checkpoint`` from host-side code when GPU
work is finished; the active ``LBMConfig`` must match the checkpoint on
``lattice_model``, ``nx``, ``ny``, ``nz``, and ``store_precision``.
"""
import json
import os
import time
import numpy as np
import pycuda.driver as cuda
# File format version — bump on incompatible layout changes.
CKPT_VERSION = 1
_SUPPORTED_STORE_PRECISIONS = ("FP32", "FP16S")
def _require_supported_precision(store_precision: str, source: str) -> None:
supported = ", ".join(_SUPPORTED_STORE_PRECISIONS)
if store_precision not in _SUPPORTED_STORE_PRECISIONS:
raise RuntimeError(
f"Unsupported store_precision '{store_precision}' in {source}. "
f"Supported checkpoint/runtime precisions: {supported}."
)
def save_checkpoint(field, stepper, lbm_cfg, bodies, path=None):
"""Save full simulation state to an HDF5 file.
Args:
field: LBMField instance (GPU arrays).
stepper: LBMStepper instance (step count).
lbm_cfg: LBMConfig instance.
bodies: ObjectManager instance.
path: Output file path. Auto-generated if None.
Returns:
Path to the written checkpoint file.
"""
import h5py
if path is None:
os.makedirs("output", exist_ok=True)
path = f"output/checkpoint_{stepper.step_count:08d}.h5"
_require_supported_precision(lbm_cfg.store_precision, "save_checkpoint")
# Download GPU → host
dtype = np.float16 if field.store_bytes == 2 else np.float32
ddf_buf = np.empty(field.n * field.nq, dtype=dtype)
tmp_buf = np.empty(field.n * field.nq, dtype=dtype)
cuda.memcpy_dtoh(ddf_buf, field.ddf_gpu)
cuda.memcpy_dtoh(tmp_buf, field.temp_gpu)
flag_buf = np.empty(field.n, dtype=np.uint16)
cuda.memcpy_dtoh(flag_buf, field.flag_gpu)
with h5py.File(path, "w") as hf:
# Version and metadata
hf.attrs["ckpt_version"] = CKPT_VERSION
hf.attrs["celerislab_version"] = __import__(
"CelerisLab").__version__
hf.attrs["timestamp"] = time.strftime("%Y-%m-%dT%H:%M:%S")
hf.attrs["step_count"] = stepper.step_count
# Object count metadata for runtime sync compatibility
hf.attrs["n_objects"] = bodies.count
# Config as JSON string (human-readable in HDF5 viewers)
cfg = lbm_cfg
config_dict = {
"lattice_model": cfg.lattice_model,
"nx": cfg.nx, "ny": cfg.ny, "nz": cfg.nz,
"data_type": cfg.data_type,
"viscosity": cfg.viscosity, "velocity": cfg.velocity,
"rho": cfg.rho,
"collision": cfg.collision, "streaming": cfg.streaming,
"store_precision": cfg.store_precision,
"ddf_shifting": cfg.ddf_shifting,
"les_enabled": cfg.les_enabled, "les_cs": cfg.les_cs,
"les_closed_form": cfg.les_closed_form,
"trt_magic_param": cfg.trt_magic_param,
"inlet_profile": cfg.inlet_profile,
"inlet_scheme": cfg.inlet_scheme,
"outlet_mode": cfg.outlet_mode,
"omega_min": cfg.omega_min, "omega_max": cfg.omega_max,
}
hf.attrs["config_json"] = json.dumps(config_dict)
# GPU arrays — gzip compression for portable, compact files
hf.create_dataset("ddf", data=ddf_buf, compression="gzip",
compression_opts=4)
hf.create_dataset("temp", data=tmp_buf, compression="gzip",
compression_opts=4)
hf.create_dataset("flag", data=flag_buf, compression="gzip",
compression_opts=4)
# Object states
obj_states = []
for obj in bodies.objects:
s = obj.state
obj_states.append({
"obj_id": obj.obj_id,
"type": obj.obj_type,
"x": s.x, "y": s.y, "z": s.z, "theta": s.theta,
"vx": s.vx, "vy": s.vy, "omega": s.omega,
"radius": obj.radius,
})
hf.attrs["objects_json"] = json.dumps(obj_states)
return path
def load_checkpoint(path, field, stepper, lbm_cfg, bodies):
"""Restore simulation state from an HDF5 checkpoint.
The current config's lattice_model, nx, ny, nz, and
store_precision must match the checkpoint. Other parameters
(collision, LES, …) may differ for parameter-study restarts.
Args:
path: HDF5 checkpoint file path.
field: LBMField instance.
stepper: LBMStepper instance.
lbm_cfg: LBMConfig instance.
bodies: ObjectManager instance.
"""
import h5py
_require_supported_precision(lbm_cfg.store_precision, "load_checkpoint")
with h5py.File(path, "r") as hf:
# Version check
ver = hf.attrs.get("ckpt_version", 0)
if ver != CKPT_VERSION:
raise ValueError(
f"Checkpoint version mismatch: file={ver}, "
f"expected={CKPT_VERSION}. "
f"Created by CelerisLab {hf.attrs.get('celerislab_version', '?')}")
# Config compatibility check
saved_cfg = json.loads(hf.attrs["config_json"])
for key in ("lattice_model", "nx", "ny", "nz", "store_precision",
"streaming", "ddf_shifting"):
saved_val = saved_cfg.get(key)
curr_val = getattr(lbm_cfg, key)
if saved_val != curr_val:
raise ValueError(
f"Config mismatch on '{key}': "
f"checkpoint={saved_val}, current={curr_val}")
_require_supported_precision(
str(saved_cfg.get("store_precision", "unknown")),
"checkpoint file",
)
# Object count validation: checkpoint's n_objects must match
# the compiled N_OBJS (which equals current bodies.count).
ckpt_n_objects = int(hf.attrs.get("n_objects", 0))
if ckpt_n_objects != bodies.count:
raise ValueError(
f"Object count mismatch: checkpoint has {ckpt_n_objects} "
f"objects, but the simulation is compiled with "
f"N_OBJS={bodies.count}. Use sync_bodies() to adjust "
"the object count before loading, or rebuild the "
"simulation with the correct number of objects.")
# Restore GPU arrays
ddf_buf = hf["ddf"][:]
tmp_buf = hf["temp"][:]
flag_buf = hf["flag"][:]
cuda.memcpy_htod(field.ddf_gpu, ddf_buf)
cuda.memcpy_htod(field.temp_gpu, tmp_buf)
cuda.memcpy_htod(field.flag_gpu, flag_buf)
field.flag = flag_buf.copy()
# Restore step count
stepper._step_count = int(hf.attrs["step_count"])
# Restore object states
obj_data = json.loads(hf.attrs.get("objects_json", "[]"))
for od in obj_data:
oid = od["obj_id"]
try:
obj = bodies.get(oid)
obj.state.x = od["x"]
obj.state.y = od["y"]
obj.state.z = float(od.get("z", 0.0))
obj.state.theta = od["theta"]
obj.state.vx = od["vx"]
obj.state.vy = od["vy"]
obj.state.omega = od["omega"]
except KeyError:
pass # object not in current sim — skip
+207
View File
@@ -0,0 +1,207 @@
# CelerisLab/common/pathline.py
"""
Particle pathline history accumulation and rendering (debug tool).
This is **not** a streakline — it accumulates each particle's full trajectory
over time. For streakline visualization use ``streakline.Streakline``.
"""
from __future__ import annotations
from concurrent.futures import ThreadPoolExecutor
from dataclasses import dataclass, field
from typing import List, Optional, Sequence, Tuple
import numpy as np
from .streakline._render import gaussian_blur2d
from ._types import CylinderSpec
def configure_compute_threads(num_threads: int = 0) -> int:
"""Set BLAS/OpenMP thread env vars for host-side numpy work."""
import os
if num_threads <= 0:
num_threads = min(32, os.cpu_count() or 4)
for var in (
"OMP_NUM_THREADS",
"OPENBLAS_NUM_THREADS",
"MKL_NUM_THREADS",
"NUMEXPR_NUM_THREADS",
"VECLIB_MAXIMUM_THREADS",
):
os.environ[var] = str(int(num_threads))
return int(num_threads)
@dataclass
class ParticleTrailSet:
"""Growing polylines per particle (pathline history, not streakline)."""
trails: List[np.ndarray] = field(default_factory=list)
active: List[bool] = field(default_factory=list)
def inject(self, points: np.ndarray) -> None:
pts = np.asarray(points, dtype=np.float64)
if pts.ndim != 2 or pts.shape[1] != 2:
raise ValueError("points must be [N,2].")
for p in pts:
self.trails.append(np.asarray([[p[0], p[1]]], dtype=np.float64))
self.active.append(True)
def keep_indices(self, survived_mask: np.ndarray) -> None:
mask = np.asarray(survived_mask, dtype=bool).ravel()
j = 0
for i, is_active in enumerate(self.active):
if not is_active:
continue
if j >= mask.size:
break
if not bool(mask[j]):
self.active[i] = False
j += 1
def append_positions(self, particles: np.ndarray) -> None:
pts = np.asarray(particles, dtype=np.float64)
j = 0
for i, is_active in enumerate(self.active):
if not is_active:
continue
if j >= pts.shape[0]:
break
self.trails[i] = np.vstack([self.trails[i], pts[j]])
j += 1
def _rasterize_segment(
intensity: np.ndarray,
x0: float,
y0: float,
x1: float,
y1: float,
weight: float,
) -> None:
"""Stamp one segment into a scalar intensity map."""
ny, nx = intensity.shape
n = int(max(abs(x1 - x0), abs(y1 - y0), 1.0)) + 1
xs = np.linspace(x0, x1, n)
ys = np.linspace(y0, y1, n)
xi = np.clip(np.rint(xs).astype(np.int64), 0, nx - 1)
yi = np.clip(np.rint(ys).astype(np.int64), 0, ny - 1)
w = float(max(0.0, min(1.0, weight)))
np.add.at(intensity, (yi, xi), w)
def _draw_trail(
intensity: np.ndarray,
trail: np.ndarray,
*,
fade_along_trail: bool,
) -> None:
if trail.shape[0] < 2:
return
nseg = trail.shape[0] - 1
for i in range(nseg):
if fade_along_trail:
t = float(i + 1) / float(nseg)
weight = 0.15 + 0.85 * t
else:
weight = 1.0
_rasterize_segment(
intensity,
float(trail[i, 0]),
float(trail[i, 1]),
float(trail[i + 1, 0]),
float(trail[i + 1, 1]),
weight,
)
def render_trails(
trail_set: ParticleTrailSet,
*,
nx: int,
ny: int,
out_path: str,
cylinders: Optional[Sequence[CylinderSpec]] = None,
blur_sigma: float = 0.0,
fade_along_trail: bool = True,
num_threads: int = 0,
background_color: Tuple[float, float, float] = (1.0, 1.0, 1.0),
streak_color: Tuple[float, float, float] = (1.0, 0.0, 0.0),
) -> dict:
"""Render accumulated path trails (pathline collage — debug only).
This is NOT a streakline renderer. See ``streakline.Streakline``.
"""
n_threads = configure_compute_threads(num_threads)
intensity = np.zeros((ny, nx), dtype=np.float64)
trails = trail_set.trails
if not trails:
density_max = 0.0
else:
chunk = max(1, (len(trails) + n_threads - 1) // n_threads)
def _worker(batch: List[np.ndarray]) -> np.ndarray:
local = np.zeros((ny, nx), dtype=np.float64)
for tr in batch:
_draw_trail(local, tr, fade_along_trail=fade_along_trail)
return local
batches = [trails[i : i + chunk] for i in range(0, len(trails), chunk)]
if len(batches) == 1:
intensity = _worker(batches[0])
else:
with ThreadPoolExecutor(max_workers=n_threads) as pool:
parts = list(pool.map(_worker, batches))
for part in parts:
intensity = np.maximum(intensity, part)
if np.any(intensity > 0):
vmax = float(np.percentile(intensity[intensity > 0], 99.0))
intensity = np.clip(intensity / max(vmax, 1e-12), 0.0, 1.0)
density_max = float(np.max(intensity))
rgb = np.ones((ny, nx, 3), dtype=np.float64)
rgb[:, :, 0] = background_color[0]
rgb[:, :, 1] = background_color[1] * (1.0 - intensity) + streak_color[1] * intensity
rgb[:, :, 2] = background_color[2] * (1.0 - intensity) + streak_color[2] * intensity
if streak_color[0] < 0.999:
rgb[:, :, 0] = background_color[0] * (1.0 - intensity) + streak_color[0] * intensity
if cylinders:
yy, xx = np.mgrid[0:ny, 0:nx]
for (cx, cy), radius in cylinders:
mask = (xx - float(cx)) ** 2 + (yy - float(cy)) ** 2 <= float(radius) ** 2
rgb[mask] = 0.0
if float(blur_sigma) > 0.0:
for c in range(3):
rgb[:, :, c] = gaussian_blur2d(rgb[:, :, c], sigma=float(blur_sigma))
rgb = np.clip(rgb, 0.0, 1.0)
import os
os.makedirs(os.path.dirname(os.path.abspath(out_path)), exist_ok=True)
try:
import matplotlib
matplotlib.use("Agg")
import matplotlib.pyplot as plt
fig = plt.figure(figsize=(nx / 100.0, ny / 100.0), dpi=100)
ax = fig.add_axes([0.0, 0.0, 1.0, 1.0])
ax.axis("off")
ax.imshow(rgb, origin="lower", interpolation="nearest", aspect="auto")
fig.savefig(out_path, dpi=100, bbox_inches="tight", pad_inches=0)
plt.close(fig)
except ImportError:
from PIL import Image
Image.fromarray((np.clip(rgb, 0.0, 1.0) * 255.0).astype(np.uint8)).save(out_path)
return {
"image_path": out_path,
"trail_count": int(len(trails)),
"density_max": density_max,
"num_threads": int(n_threads),
}
+70
View File
@@ -0,0 +1,70 @@
# CelerisLab/common/preprocess.py
"""Host-side geometric helpers for immersed-boundary preprocessing.
Responsibilities:
Circle-ray intersection along fluid-to-neighbour links and simple
discrete sensor-area counting used when building IBM masks and probes.
"""
import math
import numpy as np
def find_circle_intersection(x, y, x_neb, y_neb, xc, yc, r0):
"""Return (px, py) of the closest intersection along fluid->neighbour ray,
or None if no valid root in [0, 1]."""
dx, dy = x_neb - x, y_neb - y
a = dx ** 2 + dy ** 2
b = 2 * (dx * (x - xc) + dy * (y - yc))
c = (x - xc) ** 2 + (y - yc) ** 2 - r0 ** 2
det = b ** 2 - 4 * a * c
if det < 0:
return None
t1 = (-b - math.sqrt(det)) / (2 * a)
t2 = (-b + math.sqrt(det)) / (2 * a)
# Pick the smallest valid t (closest to fluid node).
for t in (t1, t2):
if 0 <= t <= 1:
return x + t * dx, y + t * dy
return None
def find_sensor_area(radius):
area = 0
for i in range(int(np.floor(-radius)), int(np.ceil(radius))):
for j in range(int(np.floor(-radius)), int(np.ceil(radius))):
if i ** 2 + j ** 2 <= radius ** 2:
area += 1
return area
def build_triangle_release_points(
layout: dict,
*,
nx: int,
ny: int,
diameter_cells: float = 20.0,
upstream_D: float = 4.0,
margin: float = 5.0,
n_seeds: int = 4,
) -> np.ndarray:
"""Upstream release seeds for triangle layout, clamped inside the domain."""
release_x = min(layout["x_apex"], layout["x_rear"]) - upstream_D * diameter_cells
release_x = float(np.clip(release_x, margin, nx - 1 - margin))
y_low = float(np.clip(layout["y_lower"] - layout["radius_lb"], margin, ny - 1 - margin))
y_high = float(np.clip(layout["y_upper"] + layout["radius_lb"], margin, ny - 1 - margin))
ys = np.linspace(y_low, y_high, max(2, int(n_seeds)), dtype=np.float64)
return np.column_stack([np.full(ys.shape[0], release_x, dtype=np.float64), ys])
def cylinders_from_triangle_layout(layout: dict) -> "list[tuple[tuple[float, float], float]]":
"""Build cylinder list from triangle-layout dict used in experiment notebook."""
radius = float(layout["radius_lb"])
return [
((float(layout["x_apex"]), float(layout["y_center"])), radius),
((float(layout["x_rear"]), float(layout["y_lower"])), radius),
((float(layout["x_rear"]), float(layout["y_upper"])), radius),
]
+92
View File
@@ -0,0 +1,92 @@
# CelerisLab/common/render.py
"""
Field rendering utilities (vorticity computation and visualization).
Separated from the streakline module: these are macroscopic field diagnostics,
not particle-tracking operations.
"""
from __future__ import annotations
import os
from typing import Optional, Sequence
import numpy as np
from ._types import CylinderSpec
def compute_vorticity(ux: np.ndarray, uy: np.ndarray) -> np.ndarray:
"""Central-difference vorticity omega = d(uy)/dx - d(ux)/dy on interior."""
ux_arr = np.asarray(ux, dtype=np.float64)
uy_arr = np.asarray(uy, dtype=np.float64)
vort = np.zeros_like(ux_arr, dtype=np.float64)
dudy = 0.5 * (ux_arr[2:, 1:-1] - ux_arr[:-2, 1:-1])
dvdx = 0.5 * (uy_arr[1:-1, 2:] - uy_arr[1:-1, :-2])
vort[1:-1, 1:-1] = dvdx - dudy
return vort
def render_vorticity_field(
vort: np.ndarray,
*,
nx: int,
ny: int,
out_path: str,
cylinders: Optional[Sequence[CylinderSpec]] = None,
vmin: Optional[float] = None,
vmax: Optional[float] = None,
percentile: float = 99.0,
minimal_axes: bool = True,
) -> dict:
"""Render vorticity with white at zero, green negative, purple positive."""
try:
import matplotlib
matplotlib.use("Agg")
import matplotlib.pyplot as plt
from matplotlib.colors import LinearSegmentedColormap, TwoSlopeNorm
except ImportError as exc:
raise RuntimeError("render_vorticity_field requires matplotlib.") from exc
field = np.asarray(vort, dtype=np.float64)
vmax_field = float(np.nanmax(np.abs(field)))
abs_pct = float(np.nanpercentile(np.abs(field), percentile))
abs_max = max(abs_pct, 0.35 * vmax_field, 1e-6)
if vmin is None:
vmin = -abs_max
if vmax is None:
vmax = abs_max
if vmin >= 0.0 or vmax <= 0.0:
raise ValueError(f"vmin/vmax must bracket zero: vmin={vmin}, vmax={vmax}")
cmap = LinearSegmentedColormap.from_list(
"vort_green_white_purple",
["#1a9850", "#f7f7f7", "#762a83"],
N=256,
)
norm = TwoSlopeNorm(vmin=float(vmin), vcenter=0.0, vmax=float(vmax))
rgba = cmap(norm(field))
if cylinders:
yy, xx = np.mgrid[0:ny, 0:nx]
for (cx, cy), radius in cylinders:
mask = (xx - float(cx)) ** 2 + (yy - float(cy)) ** 2 <= float(radius) ** 2
rgba[mask] = (0.0, 0.0, 0.0, 1.0)
os.makedirs(os.path.dirname(os.path.abspath(out_path)), exist_ok=True)
fig = plt.figure(figsize=(nx / 100.0, ny / 100.0), dpi=100)
ax = fig.add_axes([0.0, 0.0, 1.0, 1.0])
ax.imshow(rgba, origin="lower", interpolation="nearest", aspect="auto")
if minimal_axes:
ax.axis("off")
fig.savefig(out_path, dpi=100, bbox_inches="tight", pad_inches=0)
plt.close(fig)
return {
"image_path": out_path,
"vmin": float(vmin),
"vmax": float(vmax),
"vort_min": float(np.nanmin(field)),
"vort_max": float(np.nanmax(field)),
}
@@ -0,0 +1,49 @@
# CelerisLab/common/streakline/__init__.py
"""
Streakline — continuous-release particle-based flow visualization.
A post-processing sub-package under ``common/``. The ``Streakline`` class is a
passive consumer: users call ``observe()`` in their own simulation loop,
controlling body actions, checkpointing, or other modules independently.
Usage::
from CelerisLab.common.streakline import Streakline, ReleaseConfig, IntegratorConfig
streak = Streakline(release_points=..., nx=nx, ny=ny, ...)
streak.observe(ux=macro["ux"], uy=macro["uy"], step=step)
streak.render("output.png")
"""
from ._config import (
ReleaseConfig,
IntegratorConfig,
FlowFrame,
CylinderSpec,
build_release_points,
)
from ._streakline import Streakline
from ._integrate import (
advance_between_frames as advance_particles_between_frames,
bilinear_sample,
inject_particles,
particles_valid_mask,
)
from ._render import render_density, gaussian_blur2d
# configure_compute_threads is imported lazily (in _streakline.py) to avoid
# circular dependency between common.pathline and common.streakline.
# Backward-compat aliases
render_streakline_density = render_density
__all__ = [
"Streakline",
"ReleaseConfig",
"IntegratorConfig",
"FlowFrame",
"CylinderSpec",
"build_release_points",
"advance_particles_between_frames",
"render_streakline_density",
]
@@ -0,0 +1,94 @@
# CelerisLab/common/streakline/_config.py
"""
Configuration dataclasses for streakline particle integration.
"""
from __future__ import annotations
from dataclasses import dataclass
from typing import Optional
import numpy as np
from .._types import CylinderSpec
@dataclass(frozen=True)
class FlowFrame:
"""One sampled velocity frame (internal use only)."""
step: int
ux: np.ndarray
uy: np.ndarray
@dataclass(frozen=True)
class ReleaseConfig:
"""Release strategy configuration for dense streakline seeding.
Args:
mode: ``"point"`` | ``"line"`` | ``"strip"``.
line_span: Total cross-stream span for ``line`` / ``strip`` modes.
line_count: Number of cross-stream release points.
downstream_count: Number of streamwise points (``strip`` mode only).
downstream_spacing: Spacing between downstream copies (lattice units).
inject_per_seed: Particles injected per release point each frame.
"""
mode: str = "strip"
line_span: float = 12.0
line_count: int = 5
downstream_count: int = 4
downstream_spacing: float = 3.0
inject_per_seed: int = 2
@dataclass(frozen=True)
class IntegratorConfig:
"""Particle integration and filtering settings.
Args:
alpha_t: Fraction of frame interval used as substep ceiling.
alpha_x: Fraction of lattice unit per substep (CFL-like).
age_decay_steps: Exponential decay scale for age-weight in rendering.
max_particle_age: Hard cutoff age (None = no cutoff).
diffusion_coeff: Random-walk diffusion for visual thickening (0 = off).
random_seed: RNG seed for diffusion.
"""
alpha_t: float = 0.2
alpha_x: float = 0.4
age_decay_steps: float = 20000.0
max_particle_age: Optional[float] = None
diffusion_coeff: float = 0.0
random_seed: int = 1234
def build_release_points(
base_points: np.ndarray,
release_cfg: ReleaseConfig,
) -> np.ndarray:
"""Expand *base_points* to a dense release grid per *release_cfg*."""
pts = np.asarray(base_points, dtype=np.float64)
if pts.ndim != 2 or pts.shape[1] != 2:
raise ValueError("base_points must be [N,2].")
mode = str(release_cfg.mode).lower()
if mode not in ("point", "line", "strip"):
raise ValueError("release mode must be point|line|strip.")
line_count = max(1, int(release_cfg.line_count))
ds_count = max(1, int(release_cfg.downstream_count))
line_offsets = np.linspace(
-0.5 * float(release_cfg.line_span),
0.5 * float(release_cfg.line_span),
line_count,
)
ds_offsets = np.arange(ds_count, dtype=np.float64) * float(
release_cfg.downstream_spacing
)
out: list[list[float]] = []
for x0, y0 in pts:
line_iter = [0.0] if mode == "point" else line_offsets
ds_iter = [0.0] if mode in ("point", "line") else ds_offsets
for dy in line_iter:
for dx in ds_iter:
out.append([float(x0 + dx), float(y0 + dy)])
return np.asarray(out, dtype=np.float64)
@@ -0,0 +1,180 @@
# CelerisLab/common/streakline/_integrate.py
"""
Particle integration: bilinear interpolation, RK4 substep, validity filtering.
"""
from __future__ import annotations
import math
from typing import Optional, Sequence
import numpy as np
from ._config import CylinderSpec, FlowFrame, IntegratorConfig
def bilinear_sample(field: np.ndarray, x: np.ndarray, y: np.ndarray) -> np.ndarray:
"""Bilinear interpolation at floating-point positions ``(x, y)``.
Returns ``NaN`` for positions outside the domain.
"""
ny, nx = field.shape
x0 = np.floor(x).astype(np.int64)
y0 = np.floor(y).astype(np.int64)
x1 = x0 + 1
y1 = y0 + 1
inside = (x0 >= 0) & (x1 < nx) & (y0 >= 0) & (y1 < ny)
out = np.full_like(x, np.nan, dtype=np.float64)
if not np.any(inside):
return out
xi = x[inside] - x0[inside]
yi = y[inside] - y0[inside]
f00 = field[y0[inside], x0[inside]]
f10 = field[y0[inside], x1[inside]]
f01 = field[y1[inside], x0[inside]]
f11 = field[y1[inside], x1[inside]]
out[inside] = (
(1.0 - xi) * (1.0 - yi) * f00
+ xi * (1.0 - yi) * f10
+ (1.0 - xi) * yi * f01
+ xi * yi * f11
)
return out
def velocity_at(
pos: np.ndarray, theta: float, f0: FlowFrame, f1: FlowFrame
) -> np.ndarray:
"""Space-time interpolated velocity at positions ``pos`` (N, 2)."""
x = pos[:, 0]
y = pos[:, 1]
vx0 = bilinear_sample(f0.ux, x, y)
vy0 = bilinear_sample(f0.uy, x, y)
vx1 = bilinear_sample(f1.ux, x, y)
vy1 = bilinear_sample(f1.uy, x, y)
vx = (1.0 - theta) * vx0 + theta * vx1
vy = (1.0 - theta) * vy0 + theta * vy1
return np.stack([vx, vy], axis=1)
def particles_valid_mask(
p_new: np.ndarray,
*,
nx: int,
ny: int,
cylinders: Sequence[CylinderSpec],
) -> np.ndarray:
"""Boolean mask: particles within domain bounds and outside solids."""
valid = np.all(np.isfinite(p_new), axis=1)
valid &= (p_new[:, 0] >= 0.0) & (p_new[:, 0] <= nx - 1)
valid &= (p_new[:, 1] >= 0.0) & (p_new[:, 1] <= ny - 1)
for (cx, cy), radius in cylinders:
dx = p_new[:, 0] - float(cx)
dy = p_new[:, 1] - float(cy)
valid &= (dx * dx + dy * dy) > (float(radius) * float(radius))
return valid
def inject_particles(
particles: np.ndarray,
ages: np.ndarray,
release_points: np.ndarray,
*,
inject_per_seed: int,
) -> tuple[np.ndarray, np.ndarray]:
"""Append new particles at *release_points* with age 0."""
new_pts = np.repeat(release_points, max(1, int(inject_per_seed)), axis=0)
if particles.size == 0:
return new_pts.copy(), np.zeros((new_pts.shape[0],), dtype=np.float64)
return (
np.vstack([particles, new_pts]),
np.concatenate([ages, np.zeros((new_pts.shape[0],), dtype=np.float64)]),
)
def advance_between_frames(
particles: np.ndarray,
ages: np.ndarray,
frame0: FlowFrame,
frame1: FlowFrame,
*,
nx: int,
ny: int,
cfg: IntegratorConfig,
cylinders: Sequence[CylinderSpec],
rng: Optional[np.random.Generator] = None,
) -> tuple[np.ndarray, np.ndarray, dict, np.ndarray]:
"""Advance particles from *frame0* to *frame1* with RK4.
Returns:
particles, ages, diagnostics, survived_mask (input-length bool).
"""
if particles.size == 0:
return (
particles,
ages,
{"n_substeps": 0, "max_speed": 0.0},
np.zeros((0,), dtype=bool),
)
dt_save = float(frame1.step - frame0.step)
max_speed = float(
max(
np.nanmax(np.sqrt(frame0.ux * frame0.ux + frame0.uy * frame0.uy)),
np.nanmax(np.sqrt(frame1.ux * frame1.ux + frame1.uy * frame1.uy)),
)
)
umax = max(max_speed, 1e-8)
dt_trace = min(float(cfg.alpha_t) * dt_save, float(cfg.alpha_x) / umax)
n_sub = max(1, int(math.ceil(dt_save / dt_trace)))
dt_sub = dt_save / float(n_sub)
p = np.asarray(particles, dtype=np.float64)
a = np.asarray(ages, dtype=np.float64)
track = np.ones((p.shape[0],), dtype=bool)
local_rng = rng or np.random.default_rng(int(cfg.random_seed))
diffusion = float(cfg.diffusion_coeff)
for sub_idx in range(n_sub):
if p.size == 0:
break
theta = float(sub_idx) / float(n_sub)
k1 = velocity_at(p, theta, frame0, frame1)
k2 = velocity_at(
p + 0.5 * dt_sub * k1, min(1.0, theta + 0.5 / n_sub), frame0, frame1
)
k3 = velocity_at(
p + 0.5 * dt_sub * k2, min(1.0, theta + 0.5 / n_sub), frame0, frame1
)
k4 = velocity_at(
p + dt_sub * k3, min(1.0, theta + 1.0 / n_sub), frame0, frame1
)
p_new = p + (k1 + 2.0 * k2 + 2.0 * k3 + k4) * (dt_sub / 6.0)
if diffusion > 0.0:
sigma = math.sqrt(max(0.0, 2.0 * diffusion * dt_sub))
p_new += local_rng.normal(0.0, sigma, size=p_new.shape)
valid = particles_valid_mask(p_new, nx=nx, ny=ny, cylinders=cylinders)
track[track] = valid
p = p_new[valid]
a = a[valid] + dt_sub
if cfg.max_particle_age is not None:
age_keep = a <= float(cfg.max_particle_age)
track[track] = age_keep
p = p[age_keep]
a = a[age_keep]
survived_mask = track
return (
p,
a,
{
"dt_trace": float(dt_sub),
"n_substeps": int(n_sub),
"max_speed": float(max_speed),
},
survived_mask,
)
+148
View File
@@ -0,0 +1,148 @@
# CelerisLab/common/streakline/_render.py
"""
Render streakline particle clouds to density images.
"""
from __future__ import annotations
import math
import os
from typing import Optional, Sequence, Tuple
import numpy as np
from ._config import CylinderSpec
def gaussian_blur2d(img: np.ndarray, sigma: float = 1.0) -> np.ndarray:
"""Separable Gaussian blur."""
if float(sigma) <= 0.0:
return np.asarray(img, dtype=np.float64)
radius = max(1, int(math.ceil(3.0 * float(sigma))))
x = np.arange(-radius, radius + 1, dtype=np.float64)
k = np.exp(-(x**2) / (2.0 * sigma * sigma))
k /= np.sum(k)
arr = np.asarray(img, dtype=np.float64)
for i in range(arr.shape[0]):
arr[i, :] = np.convolve(arr[i, :], k, mode="same")
for j in range(arr.shape[1]):
arr[:, j] = np.convolve(arr[:, j], k, mode="same")
return arr
def _draw_cylinders(rgb: np.ndarray, cylinders: Sequence[CylinderSpec]) -> None:
ny, nx = rgb.shape[0], rgb.shape[1]
yy, xx = np.mgrid[0:ny, 0:nx]
for (cx, cy), radius in cylinders:
mask = (xx - float(cx)) ** 2 + (yy - float(cy)) ** 2 <= float(radius) ** 2
rgb[mask] = 0.0
def render_density(
positions: np.ndarray,
ages: np.ndarray,
*,
nx: int,
ny: int,
out_path: str,
cylinders: Sequence[CylinderSpec] = (),
age_decay_steps: float = 20000.0,
blur_sigma: float = 1.2,
background_color: tuple[float, float, float] = (0.0, 0.0, 0.0),
streak_color: tuple[float, float, float] = (1.0, 0.5, 0.0),
show_release_points: Optional[np.ndarray] = None,
) -> dict:
"""Render streakline particle cloud as a density image.
Particles are binned onto the pixel grid with age-weighted exponential
decay, Gaussian-blurred, then composited onto *background_color* using
*streak_color*.
"""
density = _build_density_map(
positions, ages, nx, ny, age_decay_steps=age_decay_steps
)
density = gaussian_blur2d(density, sigma=float(blur_sigma))
return _save_minimal_image(
density,
nx,
ny,
out_path,
cylinders,
background_color=background_color,
streak_color=streak_color,
release_points=show_release_points,
)
def _build_density_map(
positions: np.ndarray,
ages: np.ndarray,
nx: int,
ny: int,
*,
age_decay_steps: float,
) -> np.ndarray:
if positions.size == 0:
return np.zeros((ny, nx), dtype=np.float64)
w = np.exp(-np.asarray(ages, dtype=np.float64) / max(1.0, float(age_decay_steps)))
y_idx = np.clip(np.floor(positions[:, 1]).astype(np.int64), 0, ny - 1)
x_idx = np.clip(np.floor(positions[:, 0]).astype(np.int64), 0, nx - 1)
density = np.zeros((ny, nx), dtype=np.float64)
np.add.at(density, (y_idx, x_idx), w)
return density
def _save_minimal_image(
density: np.ndarray,
nx: int,
ny: int,
out_path: str,
cylinders: Sequence[CylinderSpec],
*,
background_color: tuple[float, float, float],
streak_color: tuple[float, float, float],
release_points: Optional[np.ndarray] = None,
) -> dict:
"""Compose density into an RGB image and save (no matplotlib axes)."""
rgb = np.ones((ny, nx, 3), dtype=np.float64)
rgb[:, :, 0] = background_color[0]
rgb[:, :, 1] = background_color[1]
rgb[:, :, 2] = background_color[2]
if np.any(density > 0):
vmax = float(np.percentile(density[density > 0], 99.0))
alpha = np.clip(density / max(vmax, 1e-12), 0.0, 1.0)
for c, val in enumerate(streak_color):
rgb[:, :, c] = np.clip(
rgb[:, :, c] * (1.0 - alpha) + val * alpha, 0.0, 1.0
)
if cylinders:
_draw_cylinders(rgb, cylinders)
os.makedirs(os.path.dirname(os.path.abspath(out_path)), exist_ok=True)
try:
import matplotlib
matplotlib.use("Agg")
import matplotlib.pyplot as plt
fig = plt.figure(figsize=(nx / 100.0, ny / 100.0), dpi=100)
ax = fig.add_axes([0.0, 0.0, 1.0, 1.0])
ax.axis("off")
ax.imshow(rgb, origin="lower", interpolation="nearest", aspect="auto")
fig.savefig(out_path, dpi=100, bbox_inches="tight", pad_inches=0)
plt.close(fig)
except ImportError:
from PIL import Image
Image.fromarray((np.clip(rgb, 0.0, 1.0) * 255.0).astype(np.uint8)).save(
out_path
)
return {
"image_path": out_path,
"n_particles": int(density.sum()),
"density_max": float(np.max(density)) if density.size else 0.0,
}
@@ -0,0 +1,117 @@
# CelerisLab/common/streakline/_streakline.py
"""
Streakline — passive-consumer particle-based flow visualization.
"""
from __future__ import annotations
from dataclasses import dataclass, field
from typing import Optional, Sequence
import numpy as np
from ._config import (
CylinderSpec,
FlowFrame,
IntegratorConfig,
ReleaseConfig,
build_release_points,
)
from ._integrate import advance_between_frames, inject_particles
from ._render import render_density
@dataclass
class Streakline:
"""Passive streakline integrator.
Does **not** own a simulation or control the stepping loop. Users call
``observe()`` whenever they have a new velocity frame; body actions,
checkpointing, and other modules are managed independently.
Usage::
streak = Streakline(release_points=..., nx=nx, ny=ny, ...)
# In your own simulation loop:
macro = sim.get_macroscopic()
streak.observe(ux=macro["ux"], uy=macro["uy"], step=step)
streak.render("output.png")
"""
release_points: np.ndarray
release_cfg: ReleaseConfig
integrator_cfg: IntegratorConfig
nx: int
ny: int
cylinders: Sequence[CylinderSpec] = field(default_factory=list)
_particles: np.ndarray = field(init=False, repr=False)
_ages: np.ndarray = field(init=False, repr=False)
_prev_frame: Optional[FlowFrame] = field(init=False, repr=False, default=None)
def __post_init__(self):
self._particles = np.zeros((0, 2), dtype=np.float64)
self._ages = np.zeros((0,), dtype=np.float64)
self._dense_pts = build_release_points(
np.asarray(self.release_points), self.release_cfg
)
def observe(self, ux: np.ndarray, uy: np.ndarray, step: int) -> dict:
"""Feed one velocity snapshot.
First call caches the frame. From the second call onward particles
are injected and advanced from the previous frame to this one.
"""
frame = FlowFrame(
step=int(step),
ux=np.asarray(ux, dtype=np.float64),
uy=np.asarray(uy, dtype=np.float64),
)
if self._prev_frame is None:
self._prev_frame = frame
return {}
self._particles, self._ages = inject_particles(
self._particles,
self._ages,
self._dense_pts,
inject_per_seed=self.release_cfg.inject_per_seed,
)
self._particles, self._ages, diag, _ = advance_between_frames(
self._particles,
self._ages,
self._prev_frame,
frame,
nx=self.nx,
ny=self.ny,
cfg=self.integrator_cfg,
cylinders=self.cylinders,
)
self._prev_frame = frame
return diag
def render(self, out_path: str, **kwargs) -> dict:
"""Render current particle cloud as a density image."""
# Default age_decay_steps from integrator config; **kwargs may override
kw = dict(kwargs, cylinders=self.cylinders)
kw.setdefault("age_decay_steps", self.integrator_cfg.age_decay_steps)
return render_density(
self._particles,
self._ages,
nx=self.nx,
ny=self.ny,
out_path=out_path,
**kw,
)
@property
def n_particles(self) -> int:
return self._particles.shape[0]
def reset(self):
self._particles = np.zeros((0, 2), dtype=np.float64)
self._ages = np.zeros((0,), dtype=np.float64)
self._prev_frame = None
+258
View File
@@ -0,0 +1,258 @@
# CelerisLab/config.py
"""
Unified configuration system.
Two JSON files:
config_lbm.json – grid, physics, method, cuda
config_body.json – object list
LBMConfig / BodyConfig are plain dataclasses; they translate to
macro dicts consumed by `cuda/compiler_v2.py` for header generation.
"""
import json
import os
from dataclasses import dataclass, field
from typing import Any, Dict, List, Optional
# ---------------------------------------------------------------------------
# String ↔ integer mappings (used in JSON and macro generation)
# ---------------------------------------------------------------------------
LATTICE_MODEL_MAP = {
"D2Q9": {"dim": 2, "nq": 9, "id": 0},
"D3Q19": {"dim": 3, "nq": 19, "id": 1},
}
COLLISION_MAP = {"SRT": 0, "TRT": 1, "MRT": 2}
STREAMING_MAP = {"double_buffer": 0, "esopull": 1}
PRECISION_MAP = {"FP32": 0, "FP16S": 1, "FP16C": 2}
INLET_MAP = {"uniform": 0, "parabolic": 1}
INLET_SCHEME_MAP = {
"zou_he_local": 0,
"channel_stabilized": 1,
"equilibrium": 2,
"regularized": 3,
}
OUTLET_MAP = {"neq_extrap": 0, "zero_gradient": 1, "blended": 2}
Y_WALL_BC_MAP = {"bounce_back": 0, "free_slip": 1}
DTYPE_MAP = {"FP32": "float", "FP64": "double"}
# ---------------------------------------------------------------------------
# LBM config
# ---------------------------------------------------------------------------
# ⚠ THIS IS NOT THE CONFIGURATION LOCATION.
# All parameters come from configs/config_lbm.json (the single source of truth).
# Use load_lbm_config() to construct; do not instantiate LBMConfig() with
# bare defaults. Tests may pass explicit kwargs for override only.
# See configs/CONFIG.md for parameter documentation.
# ---------------------------------------------------------------------------
@dataclass
class LBMConfig:
# Lattice model (canonical: determines dim and nq)
lattice_model: str = "D2Q9"
# Grid
nx: int = 512
ny: int = 256
nz: int = 1
# Physics
data_type: str = "FP32"
viscosity: float = 0.002
velocity: float = 0.03
rho: float = 1.0
# Method – collision / streaming / storage
collision: str = "SRT"
streaming: str = "double_buffer"
store_precision: str = "FP32"
ddf_shifting: bool = False
les_enabled: bool = False
les_cs: float = 0.16
les_closed_form: bool = True
trt_magic_param: float = 0.1875
inlet_profile: str = "parabolic"
inlet_scheme: str = "zou_he_local"
outlet_mode: str = "neq_extrap"
outlet_blend_alpha: float = 0.7
outlet_backflow_clamp: bool = True
inlet_trt_neq_damp: float = 0.5
inlet_regularized_neq_damp: float = 0.5
outlet_srt_neq_damp: float = 0.5
y_wall_bc: str = "bounce_back"
omega_min: float = 0.01
omega_max: float = 1.99
# CUDA
threads_per_block: int = 256
compute_capability: str = "auto"
# Derived (computed on validate — do not set manually)
dim: int = 0
nq: int = 0
omega: float = 0.0
@property
def is_d2q9(self) -> bool:
return self.lattice_model == "D2Q9"
@property
def is_d3q19(self) -> bool:
return self.lattice_model == "D3Q19"
def validate(self):
assert self.lattice_model in LATTICE_MODEL_MAP, (
f"Unknown lattice_model: {self.lattice_model}. "
f"Supported: {list(LATTICE_MODEL_MAP.keys())}")
lm = LATTICE_MODEL_MAP[self.lattice_model]
self.dim = lm["dim"]
self.nq = lm["nq"]
self.lattice_model_id = lm["id"]
assert self.collision in COLLISION_MAP, f"Unknown collision: {self.collision}"
assert self.streaming in STREAMING_MAP, f"Unknown streaming: {self.streaming}"
assert self.y_wall_bc in Y_WALL_BC_MAP, f"Unknown y_wall_bc: {self.y_wall_bc}"
assert self.data_type in DTYPE_MAP, f"Unknown data_type: {self.data_type}"
assert self.store_precision in PRECISION_MAP, (
f"Unknown store_precision: {self.store_precision}")
assert self.inlet_scheme in INLET_SCHEME_MAP, (
f"Unknown inlet_scheme: {self.inlet_scheme}")
if self.store_precision == "FP16C":
raise ValueError(
"store_precision='FP16C' is not supported in the current runtime path. "
"Supported store_precision values: FP32, FP16S."
)
if self.data_type != "FP32":
raise ValueError(
"Only data_type='FP32' is supported: CUDA kernels and LBMField "
"paths use float32; LBtype is not wired through device code yet."
)
assert self.nx > 0 and self.ny > 0 and self.nz > 0
if self.dim == 2:
assert self.nz == 1, "nz must be 1 for 2D"
if not (0.0 <= self.inlet_trt_neq_damp <= 1.0):
raise ValueError("method.inlet.trt_neq_damp must lie in [0, 1].")
if not (0.0 <= self.inlet_regularized_neq_damp <= 1.0):
raise ValueError("method.inlet.regularized_neq_damp must lie in [0, 1].")
if not (0.0 <= self.outlet_srt_neq_damp <= 1.0):
raise ValueError("method.outlet.srt_neq_damp must lie in [0, 1].")
if self.dim == 3 and self.y_wall_bc == "free_slip":
raise ValueError("y_wall_bc='free_slip' is currently supported for D2Q9 only.")
if self.omega_max >= 2.0:
raise ValueError("method.omega_guard.max must be < 2.0.")
if self.omega_min >= self.omega_max:
raise ValueError(
f"Invalid omega guard window: min={self.omega_min}, max={self.omega_max}."
)
self.omega = 1.0 / (3.0 * self.viscosity + 0.5)
if not (self.omega_min <= self.omega <= self.omega_max):
raise ValueError(
f"Computed omega={self.omega:.6f} outside guard "
f"[{self.omega_min:.6f}, {self.omega_max:.6f}]."
)
def to_macros(self) -> Dict[str, Any]:
"""Return flat dict of macro_name → value for header generation."""
self.validate()
return {
"NT": self.threads_per_block,
"MULT_GPU": 0,
"NX": self.nx,
"NY": self.ny,
"NZ": self.nz,
"LATTICE_MODEL": self.lattice_model_id,
"LBtype": DTYPE_MAP[self.data_type],
"VIS": f"{self.viscosity:.10f}",
"RHO": f"{self.rho:.1f}",
"U0": f"{self.velocity}",
"COLLISION_MODEL": COLLISION_MAP[self.collision],
"STREAMING_MODEL": STREAMING_MAP[self.streaming],
"STORE_PRECISION": PRECISION_MAP[self.store_precision],
"USE_DDF_SHIFTING": int(self.ddf_shifting),
"USE_LES": int(self.les_enabled),
"LES_CS": f"{self.les_cs:.6f}f",
"LES_CLOSED_FORM": int(self.les_closed_form),
"INLET_PROFILE": INLET_MAP[self.inlet_profile],
"INLET_SCHEME": INLET_SCHEME_MAP[self.inlet_scheme],
"OUTLET_MODE": OUTLET_MAP[self.outlet_mode],
"OUTLET_BLEND_ALPHA": f"{self.outlet_blend_alpha:.3f}f",
"OUTLET_BACKFLOW_CLAMP": int(self.outlet_backflow_clamp),
"Y_WALL_BC": Y_WALL_BC_MAP[self.y_wall_bc],
"OMEGA_COLLISION_MIN": f"{self.omega_min:.2f}f",
"OMEGA_COLLISION_MAX": f"{self.omega_max:.3f}f",
"TRT_MAGIC_PARAM": f"{self.trt_magic_param:.6f}f",
"INLET_TRT_NEQ_DAMP": f"{self.inlet_trt_neq_damp:.4f}f",
"INLET_REGULARIZED_NEQ_DAMP": f"{self.inlet_regularized_neq_damp:.4f}f",
"OUTLET_SRT_NEQ_DAMP": f"{self.outlet_srt_neq_damp:.4f}f",
}
# ---------------------------------------------------------------------------
# Body config
# ---------------------------------------------------------------------------
@dataclass
class BodyConfig:
objects: List[Dict[str, Any]] = field(default_factory=list)
# ---------------------------------------------------------------------------
# Loaders
# ---------------------------------------------------------------------------
def _find_config(filename: str, explicit_path: Optional[str] = None) -> str:
"""Search for config file in standard locations."""
candidates = []
if explicit_path:
candidates.append(explicit_path)
env_dir = os.environ.get("CELERISLAB_CONFIG_DIR")
if env_dir:
candidates.append(os.path.join(env_dir, filename))
candidates.append(os.path.join(os.getcwd(), "configs", filename))
pkg_root = os.path.dirname(os.path.abspath(__file__))
candidates.append(os.path.join(pkg_root, "configs", filename))
for p in candidates:
if os.path.isfile(p):
return os.path.abspath(p)
raise FileNotFoundError(
f"Config '{filename}' not found. Searched:\n"
+ "\n".join(f" - {p}" for p in candidates)
)
def load_lbm_config(path: Optional[str] = None) -> LBMConfig:
fpath = _find_config("config_lbm.json", path)
with open(fpath) as f:
d = json.load(f)
g, p, m, c = d["grid"], d["physics"], d["method"], d["cuda"]
cfg = LBMConfig(
lattice_model=g["lattice_model"],
nx=g["nx"], ny=g["ny"], nz=g["nz"],
data_type=p["data_type"], viscosity=p["viscosity"],
velocity=p["velocity"], rho=p["rho"],
collision=m["collision"], streaming=m["streaming"],
store_precision=m["store_precision"],
ddf_shifting=m["ddf_shifting"],
les_enabled=m["les"]["enabled"], les_cs=m["les"]["cs"],
les_closed_form=m["les"].get("closed_form", True),
trt_magic_param=m["trt"]["magic_param"],
inlet_profile=m["inlet"]["profile"],
inlet_scheme=m["inlet"].get("scheme", "zou_he_local"),
outlet_mode=m["outlet"]["mode"],
outlet_blend_alpha=m["outlet"]["blend_alpha"],
outlet_backflow_clamp=m["outlet"]["backflow_clamp"],
inlet_trt_neq_damp=m["inlet"].get("trt_neq_damp", 0.5),
inlet_regularized_neq_damp=m["inlet"].get("regularized_neq_damp", 0.5),
outlet_srt_neq_damp=m["outlet"].get("srt_neq_damp", 0.5),
y_wall_bc=m.get("y_wall_bc", "bounce_back"),
omega_min=m["omega_guard"]["min"],
omega_max=m["omega_guard"]["max"],
threads_per_block=c["threads_per_block"],
compute_capability=c["compute_capability"],
)
cfg.validate()
return cfg
def load_body_config(path: Optional[str] = None) -> BodyConfig:
fpath = _find_config("config_body.json", path)
with open(fpath) as f:
d = json.load(f)
return BodyConfig(objects=d.get("objects", []))
+103
View File
@@ -0,0 +1,103 @@
# CelerisLab 配置说明
**唯一配置入口:`config_lbm.json`**
Python `config.py` 只负责读取和校验,不是配置位置。
---
## grid — 网格
| 字段 | 类型 | 默认 | 允许值 | 说明 |
|------|------|------|--------|------|
| `lattice_model` | string | `"D2Q9"` | `D2Q9`, `D3Q19` | 格子模型,决定维度和速度数量 |
| `nx` | int | 512 | >0 | x 方向格点数(流向),建议整除 `threads_per_block` 以减少尾块浪费 |
| `ny` | int | 256 | >0 | y 方向格点数 |
| `nz` | int | 1 | >0 | z 方向格点数,D2Q9 时必须为 1 |
## physics — 物理参数
| 字段 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `data_type` | string | `"FP32"` | 计算精度:当前仅实现 **`FP32`**(CUDA 核与 `LBMField` 主机缓冲为 float32;`FP64` 会在校验阶段被拒绝) |
| `viscosity` | float | 0.0035 | 运动粘度(格子单位),ω = 1/(3ν + 0.5) |
| `velocity` | float | 0.03 | 入口速度(格子单位) |
| `rho` | float | 1.0 | 参考密度 |
## method — 算法
| 字段 | 类型 | 默认 | 允许值 | 说明 |
|------|------|------|--------|------|
| `collision` | string | `"SRT"` | `SRT`, `TRT`, `MRT` | 碰撞算子 |
| `streaming` | string | `"double_buffer"` | `double_buffer`, `esopull` | 流传输方式。运行时 body 拓扑同步 (``sync_bodies()``) 两种模式均支持 |
| `store_precision` | string | `"FP32"` | `FP32`, `FP16S`, `FP16C` | GPU 存储精度。当前运行时已实现 `FP32` 与 `FP16S`,`FP16C` 仍为保留选项 |
| `ddf_shifting` | bool | false | | 存储 f−w 而非 f,提升 FP16 精度 |
| `les.enabled` | bool | false | | LES Smagorinsky 子格模型 |
| `les.cs` | float | 0.16 | | Smagorinsky 常数 |
| `les.closed_form` | bool | true | | 闭合形式 τ_eff(vs 迭代) |
| `trt.magic_param` | float | 0.1875 | | TRT Λ 参数,高 Re 建议 0.001 |
| `inlet.profile` | string | `"parabolic"` | `uniform`, `parabolic` | 入口速度剖面(物理目标速度,与 scheme 独立) |
| `inlet.scheme` | string | `"zou_he_local"` | `zou_he_local`, `channel_stabilized`, `equilibrium`, `regularized` | 入口数值闭合。`zou_he_local` 为本地 Zou-He,适合研究或 MRT 路径;`channel_stabilized` 为 donor NEQ 稳定化入口,适合高阻塞或更保守的量产路径;`equilibrium` 直接写入 `feq` 源态,适合 ghost-source 架构下的稳健 SRT 基线;`regularized` 使用本地宏量加 incoming donor NEQ 阻尼,是介于 `equilibrium` 与 `channel_stabilized` 之间的实验入口 |
| `inlet.trt_neq_damp` | float | 0.5 | [0, 1] | 仅 `channel_stabilized`:TRT 入口 donor NEQ 阻尼;更小更平滑、精度略降 |
| `inlet.regularized_neq_damp` | float | 0.5 | [0, 1] | 仅 `regularized`:incoming 方向 donor NEQ 阻尼;0 退化到 unknown 方向仅平衡态,1 为 unknown 方向全 donor NEQ |
| `outlet.mode` | string | `"neq_extrap"` | `neq_extrap`, `zero_gradient`, `blended` | 出口条件 |
| `outlet.backflow_clamp` | bool | true | | 出口回流钳位 |
| `outlet.blend_alpha` | float | 0.7 | | `blended` 下对未知入域方向的混合系数(**所有碰撞模型**共用同一路径) |
| `outlet.srt_neq_damp` | float | 0.5 | [0, 1] | 仅当 `outlet.mode` 为 **`neq_extrap`** 且碰撞为 **SRT/TRT** 时:出口全分布 damped NEQ 的阻尼系数。`outlet.mode` 为 **`blended`** 时 SRT/TRT 走混合未知方向分支,不使用本键。MRT + `neq_extrap` 仍为少量方向的 NEQ 外推 |
| `y_wall_bc` | string | `"bounce_back"` | `bounce_back`, `free_slip` | y 向上下壁面边界条件(仅壁面相邻流体行生效) |
| `omega_guard.min` | float | 0.01 | | ω 下界(LES τ_eff 保护) |
| `omega_guard.max` | float | 1.99 | | ω 上界,高 Re 建议 1.90-1.99 |
## cuda — 编译
| 字段 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `threads_per_block` | int | 256 | CUDA block 线程数,V100 最优 256 |
| `compute_capability` | string | `"auto"` | 目标 SM 架构,`auto` 自动检测 |
---
## 配置 → 代码映射
```
**`lbm/kernels/config/*.h` 由编译器根据 `LBMConfig` 自动生成,请勿手改。**
仓库中可能检入过历史版本的 `config/*.h`,与当前默认 JSON **不一定一致**;若以 Python 入口运行仿真,`Simulation` / `compiler_v2.generate_config` 会在编译前重写这些头文件。若只用 `nvcc` 单独编译 `kernel_v2.cu` 且跳过 `generate_config`,则可能读到陈旧宏,属不受支持用法。
config_lbm.json
↓ load_lbm_config()
config.py:LBMConfig (读取 + 校验)
↓ to_macros()
cuda/compiler_v2.py (生成 config/*.h)
↓
config_grid.h → NX, NY, NZ, NT, LATTICE_MODEL;
DIM / NQ 由 LATTICE_MODEL 推导写入(与 grid.lattice_model 一致,非 JSON 顶层字段)
config_physics.h → LBtype, VIS, RHO, U0
config_method.h → COLLISION_MODEL, STORE_PRECISION, USE_LES, Y_WALL_BC, ...
config_objects.h → N_OBJS
config_obs.h → OBS_*(打包遥测:force/torque/sensor 三段的 offset/stride 宏;`OBS_N_SLOTS=max(N_OBJS,1)`;由 `generate_config(cfg, n_objects=K)` 写入;**无**单独 JSON 字段,DIM 仍由格子模型推导)
↓ #include
descriptors.cuh → d_cx[], d_cy[], d_w[] (CUDA __constant__)
step/one_step_*.cu → kernel 编排
```
### 旋转物体数据契约(Rotating body contract)
- 几何参数(如 `rx`, `ry`)在 `initialize()` 后应视为不变量;改变几何属于拓扑变更,需要重新构建物体并重新初始化。
- 转速 `omega` 属于运行时状态,可在步进期间更新;该更新不改变 `N_OBJS` 或 `OBS_*` 内存布局,因此**不需要**因 `omega` 变化触发重新编译。
- 力矩观测从 `obs` 的 torque segment 读取;force / torque / sensor 段统一由 `config_obs.h` 宏描述。
### 稳定性默认窗口(Stability defaults)
- 默认 `method.omega_guard = {min: 0.01, max: 1.99}`,用于约束碰撞频率与 LES 有效粘度路径。
- 高 Re 调参建议将 `omega_guard.max` 保持在 `1.90-1.99` 区间;过高上界会增大接近 `omega -> 2` 的不稳定风险。
### 运行时 body 拓扑同步
- 运行时增删 body(`add_body()` / `remove_body()` + `sync_bodies()`)在 ``double_buffer`` 和 ``esopull`` 两种流模式下均支持。
- 用法相同,无需特别的运行时检查。
### 力区域标记(Force region flag)
D2Q9/D3Q19 的 flag 扩展位 `0x0800` 定义为 `FRC_REGION`,用于标记 force_region 类型物体的格子。
- ForceRegionKernel 不依赖 flag 位执行,flag 只用于后处理可视化。
- `merge_flag_masks` 会正确合并 force_region 的 `FLUID | FRC_REGION` 标记。
+3
View File
@@ -0,0 +1,3 @@
{
"objects": []
}
+65
View File
@@ -0,0 +1,65 @@
{
"_doc": "CelerisLab LBM configuration — single source of truth. See configs/CONFIG.md for full documentation.",
"grid": {
"lattice_model": "D2Q9",
"_lattice_model": "D2Q9 | D3Q19",
"nx": 512,
"ny": 256,
"nz": 1
},
"physics": {
"data_type": "FP32",
"_data_type": "FP32 only for now (FP64 rejected at validate — kernels/host float32)",
"viscosity": 0.0035,
"velocity": 0.03,
"rho": 1.0
},
"method": {
"collision": "SRT",
"_collision": "SRT | TRT | MRT",
"streaming": "double_buffer",
"_streaming": "double_buffer | esopull",
"store_precision": "FP32",
"_store_precision": "FP32 | FP16S | FP16C — GPU DDF storage",
"ddf_shifting": false,
"les": {
"enabled": false,
"cs": 0.16,
"closed_form": true
},
"trt": {
"magic_param": 0.1875
},
"inlet": {
"profile": "parabolic",
"scheme": "zou_he_local",
"_profile": "uniform | parabolic",
"_scheme": "zou_he_local | channel_stabilized | equilibrium | regularized",
"trt_neq_damp": 0.5,
"_trt_neq_damp": "channel_stabilized only. TRT donor NEQ damping [0,1]. Lower = smoother inlet, less accurate.",
"regularized_neq_damp": 0.5,
"_regularized_neq_damp": "regularized only. Incoming-direction donor NEQ damping [0,1]. 0 = equilibrium-only on unknowns, 1 = full donor NEQ on unknowns."
},
"outlet": {
"mode": "neq_extrap",
"_mode": "neq_extrap | zero_gradient | blended",
"backflow_clamp": true,
"blend_alpha": 0.7,
"srt_neq_damp": 0.5,
"_srt_neq_damp": "SRT outlet NEQ donor damping [0,1]. Lower = less checkerboard noise."
},
"y_wall_bc": "bounce_back",
"_y_wall_bc": "bounce_back | free_slip",
"omega_guard": {
"min": 0.01,
"max": 1.99,
"_doc": "High-Re: keep max in 1.90-1.99"
}
},
"cuda": {
"threads_per_block": 256,
"compute_capability": "auto",
"_compute_capability": "auto | e.g. 7.0"
}
}
@@ -0,0 +1,52 @@
{
"_doc": "Three rotating cylinders in confined channel (triangle layout, free-slip walls).",
"_variant": "MRT + zou_he_local inlet — Phase 2 candidate from Kan99b K2 screening",
"_screening": "Kan99b K2 D=20: St err=1.51%, CD err=1.76%, C'D err=1.42%",
"grid": {
"lattice_model": "D2Q9",
"nx": 3000,
"ny": 300,
"nz": 1
},
"physics": {
"data_type": "FP32",
"viscosity": 0.004,
"velocity": 0.04,
"rho": 1.0
},
"method": {
"collision": "MRT",
"streaming": "double_buffer",
"store_precision": "FP32",
"ddf_shifting": false,
"les": {
"enabled": false,
"cs": 0.16,
"closed_form": true
},
"trt": {
"magic_param": 0.1875
},
"inlet": {
"profile": "uniform",
"scheme": "zou_he_local",
"trt_neq_damp": 0.5,
"regularized_neq_damp": 0.5
},
"outlet": {
"mode": "neq_extrap",
"backflow_clamp": true,
"blend_alpha": 0.7,
"srt_neq_damp": 0.5
},
"y_wall_bc": "free_slip",
"omega_guard": {
"min": 0.01,
"max": 1.96
}
},
"cuda": {
"threads_per_block": 256,
"compute_capability": "auto"
}
}
@@ -0,0 +1,52 @@
{
"_doc": "Three rotating cylinders in confined channel (triangle layout, free-slip walls).",
"_variant": "TRT + regularized inlet — Phase 2 candidate from Kan99b K2 screening",
"_screening": "Kan99b K2 D=20: St err=2.43%, CD err=2.45%, C'D err=9.06%",
"grid": {
"lattice_model": "D2Q9",
"nx": 3000,
"ny": 300,
"nz": 1
},
"physics": {
"data_type": "FP32",
"viscosity": 0.004,
"velocity": 0.04,
"rho": 1.0
},
"method": {
"collision": "TRT",
"streaming": "double_buffer",
"store_precision": "FP32",
"ddf_shifting": false,
"les": {
"enabled": false,
"cs": 0.16,
"closed_form": true
},
"trt": {
"magic_param": 0.1875
},
"inlet": {
"profile": "uniform",
"scheme": "regularized",
"trt_neq_damp": 0.5,
"regularized_neq_damp": 0.5
},
"outlet": {
"mode": "neq_extrap",
"backflow_clamp": true,
"blend_alpha": 0.7,
"srt_neq_damp": 0.5
},
"y_wall_bc": "free_slip",
"omega_guard": {
"min": 0.01,
"max": 1.96
}
},
"cuda": {
"threads_per_block": 256,
"compute_capability": "auto"
}
}
@@ -0,0 +1,50 @@
{
"_doc": "Three rotating cylinders in confined channel (triangle layout, free-slip walls).",
"grid": {
"lattice_model": "D2Q9",
"nx": 1500,
"ny": 300,
"nz": 1
},
"physics": {
"data_type": "FP32",
"viscosity": 0.004,
"velocity": 0.04,
"rho": 1.0
},
"method": {
"collision": "MRT",
"streaming": "double_buffer",
"store_precision": "FP32",
"ddf_shifting": false,
"les": {
"enabled": false,
"cs": 0.16,
"closed_form": true
},
"trt": {
"magic_param": 0.1875
},
"inlet": {
"profile": "uniform",
"scheme": "regularized",
"trt_neq_damp": 0.5,
"regularized_neq_damp": 0.5
},
"outlet": {
"mode": "neq_extrap",
"backflow_clamp": true,
"blend_alpha": 0.7,
"srt_neq_damp": 0.5
},
"y_wall_bc": "free_slip",
"omega_guard": {
"min": 0.01,
"max": 1.96
}
},
"cuda": {
"threads_per_block": 256,
"compute_capability": "auto"
}
}
+8
View File
@@ -0,0 +1,8 @@
# CelerisLab/cuda/__init__.py
"""
CUDA compiler and kernel management utilities.
"""
from . import compiler_v2 as compiler
__all__ = ['compiler']
+226
View File
@@ -0,0 +1,226 @@
# CelerisLab/cuda/compiler_v2.py
"""
Kernel configuration, compilation, and module loading.
Workflow:
1. generate_config(lbm_cfg, n_objects) — write config/*.h from LBMConfig
2. compile_kernel(arch) — nvcc -ptx kernel_v2.cu
3. load_module(ptx_path) — PyCUDA module from PTX
"""
import os
import subprocess
from typing import Optional
import pycuda.driver as cuda
from ..config import LBMConfig
from .obs_layout import obs_layout # re-exported for body.manager import path
# ---------------------------------------------------------------------------
# Paths
# ---------------------------------------------------------------------------
_KERNEL_DIR = os.path.join(
os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
"lbm", "kernels",
)
def kernel_path(filename: str) -> str:
return os.path.join(_KERNEL_DIR, filename)
# ---------------------------------------------------------------------------
# Header generation (f-string templates, no external deps)
# ---------------------------------------------------------------------------
_HEADER = "// AUTO-GENERATED by CelerisLab compiler – DO NOT EDIT MANUALLY\n"
def _write(path: str, content: str):
os.makedirs(os.path.dirname(path), exist_ok=True)
tmp_path = f"{path}.tmp"
with open(tmp_path, "w") as f:
f.write(content)
os.replace(tmp_path, path)
def generate_config(cfg: LBMConfig, n_objects: int = 0):
"""Render all config/*.h files from *cfg*."""
m = cfg.to_macros()
cdir = os.path.join(_KERNEL_DIR, "config")
_write(os.path.join(cdir, "config_grid.h"), f"""{_HEADER}\
// Layer: Global / Grid
#ifndef CELERIS_CONFIG_GRID_H
#define CELERIS_CONFIG_GRID_H
#define NT {m['NT']}
#define MULT_GPU {m['MULT_GPU']}
#define NX {m['NX']}
#define NY {m['NY']}
#define NZ {m['NZ']}
// ---- Lattice model (single source of truth) ----
// Model IDs: 0=D2Q9, 1=D3Q19 (extend here for future models like D2Q19)
#define LATTICE_D2Q9 0
#define LATTICE_D3Q19 1
#define LATTICE_MODEL {m['LATTICE_MODEL']}
// DIM and NQ are derived from LATTICE_MODEL — do NOT set independently.
#if LATTICE_MODEL == LATTICE_D2Q9
#define DIM 2
#define NQ 9
#elif LATTICE_MODEL == LATTICE_D3Q19
#define DIM 3
#define NQ 19
#else
#error "Unknown LATTICE_MODEL. Supported: LATTICE_D2Q9 (0), LATTICE_D3Q19 (1)."
#endif
#endif
""")
_write(os.path.join(cdir, "config_physics.h"), f"""{_HEADER}\
// Layer: Global / Physics
#ifndef CELERIS_CONFIG_PHYSICS_H
#define CELERIS_CONFIG_PHYSICS_H
#define LBtype {m['LBtype']}
#define VIS {m['VIS']}
#define RHO {m['RHO']}
#define U0 {m['U0']}
#define PI 3.141592653589793238
// Flag constants are defined in core/flags.cuh (uint16_t).
// Do NOT redefine them here.
#define V_TAYLOR 1
#endif
""")
_write(os.path.join(cdir, "config_method.h"), f"""{_HEADER}\
// Layer: Method
#ifndef CELERIS_CONFIG_METHOD_H
#define CELERIS_CONFIG_METHOD_H
#define COLLISION_MODEL {m['COLLISION_MODEL']}
#define STREAMING_MODEL {m['STREAMING_MODEL']}
#define STORE_PRECISION {m['STORE_PRECISION']}
#define USE_DDF_SHIFTING {m['USE_DDF_SHIFTING']}
#define USE_LES {m['USE_LES']}
#define LES_CS {m['LES_CS']}
#define LES_CLOSED_FORM {m['LES_CLOSED_FORM']}
#define INLET_PROFILE {m['INLET_PROFILE']}
#define INLET_SCHEME {m['INLET_SCHEME']}
#define OUTLET_MODE {m['OUTLET_MODE']}
#define OUTLET_BLEND_ALPHA {m['OUTLET_BLEND_ALPHA']}
#define OUTLET_BACKFLOW_CLAMP {m['OUTLET_BACKFLOW_CLAMP']}
#define Y_WALL_BC {m['Y_WALL_BC']}
#define OMEGA_COLLISION_MIN {m['OMEGA_COLLISION_MIN']}
#define OMEGA_COLLISION_MAX {m['OMEGA_COLLISION_MAX']}
#define TRT_MAGIC_PARAM {m['TRT_MAGIC_PARAM']}
// NEQ damping coefficients for inlet/outlet BC reconstruction.
// TRT inlet: donor damping used by the channel_stabilized inlet.
// Regularized inlet: damping on incoming-direction donor NEQ.
// SRT outlet: damped outlet reconstruction to suppress checkerboard noise.
#define INLET_TRT_NEQ_DAMP {m['INLET_TRT_NEQ_DAMP']}
#define INLET_REGULARIZED_NEQ_DAMP {m['INLET_REGULARIZED_NEQ_DAMP']}
#define OUTLET_SRT_NEQ_DAMP {m['OUTLET_SRT_NEQ_DAMP']}
#endif
""")
_write(os.path.join(cdir, "config_objects.h"), f"""{_HEADER}\
// Layer: Case / Objects
#ifndef CELERIS_CONFIG_OBJECTS_H
#define CELERIS_CONFIG_OBJECTS_H
#define N_OBJS {n_objects}
#endif
""")
_write(os.path.join(cdir, "config_obs.h"), f"""{_HEADER}\
// Layer: Case / Objects — packed obs (force + torque + sensor), float indices not bytes
// Derived from N_OBJS (config_objects.h) and DIM (config_grid.h); include via config.h.
#ifndef CELERIS_CONFIG_OBS_H
#define CELERIS_CONFIG_OBS_H
#if (N_OBJS) >= 1
#define OBS_N_SLOTS (N_OBJS)
#else
#define OBS_N_SLOTS 1
#endif
#define OBS_SLOT_STRIDE_FLOATS ((OBS_N_SLOTS) * (DIM))
#define OBS_FORCE_FLOATS (OBS_SLOT_STRIDE_FLOATS)
#if DIM == 2
#define OBS_TORQUE_COMPONENTS 1
#else
#define OBS_TORQUE_COMPONENTS (DIM)
#endif
#define OBS_TORQUE_FLOATS ((OBS_N_SLOTS) * (OBS_TORQUE_COMPONENTS))
#define OBS_BODY_SLOT_FLOATS (3 * (DIM))
#define OBS_FORCE0_FLOATS 0
#define OBS_TORQUE0_FLOATS (OBS_FORCE0_FLOATS + OBS_FORCE_FLOATS)
#define OBS_SENSOR0_FLOATS (OBS_TORQUE0_FLOATS + OBS_TORQUE_FLOATS)
#define OBS_TOTAL_FLOATS (OBS_SENSOR0_FLOATS + OBS_SLOT_STRIDE_FLOATS)
#endif
""")
# ---------------------------------------------------------------------------
# Compilation
# ---------------------------------------------------------------------------
def compile_kernel(arch: str = "sm_70",
source: str = "kernel_v2.cu",
output: Optional[str] = None) -> str:
"""Compile *source* to PTX. Returns path to the .ptx file.
The translation unit includes ``config/*.h``. Those headers must match the
intended ``LBMConfig`` — call :func:`generate_config` before compiling.
Invoking ``nvcc`` on ``kernel_v2.cu`` alone can pick up stale checked-in
headers from ``lbm/kernels/config/``.
"""
src = kernel_path(source)
if output is None:
output = source.replace(".cu", ".ptx")
dst = kernel_path(output)
import shutil
nvcc = shutil.which("nvcc") or "/usr/local/cuda/bin/nvcc"
subprocess.run(
[nvcc, "-ptx", f"-arch={arch}", "--use_fast_math", src, "-o", dst],
check=True,
)
return dst
# ---------------------------------------------------------------------------
# Module loading
# ---------------------------------------------------------------------------
def load_module(ptx_path: Optional[str] = None) -> cuda.Module:
"""Load a compiled PTX as a PyCUDA module."""
if ptx_path is None:
ptx_path = kernel_path("kernel_v2.ptx")
return cuda.module_from_file(ptx_path)
# ---------------------------------------------------------------------------
# Back-compat helpers (used by test scripts)
# ---------------------------------------------------------------------------
def compile_kernel_v2(arch: str = "sm_70") -> str:
"""Alias for compile_kernel() kept for test-script compatibility."""
return compile_kernel(arch=arch)
+79
View File
@@ -0,0 +1,79 @@
# CelerisLab/cuda/context.py
"""
CUDA device selection, context lifecycle, and device info queries.
"""
import subprocess
from typing import Optional
import pycuda.driver as cuda
class CudaContext:
"""Manages a single CUDA device context.
Usage::
ctx = CudaContext(device_id=0)
# ... use PyCUDA ...
ctx.close()
Or as a context-manager::
with CudaContext(0) as ctx:
...
"""
def __init__(self, device_id: int = 0):
cuda.init()
if device_id < 0 or device_id >= cuda.Device.count():
raise ValueError(
f"device_id {device_id} invalid; "
f"{cuda.Device.count()} device(s) available."
)
self.device_id = device_id
self.device = cuda.Device(device_id)
self._ctx = self.device.make_context()
# -- properties ----------------------------------------------------------
@property
def name(self) -> str:
return self.device.name()
@property
def compute_capability(self) -> str:
cc = self.device.compute_capability()
return f"{cc[0]}.{cc[1]}"
@property
def sm_arch(self) -> str:
"""Return 'sm_XX' string for nvcc -arch."""
cc = self.device.compute_capability()
return f"sm_{cc[0]}{cc[1]}"
@property
def total_memory(self) -> int:
return self.device.total_memory()
# -- lifecycle -----------------------------------------------------------
def close(self):
if self._ctx is not None:
self._ctx.pop()
self._ctx = None
def __enter__(self):
return self
def __exit__(self, *exc):
self.close()
def __del__(self):
self.close()
def detect_compute_capability(device_id: int = 0) -> str:
"""Return 'sm_XX' for the given device without creating a persistent context."""
cuda.init()
dev = cuda.Device(device_id)
cc = dev.compute_capability()
return f"sm_{cc[0]}{cc[1]}"
+61
View File
@@ -0,0 +1,61 @@
# CelerisLab/cuda/obs_layout.py
"""Packed ``obs`` buffer layout for force / torque / sensor telemetry.
Usage::
Host code (e.g. ``ObjectManager``) and ``compiler_v2.generate_config`` must use
the same ``dim`` and ``n_objects`` so allocation sizes match device macros.
Design::
Segments are contiguous in this order:
1) force : ``max(n_objects, 1) * dim`` floats
2) torque : ``max(n_objects, 1) * (1 if dim==2 else dim)`` floats
3) sensor : ``max(n_objects, 1) * dim`` floats
"""
from typing import NamedTuple
class ObsLayout(NamedTuple):
"""Integer offsets and sizes in **float** elements (not bytes)."""
n_slots: int
torque_components: int
slot_stride_floats: int
force_floats: int
torque_floats: int
force0_floats: int
torque0_floats: int
sensor0_floats: int
total_floats: int
def obs_layout(dim: int, n_objects: int) -> ObsLayout:
"""Compute packed ``obs`` indices for force, torque, and sensor segments.
Args:
dim: Spatial dimension (2 or 3); must match ``LBMConfig.dim``.
n_objects: Number of registered objects; may be zero.
Returns:
:class:`ObsLayout` with segment sizes and float offsets.
"""
n_slots = max(int(n_objects), 1)
torque_components = 1 if int(dim) == 2 else int(dim)
slot_stride_floats = n_slots * dim
force_floats = slot_stride_floats
torque_floats = n_slots * torque_components
force0_floats = 0
torque0_floats = force0_floats + force_floats
sensor0_floats = torque0_floats + torque_floats
total_floats = sensor0_floats + slot_stride_floats
return ObsLayout(
n_slots=n_slots,
torque_components=torque_components,
slot_stride_floats=slot_stride_floats,
force_floats=force_floats,
torque_floats=torque_floats,
force0_floats=force0_floats,
torque0_floats=torque0_floats,
sensor0_floats=sensor0_floats,
total_floats=total_floats,
)
+16
View File
@@ -0,0 +1,16 @@
# CelerisLab/lbm/__init__.py
"""
Lattice Boltzmann Method module for fluid simulation.
"""
try:
from .descriptors import * # noqa: flags, lattice vectors
from .field import LBMField
from .stepper import LBMStepper
from .initializers import add_vortex
__all__ = ["LBMField", "LBMStepper", "add_vortex"]
except ImportError as e:
import warnings
warnings.warn(f"LBM module not fully available: {e}", ImportWarning)
__all__ = []
+375
View File
@@ -0,0 +1,375 @@
# CelerisLab/lbm/curved_links.py
"""Structure-of-arrays helpers for curved Bouzidi links and sensor probe lists.
Responsibilities:
Hold host columns and lazy GPU mirrors for compact boundary kernels.
Design::
Device columns are reused by capacity to avoid reallocating every upload.
``count`` tracks active rows while ``capacity`` tracks allocated rows.
"""
from __future__ import annotations
from dataclasses import dataclass, field
from typing import Optional
import numpy as np
import pycuda.driver as cuda
def _free_alloc(ptr: Optional[cuda.DeviceAllocation]) -> None:
if ptr is not None:
ptr.free()
@dataclass
class CurvedLinkSoA:
"""Cut-link columns on host with matching ``*_gpu`` device buffers."""
fluid_idx: np.ndarray = field(
default_factory=lambda: np.zeros(0, dtype=np.uint32))
dir: np.ndarray = field(
default_factory=lambda: np.zeros(0, dtype=np.uint8))
q: np.ndarray = field(
default_factory=lambda: np.zeros(0, dtype=np.float32))
body_id: np.ndarray = field(
default_factory=lambda: np.zeros(0, dtype=np.int32))
rx: np.ndarray = field(
default_factory=lambda: np.zeros(0, dtype=np.float32))
ry: np.ndarray = field(
default_factory=lambda: np.zeros(0, dtype=np.float32))
rz: np.ndarray = field(
default_factory=lambda: np.zeros(0, dtype=np.float32))
fallback_class: np.ndarray = field(
default_factory=lambda: np.zeros(0, dtype=np.uint8))
fluid_idx_gpu: Optional[cuda.DeviceAllocation] = None
dir_gpu: Optional[cuda.DeviceAllocation] = None
q_gpu: Optional[cuda.DeviceAllocation] = None
body_id_gpu: Optional[cuda.DeviceAllocation] = None
rx_gpu: Optional[cuda.DeviceAllocation] = None
ry_gpu: Optional[cuda.DeviceAllocation] = None
rz_gpu: Optional[cuda.DeviceAllocation] = None
fallback_class_gpu: Optional[cuda.DeviceAllocation] = None
count: int = 0
capacity: int = 0
def assign_host(
self,
fluid_idx: np.ndarray,
dir: np.ndarray,
q: np.ndarray,
body_id: np.ndarray,
rx: np.ndarray,
ry: np.ndarray,
rz: np.ndarray,
fallback_class: np.ndarray,
) -> None:
"""Store and validate host SoA columns for curved-link kernel inputs."""
expected_dtypes = {
"fluid_idx": np.uint32,
"dir": np.uint8,
"q": np.float32,
"body_id": np.int32,
"rx": np.float32,
"ry": np.float32,
"rz": np.float32,
"fallback_class": np.uint8,
}
raw_columns = {
"fluid_idx": fluid_idx,
"dir": dir,
"q": q,
"body_id": body_id,
"rx": rx,
"ry": ry,
"rz": rz,
"fallback_class": fallback_class,
}
columns = {}
for name, value in raw_columns.items():
arr = np.asarray(value)
if not np.can_cast(arr.dtype, expected_dtypes[name], casting="same_kind"):
raise TypeError(
f"CurvedLinkSoA column '{name}' dtype {arr.dtype} "
f"is incompatible with {np.dtype(expected_dtypes[name])}"
)
columns[name] = arr.astype(expected_dtypes[name], copy=False)
n = len(columns["fluid_idx"])
for name, col in columns.items():
if len(col) != n:
raise ValueError(
f"CurvedLinkSoA column '{name}' has length {len(col)} != {n}"
)
if not col.flags["C_CONTIGUOUS"]:
columns[name] = np.ascontiguousarray(col)
self.fluid_idx = columns["fluid_idx"]
self.dir = columns["dir"]
self.q = columns["q"]
self.body_id = columns["body_id"]
self.rx = columns["rx"]
self.ry = columns["ry"]
self.rz = columns["rz"]
self.fallback_class = columns["fallback_class"]
if self.q.size > 0:
if np.any((self.q <= 0.0) | (self.q > 1.0)):
raise ValueError("CurvedLinkSoA column 'q' must satisfy 0 < q <= 1")
if self.fallback_class.size > 0:
if not np.all(np.isin(self.fallback_class, (0, 1))):
raise ValueError(
"CurvedLinkSoA column 'fallback_class' must use classes {0, 1}"
)
def upload(self, stream: Optional[cuda.Stream] = None) -> None:
"""Upload host columns to GPU with capacity-based allocation reuse.
Args:
stream: If set, use async host-to-device copies on this stream.
"""
n = int(len(self.fluid_idx))
self.count = n
if n == 0:
return
if n > self.capacity or self.fluid_idx_gpu is None:
self.free_gpu_columns()
self.fluid_idx_gpu = cuda.mem_alloc(int(n * self.fluid_idx.dtype.itemsize))
self.dir_gpu = cuda.mem_alloc(int(n * self.dir.dtype.itemsize))
self.q_gpu = cuda.mem_alloc(int(n * self.q.dtype.itemsize))
self.body_id_gpu = cuda.mem_alloc(int(n * self.body_id.dtype.itemsize))
self.rx_gpu = cuda.mem_alloc(int(n * self.rx.dtype.itemsize))
self.ry_gpu = cuda.mem_alloc(int(n * self.ry.dtype.itemsize))
self.rz_gpu = cuda.mem_alloc(int(n * self.rz.dtype.itemsize))
self.fallback_class_gpu = cuda.mem_alloc(
int(n * self.fallback_class.dtype.itemsize)
)
self.capacity = n
assert self.fluid_idx_gpu is not None
assert self.dir_gpu is not None
assert self.q_gpu is not None
assert self.body_id_gpu is not None
assert self.rx_gpu is not None
assert self.ry_gpu is not None
assert self.rz_gpu is not None
assert self.fallback_class_gpu is not None
if stream is not None:
cuda.memcpy_htod_async(self.fluid_idx_gpu, self.fluid_idx, stream)
cuda.memcpy_htod_async(self.dir_gpu, self.dir, stream)
cuda.memcpy_htod_async(self.q_gpu, self.q, stream)
cuda.memcpy_htod_async(self.body_id_gpu, self.body_id, stream)
cuda.memcpy_htod_async(self.rx_gpu, self.rx, stream)
cuda.memcpy_htod_async(self.ry_gpu, self.ry, stream)
cuda.memcpy_htod_async(self.rz_gpu, self.rz, stream)
cuda.memcpy_htod_async(
self.fallback_class_gpu, self.fallback_class, stream)
else:
cuda.memcpy_htod(self.fluid_idx_gpu, self.fluid_idx)
cuda.memcpy_htod(self.dir_gpu, self.dir)
cuda.memcpy_htod(self.q_gpu, self.q)
cuda.memcpy_htod(self.body_id_gpu, self.body_id)
cuda.memcpy_htod(self.rx_gpu, self.rx)
cuda.memcpy_htod(self.ry_gpu, self.ry)
cuda.memcpy_htod(self.rz_gpu, self.rz)
cuda.memcpy_htod(self.fallback_class_gpu, self.fallback_class)
def free_gpu_columns(self) -> None:
"""Release device columns only (host arrays unchanged)."""
_free_alloc(self.fluid_idx_gpu)
_free_alloc(self.dir_gpu)
_free_alloc(self.q_gpu)
_free_alloc(self.body_id_gpu)
_free_alloc(self.rx_gpu)
_free_alloc(self.ry_gpu)
_free_alloc(self.rz_gpu)
_free_alloc(self.fallback_class_gpu)
self.fluid_idx_gpu = None
self.dir_gpu = None
self.q_gpu = None
self.body_id_gpu = None
self.rx_gpu = None
self.ry_gpu = None
self.rz_gpu = None
self.fallback_class_gpu = None
self.capacity = 0
def free(self) -> None:
"""Free GPU storage and reset ``count``."""
self.free_gpu_columns()
self.count = 0
@dataclass
class SensorSoA:
"""Sensor cell list with GPU mirrors for ``SensorKernel``."""
cells: np.ndarray = field(
default_factory=lambda: np.zeros(0, dtype=np.uint32))
obj_id: np.ndarray = field(
default_factory=lambda: np.zeros(0, dtype=np.int32))
cells_gpu: Optional[cuda.DeviceAllocation] = None
obj_id_gpu: Optional[cuda.DeviceAllocation] = None
count: int = 0
def assign_host(self, cells: np.ndarray, obj_id: np.ndarray) -> None:
"""Store host sensor columns."""
self.cells = cells
self.obj_id = obj_id
def upload(self, stream: Optional[cuda.Stream] = None) -> None:
"""Reallocate GPU columns and upload.
Args:
stream: If set, use async host-to-device copies on this stream.
"""
self.free_gpu_columns()
n = int(len(self.cells))
self.count = n
if n == 0:
return
self.cells_gpu = cuda.mem_alloc(int(self.cells.nbytes))
self.obj_id_gpu = cuda.mem_alloc(int(self.obj_id.nbytes))
if stream is not None:
cuda.memcpy_htod_async(self.cells_gpu, self.cells, stream)
cuda.memcpy_htod_async(self.obj_id_gpu, self.obj_id, stream)
else:
cuda.memcpy_htod(self.cells_gpu, self.cells)
cuda.memcpy_htod(self.obj_id_gpu, self.obj_id)
def free_gpu_columns(self) -> None:
_free_alloc(self.cells_gpu)
_free_alloc(self.obj_id_gpu)
self.cells_gpu = None
self.obj_id_gpu = None
def free(self) -> None:
"""Free GPU storage and reset ``count``."""
self.free_gpu_columns()
self.count = 0
@dataclass
class ForceRegionSoA:
"""Force-region cell list with GPU mirrors for ForceRegionKernel."""
cells: np.ndarray = field(
default_factory=lambda: np.zeros(0, dtype=np.uint32))
obj_id: np.ndarray = field(
default_factory=lambda: np.zeros(0, dtype=np.int32))
cells_gpu: Optional[cuda.DeviceAllocation] = None
obj_id_gpu: Optional[cuda.DeviceAllocation] = None
count: int = 0
def assign_host(self, cells: np.ndarray, obj_id: np.ndarray) -> None:
"""Store host force-region columns."""
self.cells = cells
self.obj_id = obj_id
def upload(self, stream: Optional[cuda.Stream] = None) -> None:
"""Reallocate GPU columns and upload.
Args:
stream: If set, use async host-to-device copies on this stream.
"""
self.free_gpu_columns()
n = int(len(self.cells))
self.count = n
if n == 0:
return
self.cells_gpu = cuda.mem_alloc(int(self.cells.nbytes))
self.obj_id_gpu = cuda.mem_alloc(int(self.obj_id.nbytes))
if stream is not None:
cuda.memcpy_htod_async(self.cells_gpu, self.cells, stream)
cuda.memcpy_htod_async(self.obj_id_gpu, self.obj_id, stream)
else:
cuda.memcpy_htod(self.cells_gpu, self.cells)
cuda.memcpy_htod(self.obj_id_gpu, self.obj_id)
def free_gpu_columns(self) -> None:
_free_alloc(self.cells_gpu)
_free_alloc(self.obj_id_gpu)
self.cells_gpu = None
self.obj_id_gpu = None
def free(self) -> None:
"""Free GPU storage and reset ``count``."""
self.free_gpu_columns()
self.count = 0
@dataclass
class EsoPullCurvedBuffer:
"""Intermediate buffers for EsoPull curved boundary (Prepare -> Apply).
Three arrays per link: correction value, target cell index, target slot.
Allocated once per n_curved, reused across steps (layout is static).
"""
corr_value: np.ndarray = field(
default_factory=lambda: np.zeros(0, dtype=np.float32))
target_cell: np.ndarray = field(
default_factory=lambda: np.zeros(0, dtype=np.uint32))
target_slot: np.ndarray = field(
default_factory=lambda: np.zeros(0, dtype=np.uint8))
corr_value_gpu: Optional[cuda.DeviceAllocation] = None
target_cell_gpu: Optional[cuda.DeviceAllocation] = None
target_slot_gpu: Optional[cuda.DeviceAllocation] = None
count: int = 0
def assign_host(self, corr_value: np.ndarray, target_cell: np.ndarray, target_slot: np.ndarray) -> None:
"""Store host-side intermediate buffer columns."""
self.corr_value = corr_value
self.target_cell = target_cell
self.target_slot = target_slot
def upload(self, stream: Optional[cuda.Stream] = None) -> None:
"""Reallocate GPU columns and upload.
Args:
stream: If set, use async host-to-device copies on this stream.
"""
self.free_gpu_columns()
n = int(len(self.corr_value))
self.count = n
if n == 0:
return
self.corr_value_gpu = cuda.mem_alloc(int(self.corr_value.nbytes))
self.target_cell_gpu = cuda.mem_alloc(int(self.target_cell.nbytes))
self.target_slot_gpu = cuda.mem_alloc(int(self.target_slot.nbytes))
if stream is not None:
cuda.memcpy_htod_async(self.corr_value_gpu, self.corr_value, stream)
cuda.memcpy_htod_async(self.target_cell_gpu, self.target_cell, stream)
cuda.memcpy_htod_async(self.target_slot_gpu, self.target_slot, stream)
else:
cuda.memcpy_htod(self.corr_value_gpu, self.corr_value)
cuda.memcpy_htod(self.target_cell_gpu, self.target_cell)
cuda.memcpy_htod(self.target_slot_gpu, self.target_slot)
def free_gpu_columns(self) -> None:
_free_alloc(self.corr_value_gpu)
_free_alloc(self.target_cell_gpu)
_free_alloc(self.target_slot_gpu)
self.corr_value_gpu = None
self.target_cell_gpu = None
self.target_slot_gpu = None
def free(self) -> None:
"""Free GPU storage and reset ``count``."""
self.free_gpu_columns()
self.count = 0
+50
View File
@@ -0,0 +1,50 @@
# CelerisLab/lbm/descriptors.py
"""
Python-side lattice descriptor constants.
This module is the **single authoritative source** for lattice velocity
vectors and flag constants on the Python side. The CUDA-side source of
truth lives in ``core/descriptors.cuh`` and ``core/flags.cuh``; the two
MUST be kept in sync (review on any change to either file).
Why here and not body/?
This is a multi-physics project — flags and lattice vectors are shared
across all physics modules (fluid, thermal, species, …), not specific
to solid bodies. ``body/`` imports from here, not the other way around.
"""
# ===================================================================
# Cell flag constants (must match core/flags.cuh — uint16 layout)
# ===================================================================
# Cell type [3:0]
FLUID = 0x0001
SOLID = 0x0002
GAS = 0x0004
INTERFACE = 0x0008
# BC subtype [7:4]
BC_WALL = 0x0010
BC_INLET = 0x0020
BC_OUTLET = 0x0030
BC_CURVED = 0x0040
BC_PERIODIC = 0x0050
BC_MOVING = 0x0060
# Extension [15:8]
SENSOR_FLAG = 0x0100
OBSTACLE = 0x0200
FRC_REGION = 0x0800
# ===================================================================
# D2Q9 lattice velocity vectors
# Must match descriptors.cuh D2Q9 ordering.
# Used by host geometry routines that run *before* CUDA module load.
# After module load, prefer field._read_lattice_vectors().
# ===================================================================
D2Q9_EX = (0, 1, -1, 0, 0, 1, -1, 1, -1)
D2Q9_EY = (0, 0, 0, 1, -1, 1, -1, -1, 1)
# ===================================================================
# D3Q19 lattice velocity vectors
# ===================================================================
D3Q19_EX = (0, 1,-1, 0, 0, 0, 0, 1,-1, 1,-1, 0, 0, 1,-1, 1,-1, 0, 0)
D3Q19_EY = (0, 0, 0, 1,-1, 0, 0, 1,-1, 0, 0, 1,-1, -1, 1, 0, 0, 1,-1)
D3Q19_EZ = (0, 0, 0, 0, 0, 1,-1, 0, 0, 1,-1, 1,-1, 0, 0, -1, 1, -1, 1)
+60
View File
@@ -0,0 +1,60 @@
# CelerisLab/lbm/equilibrium.py
"""
Host-side equilibrium and macroscopic helpers for D2Q9. (D2Q9 only)
These functions are shared by LBMField (macroscopic computation) and
body DDF patching. They operate on host NumPy arrays only and do not
require a CUDA module.
For the authoritative GPU-side equilibrium, see ``operators/equilibrium.cuh``.
Callers with ``dim != 2`` must not call these functions. The D3Q19
equilibrium path lives in the CUDA kernel layer and is not mirrored on
the host at present.
"""
from __future__ import annotations
import numpy as np
# D2Q9 velocity vectors (must match descriptors.cuh / descriptors.py)
_CX = np.array([0, 1, -1, 0, 0, 1, -1, 1, -1], dtype=np.float32)
_CY = np.array([0, 0, 0, 1, -1, 1, -1, -1, 1], dtype=np.float32)
_W = np.array([4/9, 1/9, 1/9, 1/9, 1/9, 1/36, 1/36, 1/36, 1/36],
dtype=np.float32)
def compute_feq_d2q9(rho: float, ux: float, uy: float) -> np.ndarray:
"""Compute D2Q9 equilibrium distribution ``f_eq``.
Args:
rho: Macroscopic density.
ux: x-velocity (lattice units).
uy: y-velocity (lattice units).
Returns:
9-element float32 array ``[f0 .. f8]``.
"""
u_sq = ux * ux + uy * uy
feq = np.empty(9, dtype=np.float32)
for i in range(9):
cu = _CX[i] * ux + _CY[i] * uy
feq[i] = rho * _W[i] * (
1.0 + 3.0 * cu + 4.5 * cu * cu - 1.5 * u_sq)
return feq
def compute_macro_from_ddf(f: np.ndarray) -> tuple[float, float, float]:
"""Compute rho, ux, uy from a 9-element D2Q9 DDF array.
Args:
f: 9-element float32 array of distribution functions.
Returns:
``(rho, ux, uy)`` tuple.
"""
rho = float(np.sum(f))
rho_safe = rho if abs(rho) > 1e-12 else 1.0
ux = float(np.sum(f * _CX)) / rho_safe
uy = float(np.sum(f * _CY)) / rho_safe
return rho, ux, uy
+469
View File
@@ -0,0 +1,469 @@
# CelerisLab/lbm/field.py
"""
LBMField — GPU memory for distribution functions, flags, and macroscopic data.
Owns:
ddf_gpu / temp_gpu – distribution-function double buffers
flag_gpu – cell-type flags
curved / sensors – SoA bundles for compact curved BC and sensor lists
Provides:
upload_params() – push LBMParams to __constant__ memory
get_ddf() / set_ddf()
get_macroscopic() – rho, ux, uy [, uz]
snapshot() / restore()
"""
import struct
from typing import Optional
import numpy as np
import pycuda.driver as cuda
from ..config import LBMConfig
from .curved_links import CurvedLinkSoA, SensorSoA, ForceRegionSoA, EsoPullCurvedBuffer
from .descriptors import FLUID, SOLID, BC_WALL, BC_INLET, BC_OUTLET
_SUPPORTED_STORE_PRECISIONS = ("FP32", "FP16S")
class LBMField:
"""Allocate and manage GPU arrays for one LBM domain."""
def __init__(self, cfg: LBMConfig, module: cuda.Module):
assert cfg.dim > 0 and cfg.nq > 0, (
"cfg.validate() must be called before constructing LBMField")
self.cfg = cfg
self.module = module
self.nx, self.ny, self.nz = cfg.nx, cfg.ny, cfg.nz
self.nq = cfg.nq
self.dim = cfg.dim
self.n = self.nx * self.ny * self.nz
self.dtype = np.float32 # compute precision always float32
# Storage precision: current runtime path supports FP32 and FP16S only.
_prec = getattr(cfg, 'store_precision', 'FP32')
if _prec not in _SUPPORTED_STORE_PRECISIONS:
supported = ", ".join(_SUPPORTED_STORE_PRECISIONS)
raise RuntimeError(
f"Unsupported store_precision '{_prec}' in LBMField. "
f"Supported runtime precisions: {supported}."
)
self.store_bytes = 2 if _prec == 'FP16S' else 4
self.store_dtype = np.float16 if _prec == 'FP16S' else np.float32
# Host arrays (always float32 for convenience)
self.ddf = np.zeros(self.n * self.nq, dtype=self.dtype)
self.flag = self.build_channel_flags()
# Compact lists (filled by ObjectManager.sync_to_gpu)
self.curved = CurvedLinkSoA()
self.sensors = SensorSoA()
self.force_regions = ForceRegionSoA()
self.esopull_curved = EsoPullCurvedBuffer()
# GPU allocations – sized by storage precision
_ddf_bytes = self.n * self.nq * self.store_bytes
self.ddf_gpu = cuda.mem_alloc(_ddf_bytes)
self.temp_gpu = cuda.mem_alloc(_ddf_bytes)
self.flag_gpu = cuda.mem_alloc(self.flag.nbytes)
# Macroscopic output buffers for EsoPull GPU diagnostics
_macro_bytes = self.n * 4
self.macro_rho_gpu = cuda.mem_alloc(_macro_bytes)
self.macro_ux_gpu = cuda.mem_alloc(_macro_bytes)
self.macro_uy_gpu = cuda.mem_alloc(_macro_bytes)
self._macro_rho = np.zeros(self.n, dtype=np.float32)
self._macro_ux = np.zeros(self.n, dtype=np.float32)
self._macro_uy = np.zeros(self.n, dtype=np.float32)
# Snapshot
self._ddf_snap: np.ndarray | None = None
self._host_ddf_step: int | None = None
# Cached lattice constants mirrored from CUDA __constant__ memory.
self._cached_w: np.ndarray | None = None
self._cached_vectors_2d: tuple[np.ndarray, np.ndarray] | None = None
self._cached_vectors_3d: tuple[np.ndarray, np.ndarray, np.ndarray] | None = None
# Host mirror of runtime parameters so partial updates preserve state.
self._runtime_params = {
"omega": float(cfg.omega),
"fx": 0.0,
"fy": 0.0,
"fz": 0.0,
"n_objects": 0,
}
# Upload d_params immediately
self._upload_params()
def invalidate_host_ddf_cache(self) -> None:
"""Mark host DDF mirror as stale after GPU-side updates."""
self._host_ddf_step = None
def invalidate_module_constant_cache(self) -> None:
"""Drop cached __constant__ mirrors after module replacement."""
self._cached_w = None
self._cached_vectors_2d = None
self._cached_vectors_3d = None
def build_channel_flags(self) -> np.ndarray:
"""Return a fresh host flag array for the base channel domain.
The returned array contains only the static channel topology:
inlet, outlet, y-walls, and interior fluid. Object overlays are applied
later by ObjectManager on top of this clean base, which avoids stale
obstacle bits when geometry is rebuilt or moved.
"""
flag = np.ones(self.n, dtype=np.uint16) * FLUID
if self.cfg.is_d2q9:
flag[0:self.nx] = SOLID | BC_WALL
flag[(self.ny - 1) * self.nx:self.ny * self.nx] = SOLID | BC_WALL
flag[::self.nx] = SOLID | BC_INLET
flag[self.nx - 1::self.nx] = SOLID | BC_OUTLET
flag[0] = SOLID | BC_WALL
flag[self.nx - 1] = SOLID | BC_WALL
flag[(self.ny - 1) * self.nx] = SOLID | BC_WALL
flag[self.ny * self.nx - 1] = SOLID | BC_WALL
return flag
flag = flag.reshape(self.nz, self.ny, self.nx)
flag[:, 0, :] = SOLID | BC_WALL
flag[:, self.ny - 1, :] = SOLID | BC_WALL
flag[:, :, 0] = SOLID | BC_INLET
flag[:, :, self.nx - 1] = SOLID | BC_OUTLET
flag[:, 0, 0] = SOLID | BC_WALL
flag[:, 0, self.nx - 1] = SOLID | BC_WALL
flag[:, self.ny - 1, 0] = SOLID | BC_WALL
flag[:, self.ny - 1, self.nx - 1] = SOLID | BC_WALL
return flag.reshape(-1)
@property
def n_curved(self) -> int:
return self.curved.count
@property
def n_sensor(self) -> int:
return self.sensors.count
@property
def n_force_region(self) -> int:
return self.force_regions.count
# -- DDF download with precision decode ----------------------------------
def download_ddf(self, *, step_id: int | None = None, force: bool = False):
"""Copy DDF from GPU to host self.ddf (float32), decoding FP16S if needed.
If DDF shifting is enabled, un-shifts by adding back lattice weights."""
# Fast path for repeated host queries within one solver step.
# Callers pass step_id from LBMStepper; force=True bypasses cache
# for snapshot-style semantics.
if not force and step_id is not None and self._host_ddf_step == int(step_id):
return
if self.store_bytes == 2:
buf = np.empty(self.n * self.nq, dtype=self.store_dtype)
cuda.memcpy_dtoh(buf, self.ddf_gpu)
if self.store_dtype == np.float16:
# FP16S: stored as half(val * 32768) → decode by / 32768
self.ddf[:] = buf.astype(np.float32) * 3.0517578125e-5
else:
self.ddf[:] = buf.astype(np.float32)
else:
cuda.memcpy_dtoh(self.ddf, self.ddf_gpu)
# Un-shift: kernel stores (f_i - w_i), restore to f_i for host analysis
if getattr(self.cfg, 'ddf_shifting', False):
w = self._read_lattice_weights()
ddf_2d = self.ddf.reshape(self.nq, -1)
for i in range(self.nq):
ddf_2d[i] += w[i]
# NOTE: EsoPull host DDF decode is NOT implemented here.
# After EsoPullStep stores results, fi[k,i] is in EsoPull backing layout
# (paired directions scattered across neighbor cells). Reconstructing
# physical DDF on the host requires per-cell neighbor tables.
# Use get_macroscopic() which automatically selects the correct path
# (host decode for double_buffer, GPU kernel for esopull).
# See load_physical_node_esopull / store_physical_node_esopull.
self._host_ddf_step = int(step_id) if step_id is not None else None
def _read_lattice_weights(self):
"""Read d_w[] from CUDA __constant__ memory (single source of truth in descriptors.cuh)."""
if self._cached_w is not None:
return self._cached_w
ptr, size = self.module.get_global("d_w")
w = np.empty(self.nq, dtype=np.float32)
cuda.memcpy_dtoh(w, ptr)
self._cached_w = w
return self._cached_w
# -- d_params upload -----------------------------------------------------
def _upload_params(self):
"""Pack LBMParams struct and upload to __constant__ d_params.
Must match struct LBMParams in core/params.cuh layout:
float omega;
float fx, fy, fz;
uint n_objects;
Total: 5 floats/uint words = 20 bytes.
"""
p = self._runtime_params
fmt = "=f fff I"
data = struct.pack(
fmt,
p["omega"],
p["fx"], p["fy"], p["fz"],
p["n_objects"],
)
ptr, size = self.module.get_global("d_params")
cuda.memcpy_htod(ptr, data)
def update_params(self, **kwargs):
"""Re-upload d_params after changing runtime-adjustable values.
Accepted keys: omega, fx, fy, fz, n_objects.
"""
self._runtime_params.update({
"omega": float(kwargs.get("omega", self._runtime_params["omega"])),
"fx": float(kwargs.get("fx", self._runtime_params["fx"])),
"fy": float(kwargs.get("fy", self._runtime_params["fy"])),
"fz": float(kwargs.get("fz", self._runtime_params["fz"])),
"n_objects": int(kwargs.get("n_objects", self._runtime_params["n_objects"])),
})
p = self._runtime_params
fmt = "=f fff I"
data = struct.pack(
fmt,
p["omega"],
p["fx"], p["fy"], p["fz"],
p["n_objects"],
)
ptr, _ = self.module.get_global("d_params")
cuda.memcpy_htod(ptr, data)
# -- Host ↔ GPU transfers ------------------------------------------------
def upload_ddf(self):
upload_data = self.ddf
if getattr(self.cfg, 'ddf_shifting', False):
# Host stores physical DDF; GPU stores shifted DDF (f - w).
w = self._read_lattice_weights()
upload_data = upload_data.copy()
ddf_2d = upload_data.reshape(self.nq, -1)
for i in range(self.nq):
ddf_2d[i] -= w[i]
if self.store_bytes == 2:
if self.store_dtype != np.float16:
raise RuntimeError(
"Invalid 2-byte DDF storage dtype; expected float16 for FP16S."
)
buf = (upload_data * 32768.0).astype(self.store_dtype)
cuda.memcpy_htod(self.ddf_gpu, buf)
cuda.memcpy_htod(self.temp_gpu, buf)
else:
cuda.memcpy_htod(self.ddf_gpu, upload_data)
cuda.memcpy_htod(self.temp_gpu, upload_data)
self.invalidate_host_ddf_cache()
# The canonical download_ddf is defined above in the class body.
def upload_flags(self):
cuda.memcpy_htod(self.flag_gpu, self.flag)
def upload_compact_lists(self, stream: Optional[cuda.Stream] = None) -> None:
"""Upload compact lists (curved, sensor, force_region) to GPU.
Also allocates the EsoPull curved intermediate buffer when cut-links exist.
The buffer is a GPU scratch space (no meaningful host data).
"""
self.curved.upload(stream=stream)
self.sensors.upload(stream=stream)
self.force_regions.upload(stream=stream)
# EsoPull curved scratch buffer: sized to n_curved, zero-filled.
n = self.n_curved
if n > 0:
self.esopull_curved.assign_host(
np.zeros(n, dtype=np.float32),
np.zeros(n, dtype=np.uint32),
np.zeros(n, dtype=np.uint8),
)
self.esopull_curved.upload(stream=stream)
# -- Read lattice descriptors from CUDA module ---------------------------
def _read_lattice_vectors(self):
"""Read d_cx, d_cy [, d_cz] from CUDA __constant__ memory."""
if self.cfg.is_d2q9 and self._cached_vectors_2d is not None:
return self._cached_vectors_2d
if self.cfg.is_d3q19 and self._cached_vectors_3d is not None:
return self._cached_vectors_3d
nq = self.nq
cx = np.empty(nq, dtype=np.int32)
cy = np.empty(nq, dtype=np.int32)
ptr_cx, _ = self.module.get_global("d_cx")
ptr_cy, _ = self.module.get_global("d_cy")
cuda.memcpy_dtoh(cx, ptr_cx)
cuda.memcpy_dtoh(cy, ptr_cy)
if self.cfg.is_d3q19:
cz = np.empty(nq, dtype=np.int32)
ptr_cz, _ = self.module.get_global("d_cz")
cuda.memcpy_dtoh(cz, ptr_cz)
self._cached_vectors_3d = (cx, cy, cz)
return self._cached_vectors_3d
self._cached_vectors_2d = (cx, cy)
return self._cached_vectors_2d
# -- Macroscopic field extraction ----------------------------------------
def get_macroscopic(self, *, step_id: int | None = None):
"""Download DDF and compute rho, ux, uy [, uz].
For double_buffer streaming: host-side decode from raw DDF.
For esopull streaming: GPU-side MacroscopicEsoPullKernel.
.. note::
In EsoPull mode, ``get_ddf()`` returns backing-layout raw storage,
NOT physical DDF. Only ``get_macroscopic()`` is semantically correct.
Verified: Kan99b K2 (200k steps, MRT) -- bit-identical to
double-buffer for all metrics (St, mean_CL, mean_CD, amp_CL, amp_CD).
"""
if getattr(self.cfg, 'streaming', 'double_buffer') == 'esopull':
return self.get_macroscopic_esopull(step_id=step_id)
# Double-buffer host path (existing)
self.download_ddf(step_id=step_id)
nq = self.nq
if self.cfg.is_d2q9:
f = self.ddf.reshape(nq, self.ny, self.nx)
rho = np.sum(f, axis=0)
cx, cy = self._read_lattice_vectors()
rho_safe = np.where(np.abs(rho) > 1e-12, rho, 1.0)
ux = sum(f[i] * cx[i] for i in range(nq)) / rho_safe
uy = sum(f[i] * cy[i] for i in range(nq)) / rho_safe
return {"rho": rho, "ux": ux, "uy": uy}
if self.cfg.is_d3q19:
f = self.ddf.reshape(nq, self.nz, self.ny, self.nx)
rho = np.sum(f, axis=0)
cx, cy, cz = self._read_lattice_vectors()
rho_safe = np.where(np.abs(rho) > 1e-12, rho, 1.0)
ux = sum(f[i] * cx[i] for i in range(nq)) / rho_safe
uy = sum(f[i] * cy[i] for i in range(nq)) / rho_safe
uz = sum(f[i] * cz[i] for i in range(nq)) / rho_safe
return {"rho": rho, "ux": ux, "uy": uy, "uz": uz}
raise ValueError(f"Unsupported lattice_model: {self.cfg.lattice_model}")
def get_macroscopic_esopull(self, *, step_id: int | None = None) -> dict:
"""Compute macroscopic field from EsoPull backing layout on GPU.
Launches MacroscopicEsoPullKernel to decode the EsoPull backing layout
into physical rho/ux/uy, then downloads results to host.
.. note::
Only supports D2Q9. D3Q19 raises NotImplementedError.
This is the ONLY correct path for macroscopic diagnostics in EsoPull
mode. Host-side raw DDF download (get_ddf) is NOT physical DDF
when streaming is esopull -- the backing layout scatters paired
directions across neighbor cells.
Verified: Kan99b K2 -- bit-identical to double-buffer.
Args:
step_id: Current step count used for EsoPull parity decoding.
Returns:
dict with keys ``"rho"``, ``"ux"``, ``"uy"`` as 2D arrays.
"""
if not self.cfg.is_d2q9:
raise NotImplementedError(
"MacroscopicEsoPullKernel currently only supports D2Q9.")
fn = self.module.get_function("MacroscopicEsoPullKernel")
tpb = self.cfg.threads_per_block
grid = ((self.nx + tpb - 1) // tpb, self.ny, 1)
t_val = np.uint64(int(step_id) if step_id is not None else 0)
fn(self.ddf_gpu,
self.macro_rho_gpu, self.macro_ux_gpu, self.macro_uy_gpu,
t_val,
block=(tpb, 1, 1), grid=grid)
cuda.memcpy_dtoh(self._macro_rho, self.macro_rho_gpu)
cuda.memcpy_dtoh(self._macro_ux, self.macro_ux_gpu)
cuda.memcpy_dtoh(self._macro_uy, self.macro_uy_gpu)
return {
"rho": self._macro_rho.reshape(self.ny, self.nx),
"ux": self._macro_ux.reshape(self.ny, self.nx),
"uy": self._macro_uy.reshape(self.ny, self.nx),
}
# -- DDF patch for runtime body sync (delegated to body/ddf_patch.py) -----
# patch_ddf_for_body_sync and upload_patched_ddf are imported and called
# directly from Simulation.sync_bodies(). They are no longer methods on
# LBMField.
# -- EsoPull sync decode/encode (compact list) --------------------------
def esopull_sync_decode(self, patch_indices, step_count, stream=None):
"""Decode a subset of cells from EsoPull backing to physical DDF.
Args:
patch_indices: uint32 array of cell indices to decode.
step_count: Current step count (for EsoPull parity).
stream: Optional CUDA stream.
Returns:
(scratch_gpu, scratch_host, idx_gpu): scratch buffer handles.
"""
n = len(patch_indices)
nq = self.nq
scratch_gpu = cuda.mem_alloc(n * nq * 4)
scratch_host = np.empty(n * nq, dtype=np.float32)
idx_gpu = cuda.mem_alloc(n * 4)
cuda.memcpy_htod(idx_gpu, np.asarray(patch_indices, dtype=np.uint32))
fn = self.module.get_function("DecodeCellsToPhysical")
tpb = self.cfg.threads_per_block
fn(self.ddf_gpu, scratch_gpu, idx_gpu, np.uint32(n),
np.uint64(step_count),
block=(tpb, 1, 1), grid=((n + tpb - 1) // tpb, 1, 1),
stream=stream)
cuda.memcpy_dtoh_async(scratch_host, scratch_gpu, stream)
stream.synchronize()
return scratch_gpu, scratch_host, idx_gpu
def esopull_sync_encode(self, scratch_gpu, scratch_host, idx_gpu,
n, step_count, stream=None):
"""Upload patched physical DDF, collide + encode to EsoPull layout.
The backing layout stores post-collision values. This method
applies collision to the patched physical DDF before encoding,
matching the store_f_esopull convention at parity *step_count*.
Frees scratch_gpu and idx_gpu after encoding.
"""
cuda.memcpy_htod_async(scratch_gpu, scratch_host, stream)
fn = self.module.get_function("EncodePhysicalToCells")
tpb = self.cfg.threads_per_block
fn(self.ddf_gpu, scratch_gpu, idx_gpu, np.uint32(n),
np.uint64(step_count),
block=(tpb, 1, 1), grid=((n + tpb - 1) // tpb, 1, 1),
stream=stream)
scratch_gpu.free()
idx_gpu.free()
def snapshot(self):
self.download_ddf(force=True)
self._ddf_snap = self.ddf.copy()
def restore(self):
if self._ddf_snap is None:
raise RuntimeError("No snapshot to restore")
self.ddf = self._ddf_snap.copy()
self.upload_ddf()
+130
View File
@@ -0,0 +1,130 @@
# CelerisLab/lbm/initializers.py
"""
Flow-field initialization helpers (vortex superposition, etc.).
All functions operate on an LBMField — they download DDF, modify on host,
and re-upload. Only 2D D2Q9 vortices implemented for now.
"""
import numpy as np
from scipy.special import jv, expi
from typing import Tuple
import pycuda.driver as cuda
def add_vortex(field, center: Tuple[float, float],
radius: float, strength: float,
vortex_type: str = "lamb"):
"""Superimpose a vortex onto an existing 2D D2Q9 flow field.
Supported types: "lamb", "oseen", "taylor".
"""
if not field.cfg.is_d2q9:
raise NotImplementedError("Vortex init only for D2Q9")
if vortex_type not in ("lamb", "oseen", "taylor"):
raise ValueError(f"Unknown vortex type: {vortex_type}")
nx, ny = field.nx, field.ny
x_c, y_c = center
nu = field.cfg.viscosity
x = np.linspace(-x_c, nx - 1 - x_c, nx)
y = np.linspace(-y_c, ny - 1 - y_c, ny)
X, Y = np.meshgrid(x, y)
r = np.sqrt(X**2 + Y**2)
theta = np.arctan2(Y, X)
if vortex_type == "lamb":
u_vor, v_vor, p_vor = _lamb_vortex(r, theta, radius, strength)
elif vortex_type == "oseen":
u_vor, v_vor, p_vor = _oseen_vortex(r, theta, radius, strength)
else:
u_vor, v_vor, p_vor = _taylor_vortex(r, theta, radius, strength, nu)
# Download current DDF
field.download_ddf()
nq = field.nq
f = field.ddf.reshape(nq, ny, nx)
# Read lattice descriptors from CUDA module (single source of truth)
cx, cy = field._read_lattice_vectors()
w = field._read_lattice_weights()
# Compute current macroscopic from DDF
rho_old = np.sum(f, axis=0)
rho_safe = np.where(np.abs(rho_old) > 1e-12, rho_old, 1.0)
ux_old = sum(f[i] * cx[i] for i in range(nq)) / rho_safe
uy_old = sum(f[i] * cy[i] for i in range(nq)) / rho_safe
p_old = rho_old / 3.0
# Superimpose
# Vortex arrays are (ny, nx); u_vor[j, i] adds to node (i, j)
u_new = ux_old + u_vor
v_new = uy_old + v_vor
p_new = p_old + p_vor
# Reconstruct DDF from new macroscopic (equilibrium)
for j in range(1, ny - 1):
for i in range(1, nx - 1):
u, v, p = float(u_new[j, i]), float(v_new[j, i]), float(p_new[j, i])
for e in range(nq):
eu = cx[e] * u + cy[e] * v
u2 = u * u + v * v
f[e, j, i] = w[e] * (3*p + 3*eu + 4.5*eu*eu - 1.5*u2)
field.ddf = f.reshape(-1)
field.upload_ddf()
# ---------------------------------------------------------------------------
# Vortex models
# ---------------------------------------------------------------------------
def _lamb_vortex(r, theta, radius, strength):
b = 3.831705970207512
n = b / radius
u0 = strength
inside = r <= radius
outside = r > radius
psi = np.zeros_like(r)
psi[inside] = (
(2*u0 / n / jv(0, b) * jv(1, n*r[inside]) - u0*r[inside])
* np.sin(theta[inside])
)
psi[outside] = -u0 * radius**2 / r[outside] * np.sin(theta[outside])
u_vor = np.gradient(psi, axis=0)
v_vor = -np.gradient(psi, axis=1)
p_vor = (
-2*(np.gradient(v_vor, axis=1) - np.gradient(u_vor, axis=0))*psi
- (u_vor**2 + v_vor**2) / 2
)
return u_vor, v_vor, p_vor
def _oseen_vortex(r, theta, radius, strength):
kappa = 2 * np.pi * radius**2 * strength
r_safe = np.where(r > 1e-12, r, 1e-12)
exp_term = 1 - np.exp(-4 * r**2 / radius**2)
u_vor = -kappa / (2*np.pi*r_safe) * exp_term * np.sin(theta)
v_vor = kappa / (2*np.pi*r_safe) * exp_term * np.cos(theta)
zeta = 4 * r**2 / radius**2
p_vor = (
-kappa**2 / (8*np.pi**2 * r_safe**2)
* (-2*zeta*(expi(-zeta) - expi(-2*zeta))
+ (1 - np.exp(-zeta))**2)
)
return u_vor, v_vor, p_vor
def _taylor_vortex(r, theta, radius, strength, nu):
M = strength * np.pi * radius**4 / (8 * nu)
coeff = M * 4 * nu / radius**4
exp_term = np.exp(-r**2 / radius**2)
u_vor = -coeff * r * exp_term * np.sin(theta)
v_vor = coeff * r * exp_term * np.cos(theta)
p_vor = (
-4 * M**2 * nu**2
* np.exp(-2 * r**2 / radius**2)
/ (np.pi**2 * radius**6)
)
return u_vor, v_vor, p_vor
@@ -0,0 +1,143 @@
// CelerisLab – boundary/bounce_back.cuh
// Half-way bounce-back for grid-aligned solid walls (pull-streaming variant).
//
// For wall-adjacent fluid nodes, the pull step loaded garbage from the wall.
// We replace those directions with the opposite-direction population at the
// SAME node from the INPUT buffer (half-way BB).
//
// In EsoPull mode (t > 0), reads via load_physical_dir_esopull to resolve
// the opposite direction's value from the EsoPull single-buffer layout.
// For Kan99b (cylinder far from walls), this is correct in practice.
// A more rigorous pre_streaming fix is pending further investigation.
// ============================================================================
#ifndef CELERIS_BOUNDARY_BOUNCE_BACK_CUH
#define CELERIS_BOUNDARY_BOUNCE_BACK_CUH
// ---------------------------------------------------------------------------
// D2Q9 y-wall half-way bounce-back for pull double-buffer streaming.
// ---------------------------------------------------------------------------
#if LATTICE_MODEL == LATTICE_D2Q9
__device__ inline void apply_wall_bb_d2q9_y_pull(unsigned int y,
float* __restrict__ f,
const fpxx* __restrict__ fi_in,
unsigned long k,
const unsigned long* j = nullptr,
unsigned long t = 0ul)
{
if (y == 1) {
// Directions sourced from y=0 wall in pull step: +y, +x+y, -x+y.
if (t == 0ul) {
f[3] = load_ddf(fi_in, index_f(k, 4u));
f[5] = load_ddf(fi_in, index_f(k, 6u));
f[8] = load_ddf(fi_in, index_f(k, 7u));
} else {
f[3] = load_physical_dir_esopull(k, 4u, fi_in, j, t); // N ← S
f[5] = load_physical_dir_esopull(k, 6u, fi_in, j, t); // NE ← SW
f[8] = load_physical_dir_esopull(k, 7u, fi_in, j, t); // NW ← SE
}
}
else if (y == (unsigned int)(NY - 2)) {
// Directions sourced from y=NY-1 wall in pull step: -y, -x-y, +x-y.
if (t == 0ul) {
f[4] = load_ddf(fi_in, index_f(k, 3u));
f[6] = load_ddf(fi_in, index_f(k, 5u));
f[7] = load_ddf(fi_in, index_f(k, 8u));
} else {
f[4] = load_physical_dir_esopull(k, 3u, fi_in, j, t); // S ← N
f[6] = load_physical_dir_esopull(k, 5u, fi_in, j, t); // SW ← NE
f[7] = load_physical_dir_esopull(k, 8u, fi_in, j, t); // SE ← NW
}
}
}
// ---------------------------------------------------------------------------
// D2Q9 y-wall free-slip (specular reflection) for pull double-buffer streaming.
//
// Normal components use the same mapping as half-way BB at horizontal walls:
// (0,+1) <-> (0,-1)
// Tangential components mirror across wall normal:
// (+1,+1) <-> (+1,-1), (-1,+1) <-> (-1,-1)
// ---------------------------------------------------------------------------
__device__ inline void apply_wall_freeslip_d2q9_y_pull(unsigned int y,
float* __restrict__ f,
const fpxx* __restrict__ fi_in,
unsigned long k,
const unsigned long* j = nullptr,
unsigned long t = 0ul)
{
if (y == 1) {
if (t == 0ul) {
f[3] = load_ddf(fi_in, index_f(k, 4u));
f[5] = load_ddf(fi_in, index_f(k, 7u));
f[8] = load_ddf(fi_in, index_f(k, 6u));
} else {
f[3] = load_physical_dir_esopull(k, 4u, fi_in, j, t); // N ← S (normal)
f[5] = load_physical_dir_esopull(k, 7u, fi_in, j, t); // NE ← SE (tangential mirror)
f[8] = load_physical_dir_esopull(k, 6u, fi_in, j, t); // NW ← SW (tangential mirror)
}
}
else if (y == (unsigned int)(NY - 2)) {
if (t == 0ul) {
f[4] = load_ddf(fi_in, index_f(k, 3u));
f[6] = load_ddf(fi_in, index_f(k, 8u));
f[7] = load_ddf(fi_in, index_f(k, 5u));
} else {
f[4] = load_physical_dir_esopull(k, 3u, fi_in, j, t); // S ← N (normal)
f[6] = load_physical_dir_esopull(k, 8u, fi_in, j, t); // SW ← NW (tangential mirror)
f[7] = load_physical_dir_esopull(k, 5u, fi_in, j, t); // SE ← NE (tangential mirror)
}
}
}
#endif
// ---------------------------------------------------------------------------
// D3Q19 y-wall half-way bounce-back for pull double-buffer streaming.
//
// Instead of swapping f[i] <-> f[opp(i)] (which corrupts the toward-wall
// direction with garbage from the wall node), we read the opposite direction
// at the SAME node from the INPUT buffer. That value is the post-collision
// population from the previous time step — exactly the correct half-way BB.
//
// At y=1 (wall at y=0): directions that arrive FROM y=0 have cy_src = -1.
// The pull loaded them from the wall (garbage). Replace with fi_in[k, opp].
//
// At y=NY-2 (wall at y=NY-1): directions from y=NY-1, cy_src = +1.
// ---------------------------------------------------------------------------
#if LATTICE_MODEL == LATTICE_D3Q19
__device__ inline void apply_wall_bb_d3q19_y_pull(unsigned int y,
float* __restrict__ f,
const fpxx* __restrict__ fi_in,
unsigned long k)
{
if (y == 1) {
// Directions whose pull-source is at y=0 (wall):
// f[3] (+y) ← source j[4] = (x, 0, z)
// f[7] (+x+y) ← source j[8] = (x-1, 0, z)
// f[11] (+y+z) ← source j[12] = (x, 0, z-1)
// f[14] (-x+y) ← source j[13] = (x+1, 0, z)
// f[17] (+y-z) ← source j[18] = (x, 0, z+1)
f[3] = load_ddf(fi_in, index_f(k, 4u));
f[7] = load_ddf(fi_in, index_f(k, 8u));
f[11] = load_ddf(fi_in, index_f(k, 12u));
f[14] = load_ddf(fi_in, index_f(k, 13u));
f[17] = load_ddf(fi_in, index_f(k, 18u));
}
else if (y == (unsigned int)(NY - 2)) {
// Directions whose pull-source is at y=NY-1 (wall):
// f[4] (-y) ← source j[3] = (x, NY-1, z)
// f[8] (-x-y) ← source j[7] = (x+1, NY-1, z)
// f[12] (-y-z) ← source j[11] = (x, NY-1, z+1)
// f[13] (+x-y) ← source j[14] = (x-1, NY-1, z)
// f[18] (-y+z) ← source j[17] = (x, NY-1, z-1)
f[4] = load_ddf(fi_in, index_f(k, 3u));
f[8] = load_ddf(fi_in, index_f(k, 7u));
f[12] = load_ddf(fi_in, index_f(k, 11u));
f[13] = load_ddf(fi_in, index_f(k, 14u));
f[18] = load_ddf(fi_in, index_f(k, 17u));
}
}
#endif
#endif // CELERIS_BOUNDARY_BOUNCE_BACK_CUH
@@ -0,0 +1,201 @@
// CelerisLab – boundary/curved_boundary.cuh
// Bouzidi linear interpolated bounce-back for curved surfaces.
//
// Pull-streaming contract used here:
// before the main pull step, each cut-link thread computes the reflected
// population and writes it into the adjacent solid source node. The pull load
// from the neighboring solid node then receives the corrected value in the
// same time step. This avoids colliding fluid nodes with garbage populations
// pulled from obstacle interiors.
//
// References:
// [Bou01] Bouzidi, Firdaouss & Lallemand, Phys. Fluids 13(11), 2001
// [Mei99] Mei, Luo & Shyy, J. Comput. Phys. 155(2), 1999
// [Gin08b] Ginzburg, Verhaeghe & d'Humieres, Commun. Comput. Phys. 2008
// [Wen15] Wen, Zhang & Fang, Entropy 17(12), 2015 (MEA force)
//
// Note on TRT:
// Plain linear Bouzidi interpolation is kept here because it is simple and
// useful for SRT and MRT baselines and for moving simple geometries.
// However, it is not a TRT-parametrized curved-wall family. Expect TRT to be
// more sensitive here than with CLI, MGLI, or other TRT-consistent schemes.
// ============================================================================
#ifndef CELERIS_BOUNDARY_CURVED_BOUNDARY_CUH
#define CELERIS_BOUNDARY_CURVED_BOUNDARY_CUH
constexpr unsigned char CURVED_FALLBACK_BOUZIDI = 0u;
constexpr unsigned char CURVED_FALLBACK_HALFWAY = 1u;
// ---------------------------------------------------------------------------
// Bouzidi linear interpolation and moving-wall correction (pure math helpers)
// ---------------------------------------------------------------------------
__device__ __forceinline__ float compute_bouzidi_reflection(
float f_toward, float f_toward_ff, float f_opp_same,
float q, unsigned char fallback_class)
{
if (fallback_class != CURVED_FALLBACK_BOUZIDI)
return f_toward;
if (q < 0.5f)
return 2.0f * q * f_toward + (1.0f - 2.0f * q) * f_toward_ff;
return (1.0f / (2.0f * q)) * f_toward +
(1.0f - 1.0f / (2.0f * q)) * f_opp_same;
}
__device__ __forceinline__ float bouzidi_linear_moving_correction(
float q, unsigned char fallback_class, float alpha_ci_dot_uw)
{
if (fallback_class != CURVED_FALLBACK_BOUZIDI) {
// Fallback replaces the q < 1/2 branch when its donor is illegal.
// For D2Q9, alpha_i = 3 w_i, so the moving-wall addend is
// +2 * alpha_i * (c_i . u_w) in the q < 1/2 branch.
return 2.0f * alpha_ci_dot_uw;
}
if (q < 0.5f) {
return 2.0f * alpha_ci_dot_uw;
}
return (alpha_ci_dot_uw / q);
}
__device__ __forceinline__ float compute_moving_wall_addend(
unsigned int dir, float q, unsigned char fallback_class,
float Uw, float Vw)
{
#if DIM == 2
const float ci_dot_uw = (float)d_cx[dir] * Uw + (float)d_cy[dir] * Vw;
#elif DIM == 3
const float ci_dot_uw = (float)d_cx[dir] * Uw + (float)d_cy[dir] * Vw + (float)d_cz[dir] * 0.0f;
#endif
const float alpha_ci_dot_uw = 3.0f * d_w[dir] * ci_dot_uw;
return bouzidi_linear_moving_correction(q, fallback_class, alpha_ci_dot_uw);
}
// ---------------------------------------------------------------------------
// D2Q9: apply Bouzidi boundary condition for one cut-link (double-buffer path)
// ---------------------------------------------------------------------------
#if DIM == 2
__device__ inline void apply_bouzidi_link(
unsigned int dir, float q, unsigned long k_f,
fpxx* __restrict__ fi,
float Uw, float Vw,
float rx, float ry,
unsigned char fallback_class,
float* __restrict__ obs, int body_id)
{
const unsigned int dir_opp = (unsigned int)opp_dir((int)dir);
unsigned int xf, yf;
coordinates(k_f, xf, yf);
const int xs = (int)xf + d_cx[dir];
const int ys = (int)yf + d_cy[dir];
const unsigned long k_s = linear_index((unsigned int)xs, (unsigned int)ys);
const float f_toward = load_ddf(fi, index_f(k_f, dir));
float f_reflected;
if (fallback_class == CURVED_FALLBACK_BOUZIDI) {
if (q < 0.5f) {
const int xff = (int)xf - d_cx[dir];
const int yff = (int)yf - d_cy[dir];
const unsigned long k_ff = linear_index((unsigned int)xff, (unsigned int)yff);
const float f_toward_ff = load_ddf(fi, index_f(k_ff, dir));
f_reflected = compute_bouzidi_reflection(f_toward, f_toward_ff, 0.0f, q, fallback_class);
} else {
const float f_opp_same = load_ddf(fi, index_f(k_f, dir_opp));
f_reflected = compute_bouzidi_reflection(f_toward, 0.0f, f_opp_same, q, fallback_class);
}
} else {
f_reflected = compute_bouzidi_reflection(f_toward, 0.0f, 0.0f, q, fallback_class);
}
f_reflected += compute_moving_wall_addend(dir, q, fallback_class, Uw, Vw);
// Write to the solid source node so the subsequent pull step loads the
// corrected incoming population into the adjacent fluid node.
store_ddf(fi, index_f(k_s, dir_opp), f_reflected);
if (obs != nullptr) {
#if USE_DDF_SHIFTING
const float w_i = (float)d_w[dir];
const float fx = (float)d_cx[dir] * ((f_toward + w_i) + (f_reflected + w_i));
const float fy = (float)d_cy[dir] * ((f_toward + w_i) + (f_reflected + w_i));
#else
const float fx = (float)d_cx[dir] * (f_toward + f_reflected);
const float fy = (float)d_cy[dir] * (f_toward + f_reflected);
#endif
atomicAdd(&obs[obs_force_index(body_id, 0)], fx);
atomicAdd(&obs[obs_force_index(body_id, 1)], fy);
const float tz = rx * fy - ry * fx;
atomicAdd(&obs[obs_torque_index(body_id, 0)], tz);
}
}
#endif // DIM == 2
// ---------------------------------------------------------------------------
// D3Q19: apply Bouzidi boundary condition for one cut-link (double-buffer path)
// ---------------------------------------------------------------------------
#if DIM == 3
__device__ inline void apply_bouzidi_link(
unsigned int dir, float q, unsigned long k_f,
fpxx* __restrict__ fi,
float Uw, float Vw, float Ww,
float rx, float ry, float rz,
unsigned char fallback_class,
float* __restrict__ obs, int body_id)
{
const unsigned int dir_opp = (unsigned int)opp_dir((int)dir);
unsigned int xf, yf, zf;
coordinates(k_f, xf, yf, zf);
const int xs = (int)xf + d_cx[dir];
const int ys = (int)yf + d_cy[dir];
const int zs = (int)zf + d_cz[dir];
const unsigned long k_s = linear_index((unsigned int)xs, (unsigned int)ys, (unsigned int)zs);
const float f_toward = load_ddf(fi, index_f(k_f, dir));
float f_reflected;
if (fallback_class == CURVED_FALLBACK_BOUZIDI) {
if (q < 0.5f) {
const int xff = (int)xf - d_cx[dir];
const int yff = (int)yf - d_cy[dir];
const int zff = (int)zf - d_cz[dir];
const unsigned long k_ff = linear_index((unsigned int)xff, (unsigned int)yff, (unsigned int)zff);
const float f_toward_ff = load_ddf(fi, index_f(k_ff, dir));
f_reflected = compute_bouzidi_reflection(f_toward, f_toward_ff, 0.0f, q, fallback_class);
} else {
const float f_opp_same = load_ddf(fi, index_f(k_f, dir_opp));
f_reflected = compute_bouzidi_reflection(f_toward, 0.0f, f_opp_same, q, fallback_class);
}
} else {
f_reflected = compute_bouzidi_reflection(f_toward, 0.0f, 0.0f, q, fallback_class);
}
f_reflected += compute_moving_wall_addend(dir, q, fallback_class, Uw, Vw);
store_ddf(fi, index_f(k_s, dir_opp), f_reflected);
if (obs != nullptr) {
#if USE_DDF_SHIFTING
const float w_i = (float)d_w[dir];
const float fx = (float)d_cx[dir] * ((f_toward + w_i) + (f_reflected + w_i));
const float fy = (float)d_cy[dir] * ((f_toward + w_i) + (f_reflected + w_i));
const float fz = (float)d_cz[dir] * ((f_toward + w_i) + (f_reflected + w_i));
#else
const float fx = (float)d_cx[dir] * (f_toward + f_reflected);
const float fy = (float)d_cy[dir] * (f_toward + f_reflected);
const float fz = (float)d_cz[dir] * (f_toward + f_reflected);
#endif
atomicAdd(&obs[obs_force_index(body_id, 0)], fx);
atomicAdd(&obs[obs_force_index(body_id, 1)], fy);
atomicAdd(&obs[obs_force_index(body_id, 2)], fz);
const float tx = ry * fz - rz * fy;
const float ty = rz * fx - rx * fz;
const float tz = rx * fy - ry * fx;
atomicAdd(&obs[obs_torque_index(body_id, 0)], tx);
atomicAdd(&obs[obs_torque_index(body_id, 1)], ty);
atomicAdd(&obs[obs_torque_index(body_id, 2)], tz);
}
}
#endif // DIM == 3
#endif // CELERIS_BOUNDARY_CURVED_BOUNDARY_CUH
@@ -0,0 +1,24 @@
// CelerisLab -- boundary/esopull_curved_helpers.cuh
// Curved-specific EsoPull helpers (target address resolution).
//
// The base semantic helpers (esopull_slot, esopull_src_cell,
// load_physical_dir_esopull et al.) are in streaming/esopull_semantic_helpers.cuh.
// ============================================================================
#ifndef CELERIS_BOUNDARY_ESOPULL_CURVED_HELPERS_CUH
#define CELERIS_BOUNDARY_ESOPULL_CURVED_HELPERS_CUH
#include "../streaming/esopull_semantic_helpers.cuh"
// Compute the cell and slot that the reflected population should be written to.
// For EsoPull, this depends on the cut-link direction parity and current timestep.
__device__ __forceinline__ void resolve_esopull_target(
unsigned long k_f, unsigned long k_s,
unsigned int dir, unsigned long t,
unsigned long& target_cell, unsigned int& target_slot)
{
target_cell = (dir & 1u) ? k_s : k_f;
target_slot = (t & 1ul) ? (unsigned int)opp_dir((int)dir) : dir;
}
#endif // CELERIS_BOUNDARY_ESOPULL_CURVED_HELPERS_CUH
@@ -0,0 +1,185 @@
// CelerisLab – boundary/ibm_kernels.cuh
// Peskin IBM (Immersed Boundary Method) kernels: Euler↔Lagrangian coupling.
//
// STATUS: FUTURE PATH — not yet wired into stepper.py or ObjectManager.
// The current production boundary path is Bouzidi curved BC (curved_boundary.cuh
// + CurvedBoundaryKernel). This file is kept for the planned multi-body /
// soft-body IBM extension where a continuous Lagrangian surface is preferred
// over discrete cut-links.
//
// To activate:
// 1. Add IBM body type to objects.py with get_lagrangian_list().
// 2. Wire update_lagrangian_control → euler_to_lagrangian → lagrangian_to_euler
// into stepper.py after the main step kernel.
// 3. Integrate forceE into the Guo forcing path (forcing_guo.cuh).
//
// Peskin 4-point delta function for interpolation/spreading [Peskin 2002].
//
// Data layout (per rigid body):
// RigidBodyState2D: {x, y, theta, vx, vy, omega}
// Lagrangian points: motionL[NT_LAG * 4]
// motionL[4*k + 0] = target vx at point k
// motionL[4*k + 1] = target vy at point k
// motionL[4*k + 2] = XL (x-position)
// motionL[4*k + 3] = YL (y-position)
// forceL[NT_LAG * 2] = Lagrangian force (fx, fy) per point
// ============================================================================
#ifndef CELERIS_BOUNDARY_IBM_KERNELS_CUH
#define CELERIS_BOUNDARY_IBM_KERNELS_CUH
#include "../core/params.cuh" // RigidBodyState2D, RigidBodyControl2D
// IBM is currently 2D only. Guard all kernels.
#if DIM == 2
// ---------------------------------------------------------------------------
// Peskin 4-point delta function (1D component)
// ---------------------------------------------------------------------------
__device__ __forceinline__ float peskin_delta_1d(float r) {
float ar = fabsf(r);
if (ar < 1.0f)
return 0.125f * (3.0f - 2.0f * ar + sqrtf(1.0f + 4.0f * ar - 4.0f * ar * ar));
else if (ar < 2.0f)
return 0.125f * (5.0f - 2.0f * ar - sqrtf(-7.0f + 12.0f * ar - 4.0f * ar * ar));
else
return 0.0f;
}
// ---------------------------------------------------------------------------
// Peskin 4-point delta function (2D = product of 1D components)
// ---------------------------------------------------------------------------
__device__ __forceinline__ float peskin_delta_2d(float dx, float dy) {
return peskin_delta_1d(dx) * peskin_delta_1d(dy);
}
// ---------------------------------------------------------------------------
// update_lagrangian_control:
// Update Lagrangian point positions using RigidBodyState2D.
// Supports circular body (points on circumference).
//
// Thread k ∈ [0, NT_LAG) — one thread per Lagrangian point.
// ---------------------------------------------------------------------------
__global__ void update_lagrangian_control(
float* __restrict__ motionL, // [NT_LAG * 4]
const RigidBodyState2D* state, // single rigid body state
float radius, // body radius
int NT_LAG) // number of Lagrangian points
{
int k = threadIdx.x + blockIdx.x * blockDim.x;
if (k >= NT_LAG) return;
float angle = state->theta + (float)k * 2.0f * 3.14159265358979323846f / (float)NT_LAG;
// Target velocity at this Lagrangian point (rigid-body kinematics)
float r_sin = radius * sinf(angle);
float r_cos = radius * cosf(angle);
motionL[4 * k + 0] = state->vx - state->omega * r_sin; // target vx
motionL[4 * k + 1] = state->vy + state->omega * r_cos; // target vy
motionL[4 * k + 2] = state->x + r_cos; // XL
motionL[4 * k + 3] = state->y + r_sin; // YL
}
// ---------------------------------------------------------------------------
// euler_to_lagrangian (Eul2Lag):
// Interpolate Eulerian velocity to Lagrangian points.
// Compute Lagrangian force = penalty * (target_vel - interpolated_vel) * dL.
//
// Thread k ∈ [0, NT_LAG)
// ---------------------------------------------------------------------------
__global__ void euler_to_lagrangian(
float* __restrict__ forceL, // [NT_LAG * 2] output forces
const float* __restrict__ motionL, // [NT_LAG * 4]
const float* __restrict__ u_field, // [DIM * N] SoA velocity field
int NT_LAG)
{
int k = threadIdx.x + blockIdx.x * blockDim.x;
if (k >= NT_LAG) return;
float XL = motionL[4 * k + 2];
float YL = motionL[4 * k + 3];
int ix = (int)XL;
int iy = (int)YL;
// Arc-length element dL (central difference)
float dL;
if (k > 0 && k < NT_LAG - 1) {
float dx1 = motionL[4*k+2] - motionL[4*(k-1)+2];
float dy1 = motionL[4*k+3] - motionL[4*(k-1)+3];
float dx2 = motionL[4*(k+1)+2] - motionL[4*k+2];
float dy2 = motionL[4*(k+1)+3] - motionL[4*k+3];
dL = 0.5f * (sqrtf(dx1*dx1 + dy1*dy1) + sqrtf(dx2*dx2 + dy2*dy2));
} else if (k == 0) {
float dx1 = motionL[4*1+2] - motionL[4*0+2];
float dy1 = motionL[4*1+3] - motionL[4*0+3];
dL = sqrtf(dx1*dx1 + dy1*dy1);
} else {
float dx1 = motionL[4*k+2] - motionL[4*(k-1)+2];
float dy1 = motionL[4*k+3] - motionL[4*(k-1)+3];
dL = sqrtf(dx1*dx1 + dy1*dy1);
}
// Interpolate velocity from Euler grid using Peskin 4-point delta
float UL = 0.0f, VL = 0.0f;
for (int dy = -2; dy <= 2; dy++) {
for (int dx = -2; dx <= 2; dx++) {
int ex = ix + dx;
int ey = iy + dy;
if (ex < 0 || ex >= NX || ey < 0 || ey >= NY) continue;
float ww = peskin_delta_2d((float)ex - XL, (float)ey - YL);
unsigned long en = (unsigned long)ey * NX + (unsigned long)ex;
UL += u_field[en] * ww; // ux
VL += u_field[TOTAL_CELLS + en] * ww; // uy
}
}
// Force = (target_vel - interpolated_vel) * dL
forceL[2 * k + 0] = 2.0f * (motionL[4*k+0] - UL) * dL; // fx
forceL[2 * k + 1] = 2.0f * (motionL[4*k+1] - VL) * dL; // fy
}
// ---------------------------------------------------------------------------
// lagrangian_to_euler (Lag2Eul):
// Spread Lagrangian forces back to the Eulerian grid.
//
// Thread (x, y) — one thread per Euler node.
// Only processes nodes near the body (bounding box check).
// ---------------------------------------------------------------------------
__global__ void lagrangian_to_euler(
float* __restrict__ forceE, // [DIM * N] output Euler force field
const float* __restrict__ forceL, // [NT_LAG * 2]
const float* __restrict__ motionL, // [NT_LAG * 4]
float xc, float yc, float L0, // body center and extent
int NT_LAG)
{
unsigned int x, y;
unsigned long k;
#if DIM == 2
index_from_thread(x, y, k);
#endif
if (x >= (unsigned int)NX || y >= (unsigned int)NY) return;
// Bounding box check
if ((float)x < xc - L0 || (float)x > xc + L0 ||
(float)y < yc - L0 || (float)y > yc + L0) return;
float forcex = 0.0f, forcey = 0.0f;
for (int kl = 0; kl < NT_LAG; kl++) {
float XL = motionL[4 * kl + 2];
float YL = motionL[4 * kl + 3];
float ww = peskin_delta_2d((float)x - XL, (float)y - YL);
forcex += forceL[2 * kl + 0] * ww;
forcey += forceL[2 * kl + 1] * ww;
}
forceE[k] = forcex;
forceE[TOTAL_CELLS + k] = forcey;
}
#endif // DIM == 2
#endif // CELERIS_BOUNDARY_IBM_KERNELS_CUH
@@ -0,0 +1,110 @@
// CelerisLab – boundary/inlet/channel_stabilized.cuh
// Donor-based west velocity inlet closures designed for robust ghost-source use.
// ============================================================================
#ifndef CELERIS_BOUNDARY_INLET_CHANNEL_STABILIZED_CUH
#define CELERIS_BOUNDARY_INLET_CHANNEL_STABILIZED_CUH
#if LATTICE_MODEL == LATTICE_D2Q9
__device__ inline void apply_channel_stabilized_inlet_d2q9(
float* __restrict__ f,
const float* __restrict__ f_neb,
float y_coord)
{
float rho_neb, u_neb, v_neb;
compute_rho_u(f_neb, rho_neb, u_neb, v_neb);
const float u_target = inlet_target_u(y_coord);
const float v_target = 0.0f;
const float rho_in = west_velocity_rho_closure_d2q9(f, u_target);
float feq_tar[9], feq_neb[9];
compute_feq(rho_in, u_target, v_target, feq_tar);
compute_feq(rho_neb, u_neb, v_neb, feq_neb);
#if COLLISION_MODEL == 1
const float beta_n = INLET_TRT_NEQ_DAMP;
#else
const float beta_n = 1.0f;
#endif
const float f1_try = feq_tar[1] + beta_n * (f_neb[1] - feq_neb[1]);
const float known_sum = f[0] + f[2] + f[3] + f[4] + f[6] + f[8];
float pair_diff = rho_in * v_target + (f[4] - f[3]) + (f[6] - f[8]);
const float f1_hi = fmaxf(0.0f, rho_in - known_sum - fabsf(pair_diff));
const float f1 = fminf(fmaxf(f1_try, 0.0f), f1_hi);
float pair_sum = rho_in - known_sum - f1;
if (fabsf(pair_diff) > pair_sum) {
pair_diff = copysignf(pair_sum, pair_diff);
}
f[1] = f1;
f[5] = 0.5f * (pair_sum + pair_diff);
f[7] = 0.5f * (pair_sum - pair_diff);
}
#endif
#if LATTICE_MODEL == LATTICE_D3Q19
__device__ inline void apply_channel_stabilized_inlet_d3q19(
float* __restrict__ f,
const float* __restrict__ f_neb,
float y_coord)
{
float rho_neb, un, vn, wn;
compute_rho_u(f_neb, rho_neb, un, vn, wn);
const float u_tar = inlet_target_u(y_coord);
const float v_tar = 0.0f;
const float w_tar = 0.0f;
const float rho_in = west_velocity_rho_closure_d3q19(f, u_tar);
float feq_tar[19], feq_neb[19];
compute_feq(rho_in, u_tar, v_tar, w_tar, feq_tar);
compute_feq(rho_neb, un, vn, wn, feq_neb);
#if COLLISION_MODEL == 1
const float beta_n = INLET_TRT_NEQ_DAMP;
#else
const float beta_n = 1.0f;
#endif
const float f1_try = feq_tar[1] + beta_n * (f_neb[1] - feq_neb[1]);
const float zsum_try = (feq_tar[9] + feq_tar[15])
+ beta_n * ((f_neb[9] - feq_neb[9])
+ (f_neb[15] - feq_neb[15]));
const float known_sum = f[0] + f[2] + f[3] + f[4] + f[5] + f[6]
+ f[8] + f[10] + f[11] + f[12] + f[14]
+ f[16] + f[17] + f[18];
const float rem_total = rho_in - known_sum;
float y_diff = rho_in * v_tar
- (f[3] - f[4] - f[8] + f[11] - f[12] + f[14] + f[17] - f[18]);
float z_diff = rho_in * w_tar
- (f[5] - f[6] - f[10] + f[11] - f[12] + f[16] + f[18] - f[17]);
const float f1_hi = fmaxf(0.0f, rem_total - fabsf(y_diff));
const float f1 = fminf(fmaxf(f1_try, 0.0f), f1_hi);
const float zsum_hi = fmaxf(0.0f, rem_total - f1 - fabsf(y_diff));
const float z_sum = fminf(fmaxf(zsum_try, 0.0f), zsum_hi);
if (fabsf(z_diff) > z_sum) {
z_diff = copysignf(z_sum, z_diff);
}
float y_sum = rem_total - f1 - z_sum;
y_sum = fmaxf(y_sum, 0.0f);
if (fabsf(y_diff) > y_sum) {
y_diff = copysignf(y_sum, y_diff);
}
f[1] = f1;
f[9] = 0.5f * (z_sum + z_diff);
f[15] = 0.5f * (z_sum - z_diff);
f[7] = 0.5f * (y_sum + y_diff);
f[13] = 0.5f * (y_sum - y_diff);
}
#endif
#endif // CELERIS_BOUNDARY_INLET_CHANNEL_STABILIZED_CUH
@@ -0,0 +1,86 @@
// CelerisLab – boundary/inlet/common.cuh
// Shared helpers for west velocity inlet source-state generation.
//
// Important semantic contract in this solver:
// - x=0 inlet cells are SOLID|BC_INLET ghost source nodes
// - they generate the state later pulled by the first interior fluid column
// - inlet methods therefore construct a source state, not a textbook fluid-node
// boundary update in isolation
// ============================================================================
#ifndef CELERIS_BOUNDARY_INLET_COMMON_CUH
#define CELERIS_BOUNDARY_INLET_COMMON_CUH
#ifndef INLET_PROFILE
#define INLET_PROFILE 1
#endif
#ifndef INLET_SCHEME
#define INLET_SCHEME 0
#endif
#ifndef INLET_TRT_NEQ_DAMP
#define INLET_TRT_NEQ_DAMP 0.50f
#endif
#ifndef INLET_REGULARIZED_NEQ_DAMP
#define INLET_REGULARIZED_NEQ_DAMP 0.50f
#endif
__device__ __forceinline__ float inlet_target_u(float y_coord) {
#if INLET_PROFILE == 0
return U0;
#else
const float y_clamped = fminf((float)(NY - 2), fmaxf(1.0f, y_coord));
const float H = fmaxf((float)(NY - 2), 1.0f);
const float eta = (y_clamped - 0.5f) / H;
const float shape = fmaxf(0.0f, 4.0f * eta * (1.0f - eta));
return U0 * 1.5f * shape;
#endif
}
#if LATTICE_MODEL == LATTICE_D2Q9
__device__ __forceinline__ float west_velocity_rho_closure_d2q9(
const float* __restrict__ f,
float ux_target)
{
float rho_num = f[0] + f[3] + f[4] + 2.0f * (f[2] + f[6] + f[8]);
#if USE_DDF_SHIFTING
// f[i] = physical_f[i] - w[i]; restore the sum of weights for
// the directions appearing in the numerator (w[0]=4/9, w[3]=w[4]=1/9,
// w[2]=w[6]=w[8]=1/36, with f[2],f[6],f[8] double-counted):
// sum(w) = 4/9 + 1/9 + 1/9 + 2*(1/36+1/36+1/36) = 6/9 + 6/36 = 5/6
rho_num += 5.0f / 6.0f;
#endif
return rho_num / (1.0f - ux_target);
}
#endif
#if LATTICE_MODEL == LATTICE_D3Q19
__device__ __forceinline__ float west_velocity_rho_closure_d3q19(
const float* __restrict__ f,
float ux_target)
{
float rho_num = f[0] + f[3] + f[4] + f[5] + f[6] + f[11] + f[12] + f[17] + f[18]
+ 2.0f * (f[2] + f[8] + f[10] + f[14] + f[16]);
#if USE_DDF_SHIFTING
// f[i] = physical_f[i] - w[i]; restore the sum of weights for
// the directions appearing in the numerator (w[0]=1/3, w[3..6,11,12,17,18]=1/18,
// w[2,8,10,14,16]=1/36 double-counted):
// sum(w) = 1/3 + 8*(1/18) + 5*(2/36) = 12/36 + 16/36 + 10/36 = 38/36 = 19/18
rho_num += 19.0f / 18.0f;
#endif
return rho_num / (1.0f - ux_target);
}
#endif
__device__ __forceinline__ bool inlet_scheme_uses_post_collision_ghost()
{
#if INLET_SCHEME == 0
return true;
#else
return false;
#endif
}
#endif // CELERIS_BOUNDARY_INLET_COMMON_CUH
@@ -0,0 +1,48 @@
// CelerisLab – boundary/inlet/equilibrium.cuh
// West velocity inlet source state built from full equilibrium.
//
// This method recovers rho from local west-boundary mass closure and then
// overwrites the full ghost-node state with feq(rho, u_target).
// It is robust for ghost-source architectures because it injects no boundary
// non-equilibrium content.
// ============================================================================
#ifndef CELERIS_BOUNDARY_INLET_EQUILIBRIUM_CUH
#define CELERIS_BOUNDARY_INLET_EQUILIBRIUM_CUH
#if LATTICE_MODEL == LATTICE_D2Q9
__device__ inline void apply_equilibrium_left_velocity_inlet_d2q9(
float* __restrict__ f,
float ux_target,
float uy_target)
{
const float rho = west_velocity_rho_closure_d2q9(f, ux_target);
float feq[9];
compute_feq(rho, ux_target, uy_target, feq);
#pragma unroll
for (int i = 0; i < 9; i++) {
f[i] = feq[i];
}
}
#endif
#if LATTICE_MODEL == LATTICE_D3Q19
__device__ inline void apply_equilibrium_left_velocity_inlet_d3q19(
float* __restrict__ f,
float ux_target,
float uy_target,
float uz_target)
{
const float rho = west_velocity_rho_closure_d3q19(f, ux_target);
float feq[19];
compute_feq(rho, ux_target, uy_target, uz_target, feq);
#pragma unroll
for (int i = 0; i < 19; i++) {
f[i] = feq[i];
}
}
#endif
#endif // CELERIS_BOUNDARY_INLET_EQUILIBRIUM_CUH
@@ -0,0 +1,70 @@
// CelerisLab – boundary/inlet/regularized.cuh
// West velocity inlet with local macro state and donor-damped incoming NEQ.
//
// This method keeps the target macro state from local west-boundary closure but
// avoids a full local algebraic source state by injecting only damped donor NEQ
// on incoming directions.
//
// COMPATIBILITY NOTE (ddf_shifting):
// Formula: f[1] = feq_tar[1] + beta * (f_neb[1] - feq_neb[1])
// f_neb comes from load_ddf / load_f_esopull (shifted when USE_DDF_SHIFTING=1).
// feq_tar / feq_neb come from compute_feq (also shifted when USE_DDF_SHIFTING=1).
// The NEQ term (f_neb - feq_neb) cancels weights pairwise --> self-consistent.
//
// CURRENT STATUS: Verified self-consistent for SRT/TRT. MRT + shifting +
// regularized inlet shows suppressed vortex shedding -- root cause not yet
// fully isolated (may involve inlet NEQ interaction with unshifted MRT interior).
// Use zou_he_local inlet when combining MRT + ddf_shifting.
// ============================================================================
#ifndef CELERIS_BOUNDARY_INLET_REGULARIZED_CUH
#define CELERIS_BOUNDARY_INLET_REGULARIZED_CUH
#if LATTICE_MODEL == LATTICE_D2Q9
__device__ inline void apply_regularized_left_velocity_inlet_d2q9(
float* __restrict__ f,
const float* __restrict__ f_neb,
float ux_target,
float uy_target)
{
const float rho = west_velocity_rho_closure_d2q9(f, ux_target);
float rho_neb, u_neb, v_neb;
compute_rho_u(f_neb, rho_neb, u_neb, v_neb);
float feq_tar[9], feq_neb[9];
compute_feq(rho, ux_target, uy_target, feq_tar);
compute_feq(rho_neb, u_neb, v_neb, feq_neb);
const float beta = INLET_REGULARIZED_NEQ_DAMP;
f[1] = feq_tar[1] + beta * (f_neb[1] - feq_neb[1]);
f[5] = feq_tar[5] + beta * (f_neb[5] - feq_neb[5]);
f[7] = feq_tar[7] + beta * (f_neb[7] - feq_neb[7]);
}
#endif
#if LATTICE_MODEL == LATTICE_D3Q19
__device__ inline void apply_regularized_left_velocity_inlet_d3q19(
float* __restrict__ f,
const float* __restrict__ f_neb,
float ux_target,
float uy_target,
float uz_target)
{
const float rho = west_velocity_rho_closure_d3q19(f, ux_target);
float rho_neb, u_neb, v_neb, w_neb;
compute_rho_u(f_neb, rho_neb, u_neb, v_neb, w_neb);
float feq_tar[19], feq_neb[19];
compute_feq(rho, ux_target, uy_target, uz_target, feq_tar);
compute_feq(rho_neb, u_neb, v_neb, w_neb, feq_neb);
const float beta = INLET_REGULARIZED_NEQ_DAMP;
f[1] = feq_tar[1] + beta * (f_neb[1] - feq_neb[1]);
f[7] = feq_tar[7] + beta * (f_neb[7] - feq_neb[7]);
f[9] = feq_tar[9] + beta * (f_neb[9] - feq_neb[9]);
f[13] = feq_tar[13] + beta * (f_neb[13] - feq_neb[13]);
f[15] = feq_tar[15] + beta * (f_neb[15] - feq_neb[15]);
}
#endif
#endif // CELERIS_BOUNDARY_INLET_REGULARIZED_CUH
@@ -0,0 +1,107 @@
// CelerisLab – boundary/inlet/zou_he_local.cuh
// Local on-site west velocity inlet closures.
//
// D2Q9 and D3Q19 variants recover rho from local mass closure and reconstruct
// unknown incoming populations from local target velocity constraints.
//
// In the current ghost-source architecture these reconstructed states are later
// used as pull sources. Therefore this method requires post-BC ghost collision
// in the step kernel.
// ============================================================================
#ifndef CELERIS_BOUNDARY_INLET_ZOU_HE_LOCAL_CUH
#define CELERIS_BOUNDARY_INLET_ZOU_HE_LOCAL_CUH
#if LATTICE_MODEL == LATTICE_D2Q9
// Free-slip y-walls: at inlet rows y=1 and y=NY-2, pull can source wall nodes for
// some known directions. Copy those from stored DDF at (x=1, same y) only.
//
// NOTE: This helper is not Zou-He-specific. All west inlet schemes that use
// west_velocity_rho_closure_d2q9() need clean known-direction values. The
// free-slip wall interferes with these at the top/bottom inlet corners.
// The legacy name is kept for now (not renamed yet).
__device__ inline void repair_zou_he_west_knowns_d2q9(
float* __restrict__ f,
const fpxx* __restrict__ fi_in,
unsigned int x,
unsigned int y,
const unsigned long* j_neb = nullptr,
unsigned long t = 0ul)
{
if (x != 0u) return;
const unsigned long k_int = linear_index(x + 1u, y);
if (y == 1u) {
if (t == 0ul || j_neb == nullptr) {
f[3] = load_ddf(fi_in, index_f(k_int, 3u));
f[8] = load_ddf(fi_in, index_f(k_int, 8u));
} else {
f[3] = load_physical_dir_pre_streaming(k_int, 3u, fi_in, j_neb, t);
f[8] = load_physical_dir_pre_streaming(k_int, 8u, fi_in, j_neb, t);
}
} else if (y == (unsigned int)(NY - 2)) {
if (t == 0ul || j_neb == nullptr) {
f[4] = load_ddf(fi_in, index_f(k_int, 4u));
f[6] = load_ddf(fi_in, index_f(k_int, 6u));
} else {
f[4] = load_physical_dir_pre_streaming(k_int, 4u, fi_in, j_neb, t);
f[6] = load_physical_dir_pre_streaming(k_int, 6u, fi_in, j_neb, t);
}
}
}
__device__ inline void apply_zou_he_left_velocity_inlet_d2q9(
float* __restrict__ f,
float ux_target,
float uy_target)
{
const float rho = west_velocity_rho_closure_d2q9(f, ux_target);
f[1] = f[2] + (2.0f / 3.0f) * rho * ux_target;
f[5] = f[6]
+ 0.5f * (f[4] - f[3])
+ (1.0f / 6.0f) * rho * ux_target
+ 0.5f * rho * uy_target;
f[7] = f[8]
+ 0.5f * (f[3] - f[4])
+ (1.0f / 6.0f) * rho * ux_target
- 0.5f * rho * uy_target;
}
#endif // LATTICE_MODEL == LATTICE_D2Q9
#if LATTICE_MODEL == LATTICE_D3Q19
// Hecht-Harting style D3Q19 on-site west velocity closure adapted to the
// codebase paired ordering:
// 7 = (+x,+y), 8 = (-x,-y)
// 13 = (+x,-y), 14 = (-x,+y)
// 9 = (+x,+z), 10 = (-x,-z)
// 15 = (+x,-z), 16 = (-x,+z)
__device__ inline void apply_zou_he_left_velocity_inlet_d3q19(
float* __restrict__ f,
float ux_target,
float uy_target,
float uz_target)
{
const float rho = west_velocity_rho_closure_d3q19(f, ux_target);
const float Nyx = 0.5f * (f[3] + f[11] + f[17] - (f[4] + f[12] + f[18]))
- (1.0f / 3.0f) * rho * uy_target;
const float Nzx = 0.5f * (f[5] + f[11] + f[18] - (f[6] + f[17] + f[12]))
- (1.0f / 3.0f) * rho * uz_target;
f[1] = f[2] + (1.0f / 3.0f) * rho * ux_target;
f[7] = f[8] + (1.0f / 6.0f) * rho * (ux_target + uy_target) - Nyx;
f[13] = f[14] + (1.0f / 6.0f) * rho * (ux_target - uy_target) + Nyx;
f[9] = f[10] + (1.0f / 6.0f) * rho * (ux_target + uz_target) - Nzx;
f[15] = f[16] + (1.0f / 6.0f) * rho * (ux_target - uz_target) + Nzx;
}
#endif // LATTICE_MODEL == LATTICE_D3Q19
#endif // CELERIS_BOUNDARY_INLET_ZOU_HE_LOCAL_CUH
@@ -0,0 +1,235 @@
// CelerisLab – boundary/inlet_outlet.cuh
// Inlet and outlet dispatch layer.
//
// This file contains only profile helpers, method includes, and compile-time
// switching. Each concrete inlet or outlet implementation lives in its own file
// under boundary/inlet/ or boundary/outlet/.
//
// Inlet scheme IDs:
// 0 = zou_he_local
// 1 = channel_stabilized
// 2 = equilibrium
// 3 = regularized
// ============================================================================
#ifndef CELERIS_BOUNDARY_INLET_OUTLET_CUH
#define CELERIS_BOUNDARY_INLET_OUTLET_CUH
#ifndef INLET_SCHEME
#define INLET_SCHEME 0
#endif
#include "inlet/common.cuh"
#include "inlet/zou_he_local.cuh"
#include "inlet/channel_stabilized.cuh"
#include "inlet/equilibrium.cuh"
#include "inlet/regularized.cuh"
#include "outlet/pressure_neq.cuh"
#if DIM == 2
__device__ __forceinline__ void apply_inlet_pull_d2q9(
float* __restrict__ f,
unsigned int x,
unsigned int y,
const fpxx* __restrict__ fi_in)
{
const float u_target = inlet_target_u((float)y);
const float v_target = 0.0f;
// Free-slip y-walls: repair west inlet ghost-node known directions
// that may have been polluted by wall source populations.
// Required by all schemes using west_velocity_rho_closure_d2q9().
#if Y_WALL_BC == 1
repair_zou_he_west_knowns_d2q9(f, fi_in, x, y);
#endif
#if INLET_SCHEME == 0
apply_zou_he_left_velocity_inlet_d2q9(f, u_target, v_target);
#elif INLET_SCHEME == 1 || INLET_SCHEME == 3
float f_neb[NQ];
const unsigned long k_neb = linear_index(x + 1u, y);
for (int i = 0; i < NQ; i++) {
f_neb[i] = load_ddf(fi_in, index_f(k_neb, (unsigned int)i));
}
#if INLET_SCHEME == 1
apply_channel_stabilized_inlet_d2q9(f, f_neb, (float)y);
#else
apply_regularized_left_velocity_inlet_d2q9(f, f_neb, u_target, v_target);
#endif
#elif INLET_SCHEME == 2
apply_equilibrium_left_velocity_inlet_d2q9(f, u_target, v_target);
#else
#error "Unsupported INLET_SCHEME for D2Q9"
#endif
}
__device__ __forceinline__ void apply_outlet_pull_d2q9(
float* __restrict__ f,
unsigned int x,
unsigned int y,
const fpxx* __restrict__ fi_in)
{
float f_neb[NQ];
const unsigned long k_neb = linear_index(x - 1u, y);
for (int i = 0; i < NQ; i++) {
f_neb[i] = load_ddf(fi_in, index_f(k_neb, (unsigned int)i));
}
apply_pressure_outlet_d2q9(f, f_neb);
}
#endif
#if DIM == 3
__device__ __forceinline__ void apply_inlet_pull_d3q19(
float* __restrict__ f,
unsigned int x,
unsigned int y,
unsigned int z,
const fpxx* __restrict__ fi_in)
{
const float u_target = inlet_target_u((float)y);
const float v_target = 0.0f;
const float w_target = 0.0f;
#if INLET_SCHEME == 0
apply_zou_he_left_velocity_inlet_d3q19(f, u_target, v_target, w_target);
#elif INLET_SCHEME == 1 || INLET_SCHEME == 3
float f_neb[NQ];
const unsigned long k_neb = linear_index(x + 1u, y, z);
for (int i = 0; i < NQ; i++) {
f_neb[i] = load_ddf(fi_in, index_f(k_neb, (unsigned int)i));
}
#if INLET_SCHEME == 1
apply_channel_stabilized_inlet_d3q19(f, f_neb, (float)y);
#else
apply_regularized_left_velocity_inlet_d3q19(f, f_neb, u_target, v_target, w_target);
#endif
#elif INLET_SCHEME == 2
apply_equilibrium_left_velocity_inlet_d3q19(f, u_target, v_target, w_target);
#else
#error "Unsupported INLET_SCHEME for D3Q19"
#endif
}
__device__ __forceinline__ void apply_outlet_pull_d3q19(
float* __restrict__ f,
unsigned int x,
unsigned int y,
unsigned int z,
const fpxx* __restrict__ fi_in)
{
float f_neb[NQ];
const unsigned long k_neb = linear_index(x - 1u, y, z);
for (int i = 0; i < NQ; i++) {
f_neb[i] = load_ddf(fi_in, index_f(k_neb, (unsigned int)i));
}
apply_pressure_outlet_d3q19(f, f_neb);
}
#endif
#if DIM == 2
__device__ __forceinline__ void apply_inlet_esopull_d2q9(
float* __restrict__ f,
unsigned int x,
unsigned int y,
const fpxx* __restrict__ fi,
unsigned long t)
{
const float u_target = inlet_target_u((float)y);
const float v_target = 0.0f;
// Free-slip y-walls: repair west inlet ghost-node known directions.
#if Y_WALL_BC == 1
{
unsigned long j_neb[NQ];
compute_neighbors(x + 1u, y, j_neb);
repair_zou_he_west_knowns_d2q9(f, fi, x, y, j_neb, t);
}
#endif
#if INLET_SCHEME == 0
apply_zou_he_left_velocity_inlet_d2q9(f, u_target, v_target);
#elif INLET_SCHEME == 1 || INLET_SCHEME == 3
const unsigned long k_neb = linear_index(x + 1u, y);
unsigned long j_neb[NQ];
compute_neighbors(x + 1u, y, j_neb);
float f_neb[NQ];
load_f_esopull(k_neb, f_neb, fi, j_neb, t);
#if INLET_SCHEME == 1
apply_channel_stabilized_inlet_d2q9(f, f_neb, (float)y);
#else
apply_regularized_left_velocity_inlet_d2q9(f, f_neb, u_target, v_target);
#endif
#elif INLET_SCHEME == 2
apply_equilibrium_left_velocity_inlet_d2q9(f, u_target, v_target);
#else
#error "Unsupported INLET_SCHEME for D2Q9"
#endif
}
__device__ __forceinline__ void apply_outlet_esopull_d2q9(
float* __restrict__ f,
unsigned int x,
unsigned int y,
const fpxx* __restrict__ fi,
unsigned long t)
{
const unsigned long k_neb = linear_index(x - 1u, y);
unsigned long j_neb[NQ];
compute_neighbors(x - 1u, y, j_neb);
float f_neb[NQ];
load_f_esopull(k_neb, f_neb, fi, j_neb, t);
apply_pressure_outlet_d2q9(f, f_neb);
}
#endif
#if DIM == 3
__device__ __forceinline__ void apply_inlet_esopull_d3q19(
float* __restrict__ f,
unsigned int x,
unsigned int y,
unsigned int z,
const fpxx* __restrict__ fi,
unsigned long t)
{
const float u_target = inlet_target_u((float)y);
const float v_target = 0.0f;
const float w_target = 0.0f;
#if INLET_SCHEME == 0
apply_zou_he_left_velocity_inlet_d3q19(f, u_target, v_target, w_target);
#elif INLET_SCHEME == 1 || INLET_SCHEME == 3
const unsigned long k_neb = linear_index(x + 1u, y, z);
unsigned long j_neb[NQ];
compute_neighbors(k_neb, j_neb);
float f_neb[NQ];
load_f_esopull(k_neb, f_neb, fi, j_neb, t);
#if INLET_SCHEME == 1
apply_channel_stabilized_inlet_d3q19(f, f_neb, (float)y);
#else
apply_regularized_left_velocity_inlet_d3q19(f, f_neb, u_target, v_target, w_target);
#endif
#elif INLET_SCHEME == 2
apply_equilibrium_left_velocity_inlet_d3q19(f, u_target, v_target, w_target);
#else
#error "Unsupported INLET_SCHEME for D3Q19"
#endif
}
__device__ __forceinline__ void apply_outlet_esopull_d3q19(
float* __restrict__ f,
unsigned int x,
unsigned int y,
unsigned int z,
const fpxx* __restrict__ fi,
unsigned long t)
{
const unsigned long k_neb = linear_index(x - 1u, y, z);
unsigned long j_neb[NQ];
compute_neighbors(k_neb, j_neb);
float f_neb[NQ];
load_f_esopull(k_neb, f_neb, fi, j_neb, t);
apply_pressure_outlet_d3q19(f, f_neb);
}
#endif
#endif // CELERIS_BOUNDARY_INLET_OUTLET_CUH
@@ -0,0 +1,114 @@
// CelerisLab – boundary/outlet/pressure_neq.cuh
// Pressure outlet and zero-gradient outlet closures.
// ============================================================================
#ifndef CELERIS_BOUNDARY_OUTLET_PRESSURE_NEQ_CUH
#define CELERIS_BOUNDARY_OUTLET_PRESSURE_NEQ_CUH
#ifndef OUTLET_MODE
#define OUTLET_MODE 0
#endif
#ifndef OUTLET_BACKFLOW_CLAMP
#define OUTLET_BACKFLOW_CLAMP 1
#endif
#ifndef OUTLET_BLEND_ALPHA
#define OUTLET_BLEND_ALPHA 0.70f
#endif
#ifndef OUTLET_SRT_NEQ_DAMP
#define OUTLET_SRT_NEQ_DAMP 0.50f
#endif
#if LATTICE_MODEL == LATTICE_D2Q9
__device__ inline void apply_pressure_outlet_d2q9(
float* __restrict__ f,
const float* __restrict__ f_neb)
{
#if OUTLET_MODE == 1
f[2] = f_neb[2];
f[8] = f_neb[8];
f[6] = f_neb[6];
#else
float rho_neb, u_neb, v_neb;
compute_rho_u(f_neb, rho_neb, u_neb, v_neb);
#if OUTLET_BACKFLOW_CLAMP
u_neb = fmaxf(u_neb, 0.0f);
#endif
const float rho_out = RHO;
float feq_tar[9], feq_neb[9];
compute_feq(rho_out, u_neb, v_neb, feq_tar);
compute_feq(rho_neb, u_neb, v_neb, feq_neb);
#if COLLISION_MODEL == 0 || COLLISION_MODEL == 1
const float beta = OUTLET_SRT_NEQ_DAMP;
#pragma unroll
for (int i = 0; i < 9; i++) {
const float fneq = f_neb[i] - feq_neb[i];
f[i] = feq_tar[i] + beta * fneq;
}
#elif OUTLET_MODE == 2
const float a = OUTLET_BLEND_ALPHA;
f[2] = a * (f_neb[2] - feq_neb[2] + feq_tar[2]) + (1.0f - a) * f_neb[2];
f[8] = a * (f_neb[8] - feq_neb[8] + feq_tar[8]) + (1.0f - a) * f_neb[8];
f[6] = a * (f_neb[6] - feq_neb[6] + feq_tar[6]) + (1.0f - a) * f_neb[6];
#else
f[2] = f_neb[2] - feq_neb[2] + feq_tar[2];
f[8] = f_neb[8] - feq_neb[8] + feq_tar[8];
f[6] = f_neb[6] - feq_neb[6] + feq_tar[6];
#endif
#endif
}
#endif
#if LATTICE_MODEL == LATTICE_D3Q19
__device__ inline void apply_pressure_outlet_d3q19(
float* __restrict__ f,
const float* __restrict__ f_neb)
{
#if OUTLET_MODE == 1
f[2] = f_neb[2];
f[8] = f_neb[8];
f[10] = f_neb[10];
f[14] = f_neb[14];
f[16] = f_neb[16];
#else
float rho_neb, un, vn, wn;
compute_rho_u(f_neb, rho_neb, un, vn, wn);
#if OUTLET_BACKFLOW_CLAMP
un = fmaxf(un, 0.0f);
#endif
const float rho_out = RHO;
float feq_tar[19], feq_neb[19];
compute_feq(rho_out, un, vn, wn, feq_tar);
compute_feq(rho_neb, un, vn, wn, feq_neb);
#if COLLISION_MODEL == 0 || COLLISION_MODEL == 1
const float beta = OUTLET_SRT_NEQ_DAMP;
#pragma unroll
for (int i = 0; i < 19; i++) {
const float fneq = f_neb[i] - feq_neb[i];
f[i] = feq_tar[i] + beta * fneq;
}
#elif OUTLET_MODE == 2
const float a = OUTLET_BLEND_ALPHA;
f[2] = a * (f_neb[2] - feq_neb[2] + feq_tar[2]) + (1.0f - a) * f_neb[2];
f[8] = a * (f_neb[8] - feq_neb[8] + feq_tar[8]) + (1.0f - a) * f_neb[8];
f[10] = a * (f_neb[10] - feq_neb[10] + feq_tar[10]) + (1.0f - a) * f_neb[10];
f[14] = a * (f_neb[14] - feq_neb[14] + feq_tar[14]) + (1.0f - a) * f_neb[14];
f[16] = a * (f_neb[16] - feq_neb[16] + feq_tar[16]) + (1.0f - a) * f_neb[16];
#else
f[2] = f_neb[2] - feq_neb[2] + feq_tar[2];
f[8] = f_neb[8] - feq_neb[8] + feq_tar[8];
f[10] = f_neb[10] - feq_neb[10] + feq_tar[10];
f[14] = f_neb[14] - feq_neb[14] + feq_tar[14];
f[16] = f_neb[16] - feq_neb[16] + feq_tar[16];
#endif
#endif
}
#endif
#endif // CELERIS_BOUNDARY_OUTLET_PRESSURE_NEQ_CUH
+19
View File
@@ -0,0 +1,19 @@
// CelerisLab – config.h
// ============================================================================
// Top-level configuration aggregator.
// Includes all layer-specific config headers generated by compiler.py.
//
// Users: read these files to see current parameters; do NOT edit them.
// Modify the JSON config and re-run the Python build step instead.
// ============================================================================
#ifndef CELERIS_CONFIG_H
#define CELERIS_CONFIG_H
#include "config/config_grid.h"
#include "config/config_physics.h"
#include "config/config_method.h"
#include "config/config_objects.h"
#include "config/config_obs.h"
#endif // CELERIS_CONFIG_H
@@ -0,0 +1,31 @@
// AUTO-GENERATED by CelerisLab compiler – DO NOT EDIT MANUALLY
// Layer: Global / Grid
#ifndef CELERIS_CONFIG_GRID_H
#define CELERIS_CONFIG_GRID_H
#define NT 256
#define MULT_GPU 0
#define NX 1351
#define NY 601
#define NZ 1
// ---- Lattice model (single source of truth) ----
// Model IDs: 0=D2Q9, 1=D3Q19 (extend here for future models like D2Q19)
#define LATTICE_D2Q9 0
#define LATTICE_D3Q19 1
#define LATTICE_MODEL 0
// DIM and NQ are derived from LATTICE_MODEL — do NOT set independently.
#if LATTICE_MODEL == LATTICE_D2Q9
#define DIM 2
#define NQ 9
#elif LATTICE_MODEL == LATTICE_D3Q19
#define DIM 3
#define NQ 19
#else
#error "Unknown LATTICE_MODEL. Supported: LATTICE_D2Q9 (0), LATTICE_D3Q19 (1)."
#endif
#endif
@@ -0,0 +1,34 @@
// AUTO-GENERATED by CelerisLab compiler – DO NOT EDIT MANUALLY
// Layer: Method
#ifndef CELERIS_CONFIG_METHOD_H
#define CELERIS_CONFIG_METHOD_H
#define COLLISION_MODEL 2
#define STREAMING_MODEL 1
#define STORE_PRECISION 0
#define USE_DDF_SHIFTING 0
#define USE_LES 0
#define LES_CS 0.160000f
#define LES_CLOSED_FORM 1
#define INLET_PROFILE 0
#define INLET_SCHEME 3
#define OUTLET_MODE 0
#define OUTLET_BLEND_ALPHA 0.700f
#define OUTLET_BACKFLOW_CLAMP 1
#define Y_WALL_BC 1
#define OMEGA_COLLISION_MIN 0.01f
#define OMEGA_COLLISION_MAX 1.990f
#define TRT_MAGIC_PARAM 0.187500f
// NEQ damping coefficients for inlet/outlet BC reconstruction.
// TRT inlet: donor damping used by the channel_stabilized inlet.
// Regularized inlet: damping on incoming-direction donor NEQ.
// SRT outlet: damped outlet reconstruction to suppress checkerboard noise.
#define INLET_TRT_NEQ_DAMP 0.5000f
#define INLET_REGULARIZED_NEQ_DAMP 0.5000f
#define OUTLET_SRT_NEQ_DAMP 0.5000f
#endif
@@ -0,0 +1,8 @@
// AUTO-GENERATED by CelerisLab compiler – DO NOT EDIT MANUALLY
// Layer: Case / Objects
#ifndef CELERIS_CONFIG_OBJECTS_H
#define CELERIS_CONFIG_OBJECTS_H
#define N_OBJS 1
#endif
@@ -0,0 +1,30 @@
// AUTO-GENERATED by CelerisLab compiler – DO NOT EDIT MANUALLY
// Layer: Case / Objects — packed obs (force + torque + sensor), float indices not bytes
// Derived from N_OBJS (config_objects.h) and DIM (config_grid.h); include via config.h.
#ifndef CELERIS_CONFIG_OBS_H
#define CELERIS_CONFIG_OBS_H
#if (N_OBJS) >= 1
#define OBS_N_SLOTS (N_OBJS)
#else
#define OBS_N_SLOTS 1
#endif
#define OBS_SLOT_STRIDE_FLOATS ((OBS_N_SLOTS) * (DIM))
#define OBS_FORCE_FLOATS (OBS_SLOT_STRIDE_FLOATS)
#if DIM == 2
#define OBS_TORQUE_COMPONENTS 1
#else
#define OBS_TORQUE_COMPONENTS (DIM)
#endif
#define OBS_TORQUE_FLOATS ((OBS_N_SLOTS) * (OBS_TORQUE_COMPONENTS))
#define OBS_BODY_SLOT_FLOATS (3 * (DIM))
#define OBS_FORCE0_FLOATS 0
#define OBS_TORQUE0_FLOATS (OBS_FORCE0_FLOATS + OBS_FORCE_FLOATS)
#define OBS_SENSOR0_FLOATS (OBS_TORQUE0_FLOATS + OBS_TORQUE_FLOATS)
#define OBS_TOTAL_FLOATS (OBS_SENSOR0_FLOATS + OBS_SLOT_STRIDE_FLOATS)
#endif
@@ -0,0 +1,18 @@
// AUTO-GENERATED by CelerisLab compiler – DO NOT EDIT MANUALLY
// Layer: Global / Physics
#ifndef CELERIS_CONFIG_PHYSICS_H
#define CELERIS_CONFIG_PHYSICS_H
#define LBtype float
#define VIS 0.0090000000
#define RHO 1.0
#define U0 0.03
#define PI 3.141592653589793238
// Flag constants are defined in core/flags.cuh (uint16_t).
// Do NOT redefine them here.
#define V_TAYLOR 1
#endif
@@ -0,0 +1,75 @@
// CelerisLab – core/descriptors.cuh
// Lattice descriptor constants.
// Direction ordering: paired for Esoteric-Pull compatibility.
// i=0 rest; for i>=1, (i, i^1|1) are opposite pairs:
// opp(0) = 0
// opp(i) = ((i-1) ^ 1) + 1 for i >= 1
//
// D2Q9 : (0)rest (1,2)±x (3,4)±y (5,6)±(x+y) (7,8)±(x-y)
// D3Q19: (0)rest (1,2)±x (3,4)±y (5,6)±z
// (7,8)±(x+y) (9,10)±(x+z) (11,12)±(y+z)
// (13,14)±(x-y) (15,16)±(x-z) (17,18)±(y-z)
// ============================================================================
#ifndef CELERIS_CORE_DESCRIPTORS_CUH
#define CELERIS_CORE_DESCRIPTORS_CUH
// NQ, DIM, LATTICE_MODEL come from config_grid.h (included before this header)
// ---------------------------------------------------------------------------
// D2Q9
// ---------------------------------------------------------------------------
#if LATTICE_MODEL == LATTICE_D2Q9
__constant__ int d_cx[9] = { 0, 1, -1, 0, 0, 1, -1, 1, -1};
__constant__ int d_cy[9] = { 0, 0, 0, 1, -1, 1, -1, -1, 1};
__constant__ float d_w[9] = {
4.0f/9.0f,
1.0f/9.0f, 1.0f/9.0f, 1.0f/9.0f, 1.0f/9.0f,
1.0f/36.0f, 1.0f/36.0f, 1.0f/36.0f, 1.0f/36.0f
};
// Named weight macros (avoid __constant__ reads in hot paths)
#define W0_VAL (4.0f/9.0f)
#define WS_VAL (1.0f/9.0f)
#define WE_VAL (1.0f/36.0f)
// ---------------------------------------------------------------------------
// D3Q19
// ---------------------------------------------------------------------------
#elif LATTICE_MODEL == LATTICE_D3Q19
__constant__ int d_cx[19] = { 0, 1,-1, 0, 0, 0, 0, 1,-1, 1,-1, 0, 0, 1,-1, 1,-1, 0, 0};
__constant__ int d_cy[19] = { 0, 0, 0, 1,-1, 0, 0, 1,-1, 0, 0, 1,-1, -1, 1, 0, 0, 1,-1};
__constant__ int d_cz[19] = { 0, 0, 0, 0, 0, 1,-1, 0, 0, 1,-1, 1,-1, 0, 0, -1, 1, -1, 1};
__constant__ float d_w[19] = {
1.0f/3.0f,
1.0f/18.0f, 1.0f/18.0f, 1.0f/18.0f, 1.0f/18.0f, 1.0f/18.0f, 1.0f/18.0f,
1.0f/36.0f, 1.0f/36.0f, 1.0f/36.0f, 1.0f/36.0f, 1.0f/36.0f, 1.0f/36.0f,
1.0f/36.0f, 1.0f/36.0f, 1.0f/36.0f, 1.0f/36.0f, 1.0f/36.0f, 1.0f/36.0f
};
#define W0_VAL (1.0f/3.0f)
#define WS_VAL (1.0f/18.0f)
#define WE_VAL (1.0f/36.0f)
#else
#error "Unsupported LATTICE_MODEL. Check config_grid.h."
#endif
// ---------------------------------------------------------------------------
// Lattice sound speed
// ---------------------------------------------------------------------------
#define CS2 (1.0f / 3.0f)
#define CS2_INV (3.0f)
// ---------------------------------------------------------------------------
// Opposite direction (works for any paired-ordered lattice)
// ---------------------------------------------------------------------------
__device__ __forceinline__ int opp_dir(int i) {
return (i == 0) ? 0 : (((i - 1) ^ 1) + 1);
}
#endif // CELERIS_CORE_DESCRIPTORS_CUH
+85
View File
@@ -0,0 +1,85 @@
// CelerisLab – core/flags.cuh
// Cell flag definitions – uint16_t, three-field layout.
//
// [15:8] Extension (SENSOR, OBSTACLE, HALO, …)
// [ 7:4] BC subtype (WALL, INLET, OUTLET, CURVED, PERIODIC, MOVING)
// [ 3:0] Cell type (FLUID, SOLID, GAS, INTERFACE)
//
// DIM and NQ are independent: a future D2Q5 or D3Q27 needs only new
// descriptors, not new flag bits.
// ============================================================================
#ifndef CELERIS_CORE_FLAGS_CUH
#define CELERIS_CORE_FLAGS_CUH
#include <stdint.h>
// ---------------------------------------------------------------------------
// Cell type [3:0]
// ---------------------------------------------------------------------------
#define FLAG_FLUID ((uint16_t)0x0001)
#define FLAG_SOLID ((uint16_t)0x0002)
#define FLAG_GAS ((uint16_t)0x0004)
#define FLAG_INTERFACE ((uint16_t)0x0008)
// ---------------------------------------------------------------------------
// BC subtype [7:4]
// ---------------------------------------------------------------------------
#define FLAG_BC_NONE ((uint16_t)0x0000)
#define FLAG_BC_WALL ((uint16_t)0x0010)
#define FLAG_BC_INLET ((uint16_t)0x0020)
#define FLAG_BC_OUTLET ((uint16_t)0x0030)
#define FLAG_BC_CURVED ((uint16_t)0x0040)
#define FLAG_BC_PERIODIC ((uint16_t)0x0050)
#define FLAG_BC_MOVING ((uint16_t)0x0060)
// ---------------------------------------------------------------------------
// Extension [15:8]
// ---------------------------------------------------------------------------
#define FLAG_SENSOR ((uint16_t)0x0100)
#define FLAG_OBSTACLE ((uint16_t)0x0200)
#define FLAG_HALO ((uint16_t)0x0400)
#define FLAG_FRC_REGION ((uint16_t)0x0800)
// 0x1000..0x8000 reserved for multi-GPU / AMR / multi-phase
// ---------------------------------------------------------------------------
// Masks
// ---------------------------------------------------------------------------
#define MASK_CELL_TYPE ((uint16_t)0x000F)
#define MASK_BC_TYPE ((uint16_t)0x00F0)
#define MASK_EXTENSION ((uint16_t)0xFF00)
// ---------------------------------------------------------------------------
// Device helper: extract fields
// ---------------------------------------------------------------------------
__device__ __forceinline__ uint16_t cell_type(uint16_t fl) { return fl & MASK_CELL_TYPE; }
__device__ __forceinline__ uint16_t bc_type(uint16_t fl) { return fl & MASK_BC_TYPE; }
__device__ __forceinline__ uint16_t ext_bits(uint16_t fl) { return fl & MASK_EXTENSION; }
// ---------------------------------------------------------------------------
// Device helper: cell type queries
// ---------------------------------------------------------------------------
__device__ __forceinline__ bool is_fluid(uint16_t fl) { return (fl & FLAG_FLUID) != 0; }
__device__ __forceinline__ bool is_solid(uint16_t fl) { return (fl & FLAG_SOLID) != 0; }
__device__ __forceinline__ bool is_gas(uint16_t fl) { return (fl & FLAG_GAS) != 0; }
__device__ __forceinline__ bool is_interface(uint16_t fl) { return (fl & FLAG_INTERFACE) != 0; }
// ---------------------------------------------------------------------------
// Device helper: BC queries
// ---------------------------------------------------------------------------
__device__ __forceinline__ bool is_wall(uint16_t fl) { return bc_type(fl) == FLAG_BC_WALL; }
__device__ __forceinline__ bool is_inlet(uint16_t fl) { return bc_type(fl) == FLAG_BC_INLET; }
__device__ __forceinline__ bool is_outlet(uint16_t fl) { return bc_type(fl) == FLAG_BC_OUTLET; }
__device__ __forceinline__ bool is_curved(uint16_t fl) { return bc_type(fl) == FLAG_BC_CURVED; }
__device__ __forceinline__ bool is_moving(uint16_t fl) { return bc_type(fl) == FLAG_BC_MOVING; }
__device__ __forceinline__ bool has_bc(uint16_t fl) { return (fl & MASK_BC_TYPE) != 0; }
// ---------------------------------------------------------------------------
// Device helper: extension queries
// ---------------------------------------------------------------------------
__device__ __forceinline__ bool is_sensor(uint16_t fl) { return (fl & FLAG_SENSOR) != 0; }
__device__ __forceinline__ bool is_obstacle(uint16_t fl) { return (fl & FLAG_OBSTACLE) != 0; }
__device__ __forceinline__ bool is_halo(uint16_t fl) { return (fl & FLAG_HALO) != 0; }
__device__ __forceinline__ bool is_force_region(uint16_t fl) { return (fl & FLAG_FRC_REGION) != 0; }
#endif // CELERIS_CORE_FLAGS_CUH
+178
View File
@@ -0,0 +1,178 @@
// CelerisLab – core/layout.cuh
// SoA memory layout: index_f, coordinates, and neighbor computation.
// Depends on: LATTICE_MODEL, NQ, NX, NY, NZ from config_grid.h; descriptors.cuh for d_cx/d_cy.
// ============================================================================
#ifndef CELERIS_CORE_LAYOUT_CUH
#define CELERIS_CORE_LAYOUT_CUH
// ---------------------------------------------------------------------------
// Total cell count (compile-time)
// ---------------------------------------------------------------------------
#define TOTAL_CELLS ((unsigned long)(NX) * (unsigned long)(NY) * (unsigned long)(NZ))
// ---------------------------------------------------------------------------
// SoA index: fi[ direction * N + node ] ("Q-major")
// ---------------------------------------------------------------------------
__device__ __forceinline__ unsigned long index_f(unsigned long n, unsigned int i) {
return (unsigned long)i * TOTAL_CELLS + n;
}
// ---------------------------------------------------------------------------
// SoA index for DIM-component field: u[ component * N + node ]
// ---------------------------------------------------------------------------
__device__ __forceinline__ unsigned long index_u(unsigned long n, unsigned int d) {
return (unsigned long)d * TOTAL_CELLS + n;
}
// ---------------------------------------------------------------------------
// 2D linear index → (x, y) and (x, y) → linear
// ---------------------------------------------------------------------------
#if DIM == 2
__device__ __forceinline__ void coordinates(unsigned long n,
unsigned int& x,
unsigned int& y)
{
x = (unsigned int)(n % NX);
y = (unsigned int)(n / NX);
}
__device__ __forceinline__ unsigned long linear_index(unsigned int x,
unsigned int y)
{
return (unsigned long)y * NX + x;
}
__device__ __forceinline__ void index_from_thread(unsigned int& x,
unsigned int& y,
unsigned long& k)
{
x = threadIdx.x + NT * blockIdx.x;
y = blockIdx.y;
k = (unsigned long)y * NX + x;
}
// ---------------------------------------------------------------------------
// Neighbor list (periodic BCs via modular arithmetic)
// ---------------------------------------------------------------------------
__device__ inline void compute_neighbors(unsigned long n, unsigned long* j) {
unsigned int x, y;
coordinates(n, x, y);
unsigned int xp = (x + 1u) % NX;
unsigned int xm = (x + NX - 1u) % NX;
unsigned int yp = (y + 1u) % NY;
unsigned int ym = (y + NY - 1u) % NY;
// i=0: self
j[0] = n;
#if LATTICE_MODEL == LATTICE_D2Q9
// paired: (1,2)±x (3,4)±y (5,6)±(x+y) (7,8)±(x-y)
j[1] = linear_index(xp, y ); // +x
j[2] = linear_index(xm, y ); // -x
j[3] = linear_index(x , yp); // +y
j[4] = linear_index(x , ym); // -y
j[5] = linear_index(xp, yp); // +x +y
j[6] = linear_index(xm, ym); // -x -y
j[7] = linear_index(xp, ym); // +x -y
j[8] = linear_index(xm, yp); // -x +y
#else
#error "2D compute_neighbors only supports LATTICE_D2Q9."
#endif
}
// Overload: skip coordinates() when x,y already known (saves ~40 cycles)
__device__ inline void compute_neighbors(unsigned int x, unsigned int y,
unsigned long* j) {
unsigned int xp = (x + 1u) % NX;
unsigned int xm = (x + NX - 1u) % NX;
unsigned int yp = (y + 1u) % NY;
unsigned int ym = (y + NY - 1u) % NY;
j[0] = linear_index(x, y);
#if LATTICE_MODEL == LATTICE_D2Q9
j[1] = linear_index(xp, y );
j[2] = linear_index(xm, y );
j[3] = linear_index(x , yp);
j[4] = linear_index(x , ym);
j[5] = linear_index(xp, yp);
j[6] = linear_index(xm, ym);
j[7] = linear_index(xp, ym);
j[8] = linear_index(xm, yp);
#else
#error "2D compute_neighbors only supports LATTICE_D2Q9."
#endif
}
#elif DIM == 3
__device__ __forceinline__ void coordinates(unsigned long n,
unsigned int& x,
unsigned int& y,
unsigned int& z)
{
x = (unsigned int)(n % NX);
y = (unsigned int)(n / NX % NY);
z = (unsigned int)(n / ((unsigned long)NX * NY));
}
__device__ __forceinline__ unsigned long linear_index(unsigned int x,
unsigned int y,
unsigned int z)
{
return (unsigned long)z * NY * NX + (unsigned long)y * NX + x;
}
__device__ __forceinline__ void index_from_thread(unsigned int& x,
unsigned int& y,
unsigned int& z,
unsigned long& k)
{
x = threadIdx.x + NT * blockIdx.x;
y = blockIdx.y;
z = blockIdx.z;
k = linear_index(x, y, z);
}
__device__ inline void compute_neighbors(unsigned long n, unsigned long* j) {
unsigned int x, y, z;
coordinates(n, x, y, z);
unsigned int xp = (x + 1u) % NX;
unsigned int xm = (x + NX - 1u) % NX;
unsigned int yp = (y + 1u) % NY;
unsigned int ym = (y + NY - 1u) % NY;
unsigned int zp = (z + 1u) % NZ;
unsigned int zm = (z + NZ - 1u) % NZ;
j[0] = n;
#if LATTICE_MODEL == LATTICE_D3Q19
// ±x, ±y, ±z (straight)
j[1] = linear_index(xp, y, z ); // +x
j[2] = linear_index(xm, y, z ); // -x
j[3] = linear_index(x, yp, z ); // +y
j[4] = linear_index(x, ym, z ); // -y
j[5] = linear_index(x, y, zp); // +z
j[6] = linear_index(x, y, zm); // -z
// diagonal
j[7] = linear_index(xp, yp, z ); // +x+y
j[8] = linear_index(xm, ym, z ); // -x-y
j[9] = linear_index(xp, y, zp); // +x+z
j[10] = linear_index(xm, y, zm); // -x-z
j[11] = linear_index(x, yp, zp); // +y+z
j[12] = linear_index(x, ym, zm); // -y-z
j[13] = linear_index(xp, ym, z ); // +x-y
j[14] = linear_index(xm, yp, z ); // -x+y
j[15] = linear_index(xp, y, zm); // +x-z
j[16] = linear_index(xm, y, zp); // -x+z
j[17] = linear_index(x, yp, zm); // +y-z
j[18] = linear_index(x, ym, zp); // -y+z
#endif
}
#endif // DIM == 3
#endif // CELERIS_CORE_LAYOUT_CUH
+31
View File
@@ -0,0 +1,31 @@
// CelerisLab – core/obs.cuh
// Compile-time packed ``obs`` layout: force + torque + sensor segments (config_obs.h).
// ============================================================================
#ifndef CELERIS_CORE_OBS_CUH
#define CELERIS_CORE_OBS_CUH
/// Flat index into *obs* for Bouzidi force accumulation for object *id_obj*, component *d*.
__device__ __forceinline__ int obs_force_index(int id_obj, int d)
{
return OBS_FORCE0_FLOATS + id_obj * DIM + d;
}
/// Flat index into *obs* for torque accumulation for object *id_obj*, component *d*.
__device__ __forceinline__ int obs_torque_index(int id_obj, int d)
{
#if DIM == 2
(void)d;
return OBS_TORQUE0_FLOATS + id_obj;
#elif DIM == 3
return OBS_TORQUE0_FLOATS + id_obj * DIM + d;
#endif
}
/// Flat index into *obs* for sensor readout for object *id_obj*, component *d*.
__device__ __forceinline__ int obs_sensor_index(int id_obj, int d)
{
return OBS_SENSOR0_FLOATS + id_obj * DIM + d;
}
#endif // CELERIS_CORE_OBS_CUH
@@ -0,0 +1,59 @@
// CelerisLab – core/params.cuh
// Runtime parameter structures transported via __constant__ memory.
// Includes: LBMParams, RigidBodyState2D, RigidBodyControl2D.
//
// Design note:
// Only parameters that are truly consumed by current kernels should live in
// LBMParams. Future-facing interface placeholders belong in host-side API
// comments or TODOs, not in the active device contract.
// ============================================================================
#ifndef CELERIS_CORE_PARAMS_CUH
#define CELERIS_CORE_PARAMS_CUH
#include <stdint.h>
// ============================================================================
// LBM runtime parameters
//
// Grid topology and collision family are compile-time via generated headers.
// Runtime state is intentionally kept minimal:
// - omega : effective relaxation rate used by SRT/TRT/MRT
// - fx,fy,fz : external body force density for Guo forcing
// - n_objects : packed telemetry contract
// ============================================================================
struct LBMParams {
float omega;
float fx, fy, fz;
unsigned int n_objects;
};
__constant__ LBMParams d_params;
// ============================================================================
// Rigid-body state / control (2D, per architecture §17.3)
// ============================================================================
struct RigidBodyState2D {
float x, y, theta;
float vx, vy, omega;
};
struct RigidBodyControl2D {
float ax_cmd, ay_cmd;
float alpha_cmd;
int control_mode; // 0=force, 1=velocity, 2=displacement
};
// ============================================================================
// Halo plan (multi-GPU / AMR 预留)
// ============================================================================
struct HaloPlan {
int face_id;
int peer_gpu;
int level;
size_t count;
int* send_idx;
int* recv_idx;
};
#endif // CELERIS_CORE_PARAMS_CUH
@@ -0,0 +1,91 @@
// CelerisLab – core/precision.cuh
// Storage precision abstraction (FP32 / FP16S / FP16C).
// Compute precision is always float (FP32).
//
// Controlled by macros.h:
// STORE_PRECISION 0 = FP32 (default)
// 1 = FP16S (IEEE-754 half + ×32768 scaling)
// 2 = FP16C (custom 1-4-11 format, higher precision)
// ============================================================================
#ifndef CELERIS_CORE_PRECISION_CUH
#define CELERIS_CORE_PRECISION_CUH
#ifndef STORE_PRECISION
#define STORE_PRECISION 0
#endif
// ============================================================================
// FP16S – Scaled IEEE-754 Half (hardware-accelerated conversion)
// ============================================================================
#if STORE_PRECISION == 1
#include <cuda_fp16.h>
using fpxx = __half;
__device__ __forceinline__ float load_ddf(const fpxx* p, unsigned long idx) {
return __half2float(p[idx]) * 3.0517578125e-5f; // ÷ 32768
}
__device__ __forceinline__ void store_ddf(fpxx* p, unsigned long idx, float v) {
p[idx] = __float2half_rn(v * 32768.0f);
}
#define FPXX_BYTES 2
// ============================================================================
// FP16C – Custom 1-4-11 format (software conversion, ~3.6 dec. digits)
// ============================================================================
#elif STORE_PRECISION == 2
using fpxx = unsigned short;
__device__ __forceinline__ float half_custom_to_float(unsigned short x) {
unsigned int e = (x & 0x7800) >> 11;
unsigned int m = (x & 0x07FF) << 12;
unsigned int v = __float_as_uint((float)m) >> 23;
return __uint_as_float(
(x & 0x8000) << 16 |
(e != 0) * ((e + 112) << 23 | m) |
((e == 0) & (m != 0)) * ((v - 37) << 23 | ((m << (150 - v)) & 0x007FF000))
);
}
__device__ __forceinline__ unsigned short float_to_half_custom(float x) {
unsigned int b = __float_as_uint(x) + 0x00000800; // round-to-nearest-even
unsigned int e = (b & 0x7F800000) >> 23;
unsigned int m = b & 0x007FFFFF;
return (unsigned short)(
(b & 0x80000000) >> 16 |
(e > 112) * ((((e - 112) << 11) & 0x7800) | m >> 12) |
((e < 113) & (e > 100)) * ((((0x007FF800 + m) >> (124 - e)) + 1) >> 1)
);
}
__device__ __forceinline__ float load_ddf(const fpxx* p, unsigned long idx) {
return half_custom_to_float(p[idx]);
}
__device__ __forceinline__ void store_ddf(fpxx* p, unsigned long idx, float v) {
p[idx] = float_to_half_custom(v);
}
#define FPXX_BYTES 2
// ============================================================================
// FP32 – No conversion (default)
// ============================================================================
#else
using fpxx = float;
__device__ __forceinline__ float load_ddf(const fpxx* p, unsigned long idx) {
return p[idx];
}
__device__ __forceinline__ void store_ddf(fpxx* p, unsigned long idx, float v) {
p[idx] = v;
}
#define FPXX_BYTES 4
#endif // STORE_PRECISION
#endif // CELERIS_CORE_PRECISION_CUH
+74
View File
@@ -0,0 +1,74 @@
// CelerisLab – kernel_v2.cu
// ============================================================================
// Compilation entry point (Stage 2 Architecture).
//
// This file only does #includes — no kernel logic lives here.
// All __global__ functions are in step/*.cu files.
//
// File layout (each <300 lines):
// operators/helpers.cuh — bounce_back_swap, collide_dispatch
// step/init_flow.cu — InitTubeFlow_v2, InitEsoPull
// step/one_step_double.cu — OneStep (pull double-buffer)
// step/one_step_esopull.cu — EsoPullStep (single-buffer)
// step/aux_kernels.cu — CurvedBoundaryKernel, SensorKernel
// ============================================================================
#include <stdio.h>
#include <stdint.h>
#include <cuda.h>
// ---------------------------------------------------------------------------
// Layer 0: Configuration (compile-time)
// ---------------------------------------------------------------------------
#include "config.h"
// ---------------------------------------------------------------------------
// Layer 1: Core primitives
// ---------------------------------------------------------------------------
#include "core/precision.cuh"
#include "core/flags.cuh"
#include "core/descriptors.cuh"
#include "core/layout.cuh"
#include "core/params.cuh"
#include "core/obs.cuh"
// ---------------------------------------------------------------------------
// Layer 2: Operators
// ---------------------------------------------------------------------------
#include "operators/macro.cuh"
#include "operators/collision_srt.cuh"
#include "operators/collision_trt.cuh"
#include "operators/collision_mrt.cuh"
#include "operators/forcing_guo.cuh"
#include "operators/turbulence_smag.cuh"
#include "operators/helpers.cuh"
// ---------------------------------------------------------------------------
// Layer 3: Streaming
// ---------------------------------------------------------------------------
#include "streaming/pull_double_buffer.cuh"
#include "streaming/esopull_single_buffer.cuh"
#include "streaming/esopull_semantic_helpers.cuh"
// ---------------------------------------------------------------------------
// Layer 4: Boundary conditions
// ---------------------------------------------------------------------------
#include "boundary/bounce_back.cuh"
#include "boundary/curved_boundary.cuh"
#include "boundary/inlet_outlet.cuh"
#include "boundary/ibm_kernels.cuh"
// ============================================================================
// Extern "C" — all __global__ kernels exported for PyCUDA
// ============================================================================
extern "C"
{
#include "step/init_flow.cu"
#include "step/one_step_double.cu"
#include "step/one_step_esopull.cu"
#include "step/aux_kernels.cu"
#include "step/esopull_macro.cu"
#include "step/esopull_sync.cu"
} // extern "C"
@@ -0,0 +1,228 @@
// CelerisLab – operators/collision_mrt.cuh
// MRT (Multiple-Relaxation-Time) collision operator.
//
// D2Q9 Lallemand-Luo (Phys. Rev. E 61, 2000) with NEW paired ordering:
// cx = {0, 1,-1, 0, 0, 1,-1, 1,-1}
// cy = {0, 0, 0, 1,-1, 1,-1,-1, 1}
//
// Moment space:
// m[0] = ρ (conserved, s₀ = 0 or 1.0 overwrite)
// m[1] = e (energy, s₁ = s_e)
// m[2] = ε (energy², s₂ = s_eps)
// m[3] = jx (conserved, s₃ = 0 or 1.0 overwrite)
// m[4] = qx (energy flux x, s₄ = s_q)
// m[5] = jy (conserved, s₅ = 0 or 1.0 overwrite)
// m[6] = qy (energy flux y, s₆ = s_q)
// m[7] = pxx (stress, s₇ = s_nu = ω = 1/(3ν + 0.5))
// m[8] = pxy (stress, s₈ = s_nu)
//
// NOTE on ddf_shifting (USE_DDF_SHIFTING):
// MRT is NOT shift-invariant in moment space because the moment transform
// of the weight vector w produces non-zero entries in m[1] (energy) and
// m[2] (energy^2). Unlike SRT/TRT where (f-feq) cancels weights pairwise,
// the MRT moment construction and inverse transform do not preserve the
// shifted-space semantics.
//
// Therefore when USE_DDF_SHIFTING=1, this function temporarily unshifts
// the distributions to physical space before collision, then shifts them
// back after. This ensures the moment construction, relaxation, and
// inverse transform all operate on physically meaningful distributions.
//
// Forcing contract:
// Fin[i] is the raw Guo source term without the (1 - ω/2) prefactor.
// This operator applies the prefactor internally, matching collide_srt().
// ============================================================================
#ifndef CELERIS_OPERATORS_COLLISION_MRT_CUH
#define CELERIS_OPERATORS_COLLISION_MRT_CUH
#if LATTICE_MODEL == LATTICE_D2Q9
__device__ __forceinline__ void collide_mrt(float* __restrict__ g,
float rho, float ux, float uy,
const float* __restrict__ Fin,
float omega)
{
// MRT is not shift-invariant in moment space. When USE_DDF_SHIFTING=1,
// temporarily unshift to physical space before collision.
#if USE_DDF_SHIFTING
g[0] += (float)d_w[0]; g[1] += (float)d_w[1]; g[2] += (float)d_w[2];
g[3] += (float)d_w[3]; g[4] += (float)d_w[4]; g[5] += (float)d_w[5];
g[6] += (float)d_w[6]; g[7] += (float)d_w[7]; g[8] += (float)d_w[8];
#endif
const float s_rho = 0.0f;
const float s_e = 1.2f;
const float s_eps = 1.2f;
const float s_jx = 0.0f;
const float s_q = 1.2f;
const float s_jy = 0.0f;
const float s_nu = omega;
const float c_tau = 1.0f - 0.5f * omega;
const float p = rho * (1.0f / 3.0f);
float m[9];
m[0] = g[0] + g[1] + g[2] + g[3] + g[4] + g[5] + g[6] + g[7] + g[8];
m[1] = -4*g[0] - g[1] - g[2] - g[3] - g[4] + 2*g[5] + 2*g[6] + 2*g[7] + 2*g[8];
m[2] = 4*g[0] - 2*g[1] - 2*g[2] - 2*g[3] - 2*g[4] + g[5] + g[6] + g[7] + g[8];
m[3] = g[1] - g[2] + g[5] - g[6] + g[7] - g[8];
m[4] = -2*g[1] + 2*g[2] + g[5] - g[6] + g[7] - g[8];
m[5] = g[3] - g[4] + g[5] - g[6] - g[7] + g[8];
m[6] = -2*g[3] + 2*g[4] + g[5] - g[6] - g[7] + g[8];
m[7] = g[1] + g[2] - g[3] - g[4];
m[8] = g[5] + g[6] - g[7] - g[8];
const float u2 = ux * ux + uy * uy;
float meq[9];
meq[0] = 3.0f * p;
meq[1] = -6.0f * p + 3.0f * rho * u2;
meq[2] = 3.0f * p - 3.0f * rho * u2;
meq[3] = rho * ux;
meq[4] = -rho * ux;
meq[5] = rho * uy;
meq[6] = -rho * uy;
meq[7] = rho * (ux * ux - uy * uy);
meq[8] = rho * ux * uy;
float dm[9];
dm[0] = s_rho * (meq[0] - m[0]);
dm[1] = s_e * (meq[1] - m[1]);
dm[2] = s_eps * (meq[2] - m[2]);
dm[3] = s_jx * (meq[3] - m[3]);
dm[4] = s_q * (meq[4] - m[4]);
dm[5] = s_jy * (meq[5] - m[5]);
dm[6] = s_q * (meq[6] - m[6]);
dm[7] = s_nu * (meq[7] - m[7]);
dm[8] = s_nu * (meq[8] - m[8]);
g[0] += ( dm[0] - dm[1] + dm[2] ) / 9.0f;
g[1] += (4 * dm[0] - dm[1] - 2* dm[2] + 6* dm[3] - 6* dm[4] + 9*dm[7]) / 36.0f;
g[2] += (4 * dm[0] - dm[1] - 2* dm[2] - 6* dm[3] + 6* dm[4] + 9*dm[7]) / 36.0f;
g[3] += (4 * dm[0] - dm[1] - 2* dm[2] + 6*dm[5] - 6*dm[6] - 9*dm[7]) / 36.0f;
g[4] += (4 * dm[0] - dm[1] - 2* dm[2] - 6*dm[5] + 6*dm[6] - 9*dm[7]) / 36.0f;
g[5] += (4 * dm[0] + 2* dm[1] + dm[2] + 6* dm[3] + 3* dm[4] + 6*dm[5] + 3*dm[6] + 9*dm[8]) / 36.0f;
g[6] += (4 * dm[0] + 2* dm[1] + dm[2] - 6* dm[3] - 3* dm[4] - 6*dm[5] - 3*dm[6] + 9*dm[8]) / 36.0f;
g[7] += (4 * dm[0] + 2* dm[1] + dm[2] + 6* dm[3] + 3* dm[4] - 6*dm[5] - 3*dm[6] - 9*dm[8]) / 36.0f;
g[8] += (4 * dm[0] + 2* dm[1] + dm[2] - 6* dm[3] - 3* dm[4] + 6*dm[5] + 3*dm[6] - 9*dm[8]) / 36.0f;
#pragma unroll
for (int i = 0; i < 9; i++) {
g[i] += c_tau * Fin[i];
}
#if USE_DDF_SHIFTING
g[0] -= (float)d_w[0]; g[1] -= (float)d_w[1]; g[2] -= (float)d_w[2];
g[3] -= (float)d_w[3]; g[4] -= (float)d_w[4]; g[5] -= (float)d_w[5];
g[6] -= (float)d_w[6]; g[7] -= (float)d_w[7]; g[8] -= (float)d_w[8];
#endif
}
__device__ __forceinline__ void collide_mrt_no_force(float* __restrict__ g,
float rho, float ux, float uy,
float omega)
{
float Fin[9] = {0};
collide_mrt(g, rho, ux, uy, Fin, omega);
}
#elif LATTICE_MODEL == LATTICE_D3Q19
__device__ __forceinline__ void collide_mrt(float* __restrict__ g,
float rho, float ux, float uy, float uz,
const float* __restrict__ Fin,
float omega)
{
// MRT is not shift-invariant. Temporarily unshift to physical space.
#if USE_DDF_SHIFTING
#pragma unroll
for (int i = 0; i < 19; i++) g[i] += (float)d_w[i];
#endif
float feq[19];
compute_feq(rho, ux, uy, uz, feq);
const float s_nu = omega;
const float s_bulk = 1.2f;
const float s_high = 1.4f;
const float c_tau = 1.0f - 0.5f * omega;
const float one_minus_s_nu = 1.0f - s_nu;
const float one_minus_s_bulk = 1.0f - s_bulk;
const float one_minus_s_high = 1.0f - s_high;
float neq[19];
#pragma unroll
for (int i = 0; i < 19; i++) {
neq[i] = g[i] - feq[i];
}
float pixx = 0.0f, piyy = 0.0f, pizz = 0.0f;
float pixy = 0.0f, pixz = 0.0f, piyz = 0.0f;
#pragma unroll
for (int i = 0; i < 19; i++) {
const float ci_x = (float)d_cx[i];
const float ci_y = (float)d_cy[i];
const float ci_z = (float)d_cz[i];
const float fneq = neq[i];
pixx += fneq * ci_x * ci_x;
piyy += fneq * ci_y * ci_y;
pizz += fneq * ci_z * ci_z;
pixy += fneq * ci_x * ci_y;
pixz += fneq * ci_x * ci_z;
piyz += fneq * ci_y * ci_z;
}
const float tr_pi = pixx + piyy + pizz;
const float tr_pi_thrd = tr_pi * (1.0f / 3.0f);
const float dev_xx = pixx - tr_pi_thrd;
const float dev_yy = piyy - tr_pi_thrd;
const float dev_zz = pizz - tr_pi_thrd;
const float dev_xy = pixy;
const float dev_xz = pixz;
const float dev_yz = piyz;
const float proj_pref = 4.5f;
#pragma unroll
for (int i = 0; i < 19; i++) {
const float ci_x = (float)d_cx[i];
const float ci_y = (float)d_cy[i];
const float ci_z = (float)d_cz[i];
const float q_xx = ci_x * ci_x - CS2;
const float q_yy = ci_y * ci_y - CS2;
const float q_zz = ci_z * ci_z - CS2;
const float q_xy = ci_x * ci_y;
const float q_xz = ci_x * ci_z;
const float q_yz = ci_y * ci_z;
const float q_dot_dev =
q_xx * dev_xx + q_yy * dev_yy + q_zz * dev_zz
+ 2.0f * (q_xy * dev_xy + q_xz * dev_xz + q_yz * dev_yz);
const float q_trace = q_xx + q_yy + q_zz;
const float q_dot_iso = q_trace * tr_pi_thrd;
const float neq_dev = d_w[i] * proj_pref * q_dot_dev;
const float neq_iso = d_w[i] * proj_pref * q_dot_iso;
const float neq_h = neq[i] - neq_dev - neq_iso;
g[i] = feq[i]
+ one_minus_s_nu * neq_dev
+ one_minus_s_bulk * neq_iso
+ one_minus_s_high * neq_h
+ c_tau * Fin[i];
}
#if USE_DDF_SHIFTING
#pragma unroll
for (int i = 0; i < 19; i++) g[i] -= (float)d_w[i];
#endif
}
#endif // NQ
#endif // CELERIS_OPERATORS_COLLISION_MRT_CUH
@@ -0,0 +1,35 @@
// CelerisLab – operators/collision_srt.cuh
// SRT (BGK) collision operator.
// f_out[i] = (1 - ω) f[i] + ω feq[i] + Fin[i]
// ============================================================================
#ifndef CELERIS_OPERATORS_COLLISION_SRT_CUH
#define CELERIS_OPERATORS_COLLISION_SRT_CUH
__device__ __forceinline__ void collide_srt(float* __restrict__ f,
const float* __restrict__ feq,
const float* __restrict__ Fin,
float omega)
{
// Pre-compute forcing prefactor (1 - ω/2) for Guo scheme
const float c_tau = 1.0f - 0.5f * omega;
#pragma unroll
for (int i = 0; i < NQ; i++) {
f[i] = fmaf(1.0f - omega, f[i],
fmaf(omega, feq[i], c_tau * Fin[i]));
}
}
// Variant without forcing (Fin = 0)
__device__ __forceinline__ void collide_srt_no_force(float* __restrict__ f,
const float* __restrict__ feq,
float omega)
{
#pragma unroll
for (int i = 0; i < NQ; i++) {
f[i] = fmaf(1.0f - omega, f[i], omega * feq[i]);
}
}
#endif // CELERIS_OPERATORS_COLLISION_SRT_CUH
@@ -0,0 +1,78 @@
// CelerisLab – operators/collision_trt.cuh
// TRT (Two-Relaxation-Time) collision operator.
//
// Symmetric part uses ω⁺ (= omega, transport viscosity)
// Antisymmetric uses ω⁻ (linked by magic parameter Λ = 3/16)
// ω⁻ = 1 / (Λ / (1/ω⁺ - 0.5) + 0.5)
//
// Paired direction ordering makes TRT natural:
// f_s[i] = 0.5*(f[i] + f[opp(i)]) symmetric
// f_a[i] = 0.5*(f[i] - f[opp(i)]) antisymmetric
//
// Forcing contract:
// Fin[i] is the raw Guo source term without the (1 - ω/2) prefactor.
// This operator applies the prefactor internally, matching collide_srt().
// ============================================================================
#ifndef CELERIS_OPERATORS_COLLISION_TRT_CUH
#define CELERIS_OPERATORS_COLLISION_TRT_CUH
#ifndef TRT_MAGIC_PARAM
#define TRT_MAGIC_PARAM (0.1875f)
#endif
__device__ __forceinline__ float compute_omega_minus(float omega_plus) {
return 1.0f / (TRT_MAGIC_PARAM / (1.0f / omega_plus - 0.5f) + 0.5f);
}
__device__ __forceinline__ void collide_trt(float* __restrict__ f,
const float* __restrict__ feq,
const float* __restrict__ Fin,
float omega)
{
const float wp = omega;
const float wm = compute_omega_minus(wp);
const float c_tau = 1.0f - 0.5f * wp;
f[0] = f[0] - wp * (f[0] - feq[0]) + c_tau * Fin[0];
#pragma unroll
for (int i = 1; i < NQ; i += 2) {
const int ib = i + 1;
const float fi = f[i];
const float fb = f[ib];
const float feqi = feq[i];
const float feqb = feq[ib];
const float delta_s = 0.5f * ((fi - feqi) + (fb - feqb));
const float delta_a = 0.5f * ((fi - feqi) - (fb - feqb));
f[i] = fi - wp * delta_s - wm * delta_a + c_tau * Fin[i];
f[ib] = fb - wp * delta_s + wm * delta_a + c_tau * Fin[ib];
}
}
__device__ __forceinline__ void collide_trt_no_force(float* __restrict__ f,
const float* __restrict__ feq,
float omega)
{
const float wp = omega;
const float wm = compute_omega_minus(wp);
f[0] = f[0] - wp * (f[0] - feq[0]);
#pragma unroll
for (int i = 1; i < NQ; i += 2) {
const int ib = i + 1;
const float fi = f[i], fb = f[ib];
const float feqi = feq[i], feqb = feq[ib];
const float delta_s = 0.5f * ((fi - feqi) + (fb - feqb));
const float delta_a = 0.5f * ((fi - feqi) - (fb - feqb));
f[i] = fi - wp * delta_s - wm * delta_a;
f[ib] = fb - wp * delta_s + wm * delta_a;
}
}
#endif // CELERIS_OPERATORS_COLLISION_TRT_CUH
@@ -0,0 +1,102 @@
// CelerisLab – operators/forcing_guo.cuh
// Guo forcing scheme (Guo, Zheng & Shi, Phys. Rev. E 65, 2002).
//
// Velocity correction: u* = u + F·dt / (2ρ)
// Forcing term:
// Fin[i] = (1 - ω/2) · w_i · [ (c_i - u*)/cs² + (c_i · u*)/cs⁴ · c_i ] · F
// simplified: Fin[i] = 9·w_i · [ (c_i·F)(c_i·u* + 1/3) - u*·F/3 ]
// ============================================================================
#ifndef CELERIS_OPERATORS_FORCING_GUO_CUH
#define CELERIS_OPERATORS_FORCING_GUO_CUH
// ---------------------------------------------------------------------------
// D2Q9 Guo forcing terms
// ---------------------------------------------------------------------------
#if LATTICE_MODEL == LATTICE_D2Q9
__device__ __forceinline__ void apply_guo_velocity_correction(
float& ux, float& uy,
float fx, float fy, float rho)
{
float rho2 = 0.5f / rho;
ux = fmaf(fx, rho2, ux);
uy = fmaf(fy, rho2, uy);
}
__device__ __forceinline__ void compute_guo_forcing(
float ux, float uy, // velocity (already corrected: u*)
float fx, float fy, // force density
float* __restrict__ Fin)
{
const float uF = -0.33333334f * fmaf(ux, fx, uy * fy); // -u*·F / 3
Fin[0] = 9.0f * W0_VAL * uF;
// Straight directions
// cx = {0, 1,-1, 0, 0, 1,-1, 1,-1}
// cy = {0, 0, 0, 1,-1, 1,-1,-1, 1}
Fin[1] = 9.0f * WS_VAL * fmaf( fx, ux + 0.33333334f, uF); // +x
Fin[2] = 9.0f * WS_VAL * fmaf(-fx, -ux + 0.33333334f, uF); // -x
Fin[3] = 9.0f * WS_VAL * fmaf( fy, uy + 0.33333334f, uF); // +y
Fin[4] = 9.0f * WS_VAL * fmaf(-fy, -uy + 0.33333334f, uF); // -y
// Diagonal directions
const float f5x = fx, f5y = fy; // +x+y
const float c5u = ux + uy;
const float c5F = f5x + f5y;
Fin[5] = 9.0f * WE_VAL * fmaf(c5F, c5u + 0.33333334f, uF);
const float c6u = -ux - uy; // -x-y
const float c6F = -fx - fy;
Fin[6] = 9.0f * WE_VAL * fmaf(c6F, c6u + 0.33333334f, uF);
const float c7u = ux - uy; // +x-y
const float c7F = fx - fy;
Fin[7] = 9.0f * WE_VAL * fmaf(c7F, c7u + 0.33333334f, uF);
const float c8u = -ux + uy; // -x+y
const float c8F = -fx + fy;
Fin[8] = 9.0f * WE_VAL * fmaf(c8F, c8u + 0.33333334f, uF);
}
#elif LATTICE_MODEL == LATTICE_D3Q19
__device__ __forceinline__ void apply_guo_velocity_correction(
float& ux, float& uy, float& uz,
float fx, float fy, float fz, float rho)
{
float rho2 = 0.5f / rho;
ux = fmaf(fx, rho2, ux);
uy = fmaf(fy, rho2, uy);
uz = fmaf(fz, rho2, uz);
}
__device__ __forceinline__ void compute_guo_forcing(
float ux, float uy, float uz,
float fx, float fy, float fz,
float* __restrict__ Fin)
{
const float uF = -0.33333334f * fmaf(ux, fx, fmaf(uy, fy, uz * fz));
Fin[0] = 9.0f * W0_VAL * uF;
// Generic loop for D3Q19 (compiler will fully unroll)
for (int i = 1; i < 19; i++) {
float ci_dot_F = d_cx[i]*fx + d_cy[i]*fy + d_cz[i]*fz;
float ci_dot_u = d_cx[i]*ux + d_cy[i]*uy + d_cz[i]*uz;
Fin[i] = 9.0f * d_w[i] * fmaf(ci_dot_F, ci_dot_u + 0.33333334f, uF);
}
}
#endif // LATTICE_MODEL
// ---------------------------------------------------------------------------
// Zero forcing helper (when no external force)
// ---------------------------------------------------------------------------
__device__ __forceinline__ void zero_forcing(float* __restrict__ Fin) {
#pragma unroll
for (int i = 0; i < NQ; i++) Fin[i] = 0.0f;
}
#endif // CELERIS_OPERATORS_FORCING_GUO_CUH
@@ -0,0 +1,71 @@
// CelerisLab – operators/helpers.cuh
// Shared device helpers used by all step kernels.
// ============================================================================
#ifndef CELERIS_OPERATORS_HELPERS_CUH
#define CELERIS_OPERATORS_HELPERS_CUH
__device__ __forceinline__ void bounce_back_swap(float* f) {
#pragma unroll
for (int i = 1; i < NQ; i += 2) {
float t = f[i]; f[i] = f[i+1]; f[i+1] = t;
}
}
__device__ __forceinline__ void collide_dispatch(
float* f, float rho_n,
#if DIM == 2
float ux, float uy
#elif DIM == 3
float ux, float uy, float uz
#endif
) {
float feq[NQ], Fin[NQ];
float omega_col = d_params.omega;
#if DIM == 2
const float fx = d_params.fx;
const float fy = d_params.fy;
if (fx != 0.0f || fy != 0.0f) {
apply_guo_velocity_correction(ux, uy, fx, fy, rho_n);
}
compute_feq(rho_n, ux, uy, feq);
if (fx != 0.0f || fy != 0.0f) {
compute_guo_forcing(ux, uy, fx, fy, Fin);
} else {
zero_forcing(Fin);
}
#elif DIM == 3
const float fx = d_params.fx;
const float fy = d_params.fy;
const float fz = d_params.fz;
if (fx != 0.0f || fy != 0.0f || fz != 0.0f) {
apply_guo_velocity_correction(ux, uy, uz, fx, fy, fz, rho_n);
}
compute_feq(rho_n, ux, uy, uz, feq);
if (fx != 0.0f || fy != 0.0f || fz != 0.0f) {
compute_guo_forcing(ux, uy, uz, fx, fy, fz, Fin);
} else {
zero_forcing(Fin);
}
#endif
#if USE_LES
omega_col = compute_omega_smag(f, feq, rho_n, omega_col);
#endif
omega_col = fminf(OMEGA_COLLISION_MAX, fmaxf(OMEGA_COLLISION_MIN, omega_col));
#if COLLISION_MODEL == 0
collide_srt(f, feq, Fin, omega_col);
#elif COLLISION_MODEL == 1
collide_trt(f, feq, Fin, omega_col);
#elif COLLISION_MODEL == 2
#if DIM == 2
collide_mrt(f, rho_n, ux, uy, Fin, omega_col);
#elif DIM == 3
collide_mrt(f, rho_n, ux, uy, uz, Fin, omega_col);
#endif
#endif
}
#endif // CELERIS_OPERATORS_HELPERS_CUH
@@ -0,0 +1,171 @@
// CelerisLab – operators/macro.cuh
// Macroscopic quantity computation (rho, u) and equilibrium distribution (feq).
// Supports DDF-shifting (USE_DDF_SHIFTING=1) and standard mode (=0).
//
// D2Q9 paired ordering:
// cx = {0, 1,-1, 0, 0, 1,-1, 1,-1}
// cy = {0, 0, 0, 1,-1, 1,-1,-1, 1}
// ============================================================================
#ifndef CELERIS_OPERATORS_MACRO_CUH
#define CELERIS_OPERATORS_MACRO_CUH
#ifndef USE_DDF_SHIFTING
#define USE_DDF_SHIFTING 0
#endif
// ---------------------------------------------------------------------------
// compute_rho_u: f[NQ] → (rho, ux, uy [, uz])
// ---------------------------------------------------------------------------
#if LATTICE_MODEL == LATTICE_D2Q9
__device__ __forceinline__ void compute_rho_u(const float* __restrict__ f,
float& rho,
float& ux, float& uy)
{
// Density: sum of all populations
rho = f[0] + f[1] + f[2] + f[3] + f[4] + f[5] + f[6] + f[7] + f[8];
#if USE_DDF_SHIFTING
rho += 1.0f; // DDF-shifting: stored f_tilde = f - w, sum(w) = 1
#endif
// Momentum (works identically with or without DDF-shifting,
// because sum(w_i * cx_i) = 0)
float inv_rho = 1.0f / rho;
// cx: 0 1 -1 0 0 1 -1 1 -1
ux = (f[1] - f[2] + f[5] - f[6] + f[7] - f[8]) * inv_rho;
// cy: 0 0 0 1 -1 1 -1 -1 1
uy = (f[3] - f[4] + f[5] - f[6] - f[7] + f[8]) * inv_rho;
}
#elif LATTICE_MODEL == LATTICE_D3Q19
__device__ __forceinline__ void compute_rho_u(const float* __restrict__ f,
float& rho,
float& ux, float& uy, float& uz)
{
rho = f[0];
for (int i = 1; i < 19; i++) rho += f[i];
#if USE_DDF_SHIFTING
rho += 1.0f;
#endif
float inv_rho = 1.0f / rho;
ux = (f[1]-f[2] + f[7]-f[8] + f[9]-f[10] + f[13]-f[14] + f[15]-f[16]) * inv_rho;
uy = (f[3]-f[4] + f[7]-f[8] + f[11]-f[12] + f[14]-f[13] + f[17]-f[18]) * inv_rho;
uz = (f[5]-f[6] + f[9]-f[10] + f[11]-f[12] + f[16]-f[15] + f[18]-f[17]) * inv_rho;
}
#endif // LATTICE_MODEL (compute_rho_u)
// ---------------------------------------------------------------------------
// compute_feq: (rho, u) → feq[NQ]
// ---------------------------------------------------------------------------
#if LATTICE_MODEL == LATTICE_D2Q9
__device__ __forceinline__ void compute_feq(float rho, float ux, float uy,
float* __restrict__ feq)
{
#if USE_DDF_SHIFTING
const float rhom1 = rho - 1.0f; // perturbation density
#endif
const float ux3 = 3.0f * ux;
const float uy3 = 3.0f * uy;
const float c3 = -1.5f * (ux * ux + uy * uy); // = -|u|²/(2cs²)
// Helper: feq_i = w_i * rho * (1 + 3 ci·u + 4.5 (ci·u)² - 1.5 u²)
// With DDF-shifting: feq_tilde_i = feq_i - w_i
// = w_i * (rho * (1 + ...) - 1) = w_i * (rho*(...) + rho - 1)
#define FEQ_CORE(cu) (rho * fmaf(0.5f * 3.0f, (cu) * (cu), (cu) + c3))
#if USE_DDF_SHIFTING
#define FEQ(w, cu) ((w) * fmaf(rho, fmaf(0.5f, (cu)*(cu), (cu) + c3), rhom1))
#else
#define FEQ(w, cu) ((w) * rho * (1.0f + (cu) + 0.5f * (cu) * (cu) + c3))
#endif
// i=0: rest
feq[0] = FEQ(W0_VAL, 0.0f);
// (1,2) ±x
feq[1] = FEQ(WS_VAL, ux3);
feq[2] = FEQ(WS_VAL, -ux3);
// (3,4) ±y
feq[3] = FEQ(WS_VAL, uy3);
feq[4] = FEQ(WS_VAL, -uy3);
// Pre-compute diagonal velocity combos
const float u0 = ux3 + uy3; // +x+y
const float u1 = ux3 - uy3; // +x-y
// (5,6) ±(x+y)
feq[5] = FEQ(WE_VAL, u0);
feq[6] = FEQ(WE_VAL, -u0);
// (7,8) ±(x-y)
feq[7] = FEQ(WE_VAL, u1);
feq[8] = FEQ(WE_VAL, -u1);
#undef FEQ
#undef FEQ_CORE
}
#elif LATTICE_MODEL == LATTICE_D3Q19
__device__ __forceinline__ void compute_feq(float rho, float ux, float uy, float uz,
float* __restrict__ feq)
{
#if USE_DDF_SHIFTING
const float rhom1 = rho - 1.0f;
#endif
const float ux3 = 3.0f * ux;
const float uy3 = 3.0f * uy;
const float uz3 = 3.0f * uz;
const float c3 = -1.5f * (ux*ux + uy*uy + uz*uz);
#if USE_DDF_SHIFTING
#define FEQ(w, cu) ((w) * fmaf(rho, fmaf(0.5f, (cu)*(cu), (cu) + c3), rhom1))
#else
#define FEQ(w, cu) ((w) * rho * (1.0f + (cu) + 0.5f * (cu) * (cu) + c3))
#endif
feq[0] = FEQ(W0_VAL, 0.0f);
// Straight
feq[1] = FEQ(WS_VAL, ux3); feq[2] = FEQ(WS_VAL, -ux3);
feq[3] = FEQ(WS_VAL, uy3); feq[4] = FEQ(WS_VAL, -uy3);
feq[5] = FEQ(WS_VAL, uz3); feq[6] = FEQ(WS_VAL, -uz3);
// Diagonal
const float u0 = ux3+uy3, u1 = ux3+uz3, u2 = uy3+uz3;
const float u3 = ux3-uy3, u4 = ux3-uz3, u5 = uy3-uz3;
feq[7] = FEQ(WE_VAL, u0); feq[8] = FEQ(WE_VAL, -u0);
feq[9] = FEQ(WE_VAL, u1); feq[10] = FEQ(WE_VAL, -u1);
feq[11] = FEQ(WE_VAL, u2); feq[12] = FEQ(WE_VAL, -u2);
feq[13] = FEQ(WE_VAL, u3); feq[14] = FEQ(WE_VAL, -u3);
feq[15] = FEQ(WE_VAL, u4); feq[16] = FEQ(WE_VAL, -u4);
feq[17] = FEQ(WE_VAL, u5); feq[18] = FEQ(WE_VAL, -u5);
#undef FEQ
}
#endif // LATTICE_MODEL (compute_feq)
// ---------------------------------------------------------------------------
// --- Diagnostic only ---
// ---------------------------------------------------------------------------
// compute_pressure / compute_pressure_perturbation are diagnostic helpers
// not consumed by any kernel on a hot path.
// ---------------------------------------------------------------------------
__device__ __forceinline__ float compute_pressure(float rho) {
return CS2 * rho;
}
__device__ __forceinline__ float compute_pressure_perturbation(float rho, float rho_ref) {
return CS2 * (rho - rho_ref);
}
#endif // CELERIS_OPERATORS_MACRO_CUH
@@ -0,0 +1,189 @@
// CelerisLab – operators/turbulence_smag.cuh
// Smagorinsky LES: compute effective omega from local non-equilibrium stress.
//
// Model:
// nu_t = (C_s * Delta)^2 * |S|, Delta = 1 (lattice unit)
// omega_eff = 1 / (3*(nu + nu_t) + 0.5)
//
// |S| is estimated from non-equilibrium second-order moments using tau0.
// ============================================================================
#ifndef CELERIS_OPERATORS_TURBULENCE_SMAG_CUH
#define CELERIS_OPERATORS_TURBULENCE_SMAG_CUH
#ifndef USE_LES
#define USE_LES 0
#endif
#ifndef LES_CS
#define LES_CS 0.16f
#endif
#ifndef LES_CLOSED_FORM
#define LES_CLOSED_FORM 1
#endif
#ifndef LES_FP_ITERS
#define LES_FP_ITERS 3
#endif
#ifndef LES_FP_RELAX
#define LES_FP_RELAX 0.70f
#endif
#ifndef LES_NUT_MAX_RATIO
#define LES_NUT_MAX_RATIO 20.0f
#endif
__device__ __forceinline__ float clamp_omega(float w) {
return fminf(OMEGA_COLLISION_MAX, fmaxf(OMEGA_COLLISION_MIN, w));
}
#if LATTICE_MODEL == LATTICE_D2Q9
__device__ __forceinline__ float compute_omega_smag(const float* __restrict__ f,
const float* __restrict__ feq,
float rho,
float omega0)
{
const float rho_safe = fmaxf(rho, 1.0e-12f);
const float tau0 = fmaxf(1.0f / fmaxf(omega0, 1.0e-6f), 0.500001f);
// Πneq = Σ (ci ci)(fi-feqi)
float pixx = 0.0f, piyy = 0.0f, pixy = 0.0f;
#pragma unroll
for (int i = 0; i < 9; i++) {
const float fneq = f[i] - feq[i];
const float cx = (float)d_cx[i];
const float cy = (float)d_cy[i];
pixx += fneq * cx * cx;
piyy += fneq * cy * cy;
pixy += fneq * cx * cy;
}
#if LES_CLOSED_FORM
// Closed-form Smagorinsky (no iteration):
// ω = 2 / (τ₀ + √(τ₀² + 18·Cs²·√Q / ρ))
// where Q = Πneq_ij · Πneq_ij (Frobenius norm squared)
const float Q = pixx*pixx + piyy*piyy + 2.0f*pixy*pixy;
const float sqrtQ = sqrtf(fmaxf(Q, 0.0f));
const float smag_const_sq = LES_CS * LES_CS;
const float discriminant = tau0*tau0 + 18.0f * smag_const_sq * sqrtQ / rho_safe;
const float tau_eff = 0.5f * (tau0 + sqrtf(fmaxf(discriminant, tau0*tau0)));
return clamp_omega(1.0f / fmaxf(tau_eff, 0.500001f));
#else
// Iterative fixed-point (original)
const float nu0 = (tau0 - 0.5f) * (1.0f / 3.0f);
float tau_eff = tau0;
const float tau_max = 1.0f / fmaxf(OMEGA_COLLISION_MIN, 1.0e-6f);
#pragma unroll
for (int it = 0; it < LES_FP_ITERS; ++it) {
const float denom = 2.0f * rho_safe * CS2 * fmaxf(tau_eff, 0.500001f);
const float sxx = -pixx / denom;
const float syy = -piyy / denom;
const float sxy = -pixy / denom;
// Use deviatoric strain to reduce SGS sensitivity to bulk/pressure-wave content.
const float tr = 0.5f * (sxx + syy);
const float sxx_dev = sxx - tr;
const float syy_dev = syy - tr;
const float sxy_dev = sxy;
// |S_dev| = sqrt(2 S_dev,ij S_dev,ij)
const float s_mag = sqrtf(2.0f * (sxx_dev*sxx_dev + syy_dev*syy_dev + 2.0f*sxy_dev*sxy_dev));
float nut = (LES_CS * LES_CS) * s_mag;
const float nut_cap = fmaxf(0.0f, LES_NUT_MAX_RATIO * nu0);
nut = fminf(fmaxf(nut, 0.0f), nut_cap);
const float tau_new = fminf(tau_max, fmaxf(0.500001f, 0.5f + 3.0f * (nu0 + nut)));
tau_eff = LES_FP_RELAX * tau_new + (1.0f - LES_FP_RELAX) * tau_eff;
}
return clamp_omega(1.0f / tau_eff);
#endif // LES_CLOSED_FORM
}
#elif LATTICE_MODEL == LATTICE_D3Q19
__device__ __forceinline__ float compute_omega_smag(const float* __restrict__ f,
const float* __restrict__ feq,
float rho,
float omega0)
{
const float rho_safe = fmaxf(rho, 1.0e-12f);
const float tau0 = fmaxf(1.0f / fmaxf(omega0, 1.0e-6f), 0.500001f);
// Πneq = Σ (ci ci)(fi-feqi)
float pixx = 0.0f, piyy = 0.0f, pizz = 0.0f;
float pixy = 0.0f, pixz = 0.0f, piyz = 0.0f;
#pragma unroll
for (int i = 0; i < 19; i++) {
const float fneq = f[i] - feq[i];
const float cx = (float)d_cx[i];
const float cy = (float)d_cy[i];
const float cz = (float)d_cz[i];
pixx += fneq * cx * cx;
piyy += fneq * cy * cy;
pizz += fneq * cz * cz;
pixy += fneq * cx * cy;
pixz += fneq * cx * cz;
piyz += fneq * cy * cz;
}
#if LES_CLOSED_FORM
const float Q = pixx*pixx + piyy*piyy + pizz*pizz
+ 2.0f*(pixy*pixy + pixz*pixz + piyz*piyz);
const float sqrtQ = sqrtf(fmaxf(Q, 0.0f));
const float smag_const_sq = LES_CS * LES_CS;
const float discriminant = tau0*tau0 + 18.0f * smag_const_sq * sqrtQ / rho_safe;
const float tau_eff = 0.5f * (tau0 + sqrtf(fmaxf(discriminant, tau0*tau0)));
return clamp_omega(1.0f / fmaxf(tau_eff, 0.500001f));
#else
// Self-consistent tau iteration for LES/TRT coupling.
const float nu0 = (tau0 - 0.5f) * (1.0f / 3.0f);
float tau_eff = tau0;
const float tau_max = 1.0f / fmaxf(OMEGA_COLLISION_MIN, 1.0e-6f);
#pragma unroll
for (int it = 0; it < LES_FP_ITERS; ++it) {
const float denom = 2.0f * rho_safe * CS2 * fmaxf(tau_eff, 0.500001f);
const float sxx = -pixx / denom;
const float syy = -piyy / denom;
const float szz = -pizz / denom;
const float sxy = -pixy / denom;
const float sxz = -pixz / denom;
const float syz = -piyz / denom;
// Use deviatoric strain to reduce SGS sensitivity to bulk/pressure-wave content.
const float tr = (sxx + syy + szz) / 3.0f;
const float sxx_dev = sxx - tr;
const float syy_dev = syy - tr;
const float szz_dev = szz - tr;
const float sxy_dev = sxy;
const float sxz_dev = sxz;
const float syz_dev = syz;
// |S_dev| = sqrt(2 S_dev,ij S_dev,ij)
const float s_mag = sqrtf(2.0f * (sxx_dev*sxx_dev + syy_dev*syy_dev + szz_dev*szz_dev
+ 2.0f*(sxy_dev*sxy_dev + sxz_dev*sxz_dev + syz_dev*syz_dev)));
float nut = (LES_CS * LES_CS) * s_mag;
const float nut_cap = fmaxf(0.0f, LES_NUT_MAX_RATIO * nu0);
nut = fminf(fmaxf(nut, 0.0f), nut_cap);
const float tau_new = fminf(tau_max, fmaxf(0.500001f, 0.5f + 3.0f * (nu0 + nut)));
tau_eff = LES_FP_RELAX * tau_new + (1.0f - LES_FP_RELAX) * tau_eff;
}
return clamp_omega(1.0f / tau_eff);
#endif // LES_CLOSED_FORM
}
#endif // NQ
#endif // CELERIS_OPERATORS_TURBULENCE_SMAG_CUH
@@ -0,0 +1,355 @@
// CelerisLab – step/aux_kernels.cu
// Auxiliary kernels: CurvedBoundaryKernel, PrepareEsoPullCurvedKernel,
// ApplyEsoPullCurvedKernel, SensorKernel, ForceRegionKernel.
//
// Launched on compact lists (n_curved / n_sensor / n_cells threads).
// Included by kernel_v2.cu. No standalone compilation.
//
// Double-buffer mode:
// CurvedBoundaryKernel runs BEFORE OneStep.
// SensorKernel / ForceRegionKernel run after.
//
// EsoPull mode:
// PrepareEsoPullCurvedKernel + ApplyEsoPullCurvedKernel run before EsoPullStep.
// Prepare uses load_physical_dir_pre_streaming() for Bouzidi force calc
// (pre-streaming semantics = matching double-buffer fi_in[k, dir]).
// SensorKernel / ForceRegionKernel run after EsoPullStep, using
// t = step_count+1 for post-streaming physical-value semantics.
// Wall boundary functions (bounce_back.cuh) use load_physical_dir_esopull
// inside EsoPullStep (post-streaming, matching load_f_esopull output).
//
// NOTE: The wall boundary helpers use post-streaming reads (unlike Bouzidi)
// because they operate inside EsoPullStep on f[] already reconstructed
// by load_f_esopull. Replacing post-streaming f[i] with post-streaming
// f[opp(i)] is the correct half-way bounce-back for EsoPull.
//
// Verified: Kan99b K2 (60k steps, MRT) — bit-identical to double-buffer.
// ============================================================================
#ifndef CELERIS_STEP_AUX_KERNELS_CU
#define CELERIS_STEP_AUX_KERNELS_CU
#include "../streaming/esopull_semantic_helpers.cuh"
#include "../boundary/esopull_curved_helpers.cuh"
__device__ __forceinline__ float action_omega(const float* action, int body_id)
{
if (action == nullptr || body_id < 0) return 0.0f;
unsigned int base = (unsigned int)body_id * (unsigned int)OBS_BODY_SLOT_FLOATS;
return action[base + (unsigned int)(OBS_BODY_SLOT_FLOATS - 1)];
}
__global__ void CurvedBoundaryKernel(
fpxx* fi,
const unsigned int* cl_fluid_idx,
const unsigned char* cl_dir,
const float* cl_q,
const float* cl_rx,
const float* cl_ry,
const float* cl_rz,
const unsigned char* cl_fallback_class,
const int* cl_body_id,
const float* action,
float* obs,
unsigned int n_curved)
{
unsigned int tid = threadIdx.x + blockIdx.x * blockDim.x;
if (tid >= n_curved) return;
const unsigned long k_f = (unsigned long)cl_fluid_idx[tid];
const unsigned int dir = (unsigned int)cl_dir[tid];
const float q = cl_q[tid];
const int bid = cl_body_id[tid];
const float rx = cl_rx[tid];
const float ry = cl_ry[tid];
const unsigned char fallback_class = cl_fallback_class[tid];
const float omega = action_omega(action, bid);
#if DIM == 2
const float Uw = -omega * ry;
const float Vw = omega * rx;
(void)cl_rz;
apply_bouzidi_link(dir, q, k_f, fi, Uw, Vw, rx, ry, fallback_class, obs, bid);
#elif DIM == 3
const float rz = cl_rz[tid];
const float Uw = -omega * ry;
const float Vw = omega * rx;
const float Ww = 0.0f;
apply_bouzidi_link(dir, q, k_f, fi, Uw, Vw, Ww,
rx, ry, rz, fallback_class, obs, bid);
#endif
}
// End of CurvedBoundaryKernel
// ---------------------------------------------------------------------------
// PrepareEsoPullCurvedKernel -- read-only curved prep for EsoPull
//
// Reads donor populations from DDF via EsoPull semantic helpers,
// computes Bouzidi reflection + moving-wall, writes to intermediate buffer.
// Does NOT write directly to fi (paired Apply kernel does the scatter).
// ---------------------------------------------------------------------------
__global__ void PrepareEsoPullCurvedKernel(
const fpxx* fi,
const unsigned int* cl_fluid_idx,
const unsigned char* cl_dir,
const float* cl_q,
const float* cl_rx,
const float* cl_ry,
const unsigned char* cl_fallback_class,
const int* cl_body_id,
const float* action,
float* obs,
float* corr_value,
unsigned int* target_cell,
unsigned char* target_slot,
unsigned int n_curved,
unsigned long t)
{
unsigned int tid = threadIdx.x + blockIdx.x * blockDim.x;
if (tid >= n_curved) return;
const unsigned long k_f = (unsigned long)cl_fluid_idx[tid];
const unsigned int dir = (unsigned int)cl_dir[tid];
const unsigned int dir_opp = (unsigned int)opp_dir((int)dir);
const float q = cl_q[tid];
const float rx = cl_rx[tid];
const float ry = cl_ry[tid];
const unsigned char fallback = cl_fallback_class[tid];
const int bid = cl_body_id[tid];
unsigned int x, y;
coordinates(k_f, x, y);
unsigned long j_f[NQ];
compute_neighbors(x, y, j_f);
const unsigned long k_s = j_f[dir];
const float omega = action_omega(action, bid);
const float Uw = -omega * ry;
const float Vw = omega * rx;
const float f_toward = load_physical_dir_pre_streaming(k_f, dir, fi, j_f, t);
float f_reflected;
if (fallback == CURVED_FALLBACK_BOUZIDI) {
if (q < 0.5f) {
const unsigned long k_ff = j_f[dir_opp];
unsigned int xff, yff;
coordinates(k_ff, xff, yff);
unsigned long j_ff[NQ];
compute_neighbors(xff, yff, j_ff);
const float f_toward_ff = load_physical_dir_pre_streaming(k_ff, dir, fi, j_ff, t);
f_reflected = compute_bouzidi_reflection(f_toward, f_toward_ff, 0.0f, q, fallback);
} else {
const float f_opp_same = load_physical_dir_pre_streaming(k_f, dir_opp, fi, j_f, t);
f_reflected = compute_bouzidi_reflection(f_toward, 0.0f, f_opp_same, q, fallback);
}
} else {
f_reflected = compute_bouzidi_reflection(f_toward, 0.0f, 0.0f, q, fallback);
}
f_reflected += compute_moving_wall_addend(dir, q, fallback, Uw, Vw);
unsigned long dst_cell;
unsigned int dst_slot;
resolve_esopull_target(k_f, k_s, dir, t, dst_cell, dst_slot);
corr_value[tid] = f_reflected;
target_cell[tid] = (unsigned int)dst_cell;
target_slot[tid] = (unsigned char)dst_slot;
if (obs != nullptr) {
#if USE_DDF_SHIFTING
const float w_i = (float)d_w[dir];
const float fx = (float)d_cx[dir] * ((f_toward + w_i) + (f_reflected + w_i));
const float fy = (float)d_cy[dir] * ((f_toward + w_i) + (f_reflected + w_i));
#else
const float fx = (float)d_cx[dir] * (f_toward + f_reflected);
const float fy = (float)d_cy[dir] * (f_toward + f_reflected);
#endif
atomicAdd(&obs[obs_force_index(bid, 0)], fx);
atomicAdd(&obs[obs_force_index(bid, 1)], fy);
const float tz = rx * fy - ry * fx;
atomicAdd(&obs[obs_torque_index(bid, 0)], tz);
}
}
// ---------------------------------------------------------------------------
// ApplyEsoPullCurvedKernel -- scatter intermediate buffer to DDF
// Read-only on intermediate buffer, write-only on DDF. No geometry/physics.
// ---------------------------------------------------------------------------
__global__ void ApplyEsoPullCurvedKernel(
fpxx* fi,
const float* corr_value,
const unsigned int* target_cell,
const unsigned char* target_slot,
unsigned int n_curved)
{
unsigned int tid = threadIdx.x + blockIdx.x * blockDim.x;
if (tid >= n_curved) return;
store_ddf(fi,
index_f((unsigned long)target_cell[tid], (unsigned int)target_slot[tid]),
corr_value[tid]);
}
// ---------------------------------------------------------------------------
// SensorKernel — accumulate area-averaged velocity from DDF.
//
// Double-buffer mode (t == 0): fi[k,i] is the physical value of direction i
// at cell k. Direct raw reads are correct.
//
// EsoPull mode (t > 0): fi[k,i] stores the EsoPull backing slot, which may
// not be the physical direction i. Reconstruct physical DDF using the same
// load_f_esopull semantics (paired directions, parity-dependent slots).
// Runs after EsoPullStep, so the physical interpretation of fi follows the
// store_f_esopull contract: after store, t+1 parity determines physical layout.
// ---------------------------------------------------------------------------
__global__ void SensorKernel(
const fpxx* fi,
const unsigned short* flag,
const unsigned int* sensor_cells,
const int* sensor_obj_id,
float* obs,
unsigned int n_sensor,
unsigned long t) // 0 = double_buffer, >0 = esopull step count
{
unsigned int tid = threadIdx.x + blockIdx.x * blockDim.x;
if (tid >= n_sensor) return;
unsigned long k = (unsigned long)sensor_cells[tid];
int id_obj = sensor_obj_id[tid];
float f[NQ];
if (t == 0ul) {
// Double-buffer mode: raw slot = physical direction
for (int i = 0; i < NQ; i++)
f[i] = load_ddf(fi, index_f(k, (unsigned int)i));
} else {
// EsoPull mode: reconstruct physical values via shared helper
unsigned int x, y;
coordinates(k, x, y);
unsigned long j[NQ];
compute_neighbors(x, y, j);
load_physical_node_esopull(k, fi, j, t, f);
}
#if DIM == 2
float rho_n, ux, uy;
compute_rho_u(f, rho_n, ux, uy);
atomicAdd(&obs[obs_sensor_index(id_obj, 0)], ux);
atomicAdd(&obs[obs_sensor_index(id_obj, 1)], uy);
#elif DIM == 3
float rho_n, ux, uy, uz;
compute_rho_u(f, rho_n, ux, uy, uz);
atomicAdd(&obs[obs_sensor_index(id_obj, 0)], ux);
atomicAdd(&obs[obs_sensor_index(id_obj, 1)], uy);
atomicAdd(&obs[obs_sensor_index(id_obj, 2)], uz);
#endif
(void)flag;
}
// ---------------------------------------------------------------------------
// ForceRegionKernel — operator-split local Guo forcing correction
//
// Runs after the main collide+stream step. Applies a Guo forcing term to
// cells within a force_region footprint. This is an operator-split correction,
// not inline in OneStep's collide_dispatch.
//
// The Guo formula and c_tau = 1 - omega/2 conventions match collide_srt,
// collide_mrt, and collide_trt exactly.
// ---------------------------------------------------------------------------
__device__ __forceinline__ float action_force_x(const float* action, int body_id)
{
if (action == nullptr || body_id < 0) return 0.0f;
unsigned int base = (unsigned int)body_id * (unsigned int)OBS_BODY_SLOT_FLOATS;
return action[base + 0u];
}
__device__ __forceinline__ float action_force_y(const float* action, int body_id)
{
if (action == nullptr || body_id < 0) return 0.0f;
unsigned int base = (unsigned int)body_id * (unsigned int)OBS_BODY_SLOT_FLOATS;
return action[base + 1u];
}
__global__ void ForceRegionKernel(
fpxx* fi,
const unsigned short* flag,
const unsigned int* fr_cells,
const int* fr_obj_id,
const float* action,
unsigned int n_cells,
unsigned long t) // 0 = double_buffer, >0 = esopull step count
{
unsigned int tid = threadIdx.x + blockIdx.x * blockDim.x;
if (tid >= n_cells) return;
unsigned long k = (unsigned long)fr_cells[tid];
int bid = fr_obj_id[tid];
float fx = action_force_x(action, bid);
float fy = action_force_y(action, bid);
if (fx == 0.0f && fy == 0.0f) return;
if (!is_fluid(flag[k])) return;
// Read physical DDF with correct semantics for the current mode
float f[NQ];
unsigned int x, y;
coordinates(k, x, y);
unsigned long j[NQ];
compute_neighbors(x, y, j);
if (t == 0ul) {
// Double-buffer: raw load
for (int i = 0; i < NQ; i++)
f[i] = load_ddf(fi, index_f(k, (unsigned int)i));
} else {
// EsoPull: reconstruct physical f[] from backing slots
load_physical_node_esopull(k, fi, j, t, f);
}
#if DIM == 2
float rho_n, ux, uy;
compute_rho_u(f, rho_n, ux, uy);
float rho2 = 0.5f / rho_n;
ux = fmaf(fx, rho2, ux);
uy = fmaf(fy, rho2, uy);
float Fin[NQ];
compute_guo_forcing(ux, uy, fx, fy, Fin);
float omega = d_params.omega;
float c_tau = 1.0f - 0.5f * omega;
#pragma unroll
for (int i = 0; i < NQ; i++)
f[i] += c_tau * Fin[i];
#elif DIM == 3
float rho_n, ux, uy, uz;
compute_rho_u(f, rho_n, ux, uy, uz);
float rho2 = 0.5f / rho_n;
ux = fmaf(fx, rho2, ux);
uy = fmaf(fy, rho2, uy);
float Fin[NQ];
compute_guo_forcing(ux, uy, uz, fx, fy, 0.0f, Fin);
float omega = d_params.omega;
float c_tau = 1.0f - 0.5f * omega;
#pragma unroll
for (int i = 0; i < NQ; i++)
f[i] += c_tau * Fin[i];
#endif
// Write back with correct semantics
if (t == 0ul) {
#pragma unroll
for (int i = 0; i < NQ; i++)
store_ddf(fi, index_f(k, (unsigned int)i), f[i]);
} else {
// EsoPull: scatter modified physical f[] back to backing slots
store_physical_node_esopull(k, f, fi, j, t);
}
}
#endif // CELERIS_STEP_AUX_KERNELS_CU
@@ -0,0 +1,46 @@
// CelerisLab -- step/esopull_macro.cu
// MacroscopicEsoPullKernel -- GPU-side macroscopic diagnostics for EsoPull.
//
// Decodes the EsoPull backing layout into physical distributions, then
// computes rho/ux/uy. Output is SoA: rho_out[N], ux_out[N], uy_out[N].
// Included by kernel_v2.cu. No standalone compilation.
//
// This kernel is the sole path for macroscopic diagnostics in EsoPull mode.
// It uses the shared semantic helper layer (esopull_semantic_helpers.cuh).
// Do NOT attempt host-side physical DDF reconstruction for EsoPull --
// the backing layout scatters paired directions across neighbor cells.
//
// Verified: Kan99b K2 -- bit-identical to double-buffer get_macroscopic().
// ============================================================================
#ifndef CELERIS_STEP_ESOPULL_MACRO_CU
#define CELERIS_STEP_ESOPULL_MACRO_CU
__global__ void MacroscopicEsoPullKernel(
const fpxx* fi,
float* rho_out, float* ux_out, float* uy_out,
unsigned long t)
{
#if DIM == 2
unsigned int x, y; unsigned long k;
index_from_thread(x, y, k);
if (x >= (unsigned int)NX || y >= (unsigned int)NY) return;
unsigned long j[NQ];
compute_neighbors(x, y, j);
float f[NQ];
load_physical_node_esopull(k, fi, j, t, f);
float rho_n, ux, uy;
compute_rho_u(f, rho_n, ux, uy);
rho_out[k] = rho_n;
ux_out[k] = ux;
uy_out[k] = uy;
#elif DIM == 3
// TODO: D3Q19 semantic decode not implemented yet.
(void)fi; (void)rho_out; (void)ux_out; (void)uy_out; (void)t;
#endif
}
#endif // CELERIS_STEP_ESOPULL_MACRO_CU
Loaded 100 of 145 files, more files were not shown because too many files have changed in this diff. Show more