57 lines
3.5 KiB
Plaintext
57 lines
3.5 KiB
Plaintext
---
|
||
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.
|