# 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)
