48 lines
2.7 KiB
Plaintext
48 lines
2.7 KiB
Plaintext
---
|
|
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.
|