CelerisLab/src/CelerisLab/configs/CONFIG.md

CelerisLab 配置说明

唯一配置入口：config_lbm.json
Python config.py 只负责读取和校验，不是配置位置。显式配置路径不存在时会报错，不会退回默认配置；仅未指定路径时按环境目录、工作目录、包内配置顺序查找。

---

grid — 网格

字段	类型	默认	允许值	说明
lattice_model	string	"D2Q9"	D2Q9, D3Q19	格子模型，决定维度和速度数量；Simulation 当前仅支持 D2Q9。D3Q19 保留供 descriptor / 局部算子研究，完整运行时在创建 GPU 上下文前明确拒绝
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 可能是历史版本。compiler.generate_config 会复制 kernel 源码到独立临时构建目录，并在副本中生成配置；不会改写包内头文件或 PTX。返回目录须显式传给 compile_kernel(build_dir=...)，编译结果与配置摘要均保存在该目录。Simulation 负责目录清理；直接使用编译器的调用者须调用 cleanup_build_dir()。跳过生成配置直接编译仓库中的 uniform.cu 属不受支持用法。

config_lbm.json
  ↓  load_lbm_config()
config.py:LBMConfig       (读取 + 校验)
  ↓  to_macros()
cuda/compiler.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 标记。

J1 on-site velocity planes (limited reference case)

Set method.y_wall_bc to "on_site_velocity" and method.wall_normal_velocity to V (default 0). This selects an x-periodic domain with physical planes through fluid rows y=1 and y=NY−2, H=NY−3. The bottom velocity is (0,V); the top is (physics.velocity,V). These are constant Cartesian velocities: positive V injects through the bottom and leaves through the top. The selected rows do not also receive halfway reflection. Initialization uses a linear tangential profile and V.

Supported only for D2Q9/SRT/FP32/unshifted/double_buffer without LES, objects or body forces. Boundary targets and the mode are fixed at construction; checkpoint restart requires matching targets. With the slot disabled this is an entire-plane Couette-throughflow reference. The default bounce_back mode and existing configurations retain their previous path.

Static centered bottom slot

Optional method.wall_slot_width is an integer W: 0 (default) keeps the above uniform planes; 2≤W≤NX enables a centered bottom slot and requires physics.velocity=0. The same support restrictions apply. Width and amplitude are fixed at construction and must match on checkpoint restart; older v3 checkpoints without this field mean W=0.

For W<NX, let c=(NX−1)/2, s=2(x−c)/W at integer x=0..NX−1. The bottom target is v=A*max(0,1-s*s)^2, where A=wall_normal_velocity is the continuous peak, not a renormalized discrete peak. This profile and its first derivative vanish at the edges. W=NX explicitly means uniform v=A, not this shaped profile. With equal unit area per node, requested Q is the sum of these bottom targets; the top target is uniform Q/NX (cfg.top_wall_normal_velocity). The sum is computed in host double precision; device targets are FP32. This balances requested volume, not actual density-weighted mass exactly.

Positive A injects from the bottom and exits through the top; negative A reverses both roles. Both are Cartesian y velocities; inward-normal velocity has the opposite sign at the top. The slot and its zero-velocity flanks share the same on-site y=1 plane. Initialization sets rho0, u=0 and linearly interpolates v between the two planes; it is not an assumed steady solution. This mode is static, single-level and flat; it does not support moving/curved slots. The finite-slot mode is experimental: the bounded W=16, A=±0.002 checks in research/j2-slot-2026-10-12/REVIEW.md exceeded the fixed late-time mass-drift tolerance. It is not yet validated for steady mass balance or long runs.

Opt-in top reservoir

Set method.top_wall_bc="reservoir" with on_site_velocity and physics.velocity=0 to fix the top density to physics.rho and tangential velocity to zero. The top Cartesian normal velocity is solved locally from known poststream populations; positive means outflow, negative means inflow. It may vary along x and is not constrained to the bottom requested Q/NX. The bottom slot/flanks and the supported lattice/collision/storage scope stay the same. This changes the physical top boundary condition.

The initializer still uses uniform Q/NX at the top as an initial guess, then the density reconstruction applies from the first step. Mode, reservoir density and tangential velocity are fixed at construction and checked on restart. Missing top_wall_bc in older configs/checkpoints means "velocity", which remains the default and preserves the previous two-velocity-boundary path. This reservoir mode is experimental. The bounded positive-slot test in research/j3-reservoir-2026-10-12/REVIEW.md passed its mass thresholds but failed the frozen full-field velocity convergence criterion; negative/zero cases and GPU restart validation were therefore not run. Long-run stability is unverified.