Undermind审计前，Cursor重构
This commit is contained in:
Frank14f
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user