第一轮分析工作暂存

.gitignore

@@ -48,7 +48,7 @@ coverage.xml
 # Environments
 .env
 .venv
-env/
+# env/
 venv/
 ENV/
 env.bak/
@@ -91,3 +91,7 @@ tensorboard/
 .DS_Store
 .AppleDouble
 .LSOverride
+
+ref/
+docs/
+ParaView/

CelerisLab

@@ -1 +1 @@
-Subproject commit 2e052480c2a8a3c52e632eeac56348b57922ee7f
+Subproject commit d5b7e98750f6ba5f6da63df1ce69c4d97aaa3413

LegacyCelerisLab/__init__.py

@@ -0,0 +1,3 @@
+# CelerisLab/__init__.py
+
+from .driver import FlowField

LegacyCelerisLab/compiler.py

@@ -0,0 +1,87 @@
+# CelerisLab/kernels/compiler.py
+
+import subprocess
+import re
+import os
+
+from .utils import FlowFieldConfig, CudaConfig
+
+
+def kernel_path(file_name: str) -> str:
+    current_dir = os.path.dirname(os.path.abspath(__file__))
+    return os.path.join(current_dir, "kernels", file_name)
+
+
+def read_lines(file_path):
+    with open(file_path, "r") as file:
+        lines = file.readlines()
+    return lines
+
+
+def write_lines(file_path, lines):
+    with open(file_path, "w") as file:
+        file.writelines(lines)
+
+
+def modify_macro(lines, macro_name, new_value):
+    pattern = re.compile(rf"(#define\s+{macro_name}\s+)(\S+)")
+    for i, line in enumerate(lines):
+        if pattern.match(line):
+            lines[i] = pattern.sub(rf"\g<1>{new_value}", line)
+            break
+    return lines
+
+def modify_const(lines, const_name, new_type, new_value):
+    pattern = re.compile(rf"(__constant__\s+)(\S+\s+{const_name}\s*=\s*)([^;]+)(;)")
+    for i, line in enumerate(lines):
+        if pattern.match(line):
+            lines[i] = pattern.sub(rf"\g<1>{new_type} {const_name} = {new_value}\4", line)
+            break
+    return lines
+
+def compile_kernel():
+    subprocess.run(
+        [
+            "nvcc",
+            "-ptx",
+            kernel_path("kernel.cu"),
+            "-o",
+            kernel_path("kernel.ptx"),
+        ]
+    )
+
+def config_kernal(config_cuda: CudaConfig, config_field: FlowFieldConfig):
+    lines = read_lines(kernel_path("macros.h"))
+    lines = modify_macro(lines, "MULT_GPU", config_cuda.multi_gpu)
+    lines = modify_macro(lines, "NT", config_cuda.threads_per_block)
+    lines = modify_macro(lines, "X_1U", config_cuda.unit_dimensions[0])
+    lines = modify_macro(lines, "Y_1U", config_cuda.unit_dimensions[1])
+    lines = modify_macro(lines, "Z_1U", config_cuda.unit_dimensions[2])
+
+    if config_field.data_type == "FP32":
+        lb_type = "float"
+    else:
+        raise ValueError(f"Unsupported data type {config_field.data_type}.")
+    lines = modify_macro(lines, "LBtype", lb_type)
+    lines = modify_macro(lines, "UX", config_field.field_dim_in_U[0])
+    lines = modify_macro(lines, "UY", config_field.field_dim_in_U[1])
+    lines = modify_macro(lines, "UZ", config_field.field_dim_in_U[2])
+    lines = modify_macro(lines, "NX", config_field.field_dim_in_U[0] * config_cuda.unit_dimensions[0])
+    lines = modify_macro(lines, "NY", config_field.field_dim_in_U[1] * config_cuda.unit_dimensions[1])
+    lines = modify_macro(lines, "NZ", config_field.field_dim_in_U[2] * config_cuda.unit_dimensions[2])
+    lines = modify_macro(lines, "DIM", config_field.dimensionality)
+    lines = modify_macro(lines, "NQ", config_field.lattice)
+    lines = modify_macro(lines, "VIS", config_field.viscosity)
+    lines = modify_macro(lines, "U0", config_field.velocity)
+
+    write_lines(kernel_path("macros.h"), lines)
+
+def config_object(n_obj: int):
+    lines = read_lines(kernel_path("macros.h"))
+    lines = modify_macro(lines, "N_OBJS", n_obj)
+    write_lines(kernel_path("macros.h"), lines)
+
+def config_sensor(n_sen: int):
+    lines = read_lines(kernel_path("macros.h"))
+    lines = modify_macro(lines, "N_SENS", n_sen)
+    write_lines(kernel_path("macros.h"), lines)

LegacyCelerisLab/driver.py

@@ -0,0 +1,409 @@
+# CelerisLab/driver.py
+
+import pycuda.driver as cuda
+import numpy as np
+import struct
+from scipy.special import jv, expi
+from typing import List, Tuple, Union, Optional
+
+from . import utils
+from . import preprocess as preproc
+from . import compiler
+
+FLUID = 0b00000001
+SOLID = 0b00000010
+GAS = 0b00000100
+INTERFACE = 0b00001000
+SENSOR = 0b00010000
+V_TAYLOR = np.int32(1)
+
+class FlowField:
+    def __init__(
+        self,
+        field_config: utils.FlowFieldConfig,
+        cuda_config: utils.CudaConfig,
+        device_id: Union[int, List[int]] = None,
+    ):
+        self.field_config = field_config
+        self.cuda_config = cuda_config
+        cuda.init()
+
+        # Sanity checks
+        if cuda_config.multi_gpu:
+            if device_id is None or isinstance(device_id, int):
+                raise ValueError("Multi-GPU support requires a list of device IDs.")
+            # self.devices = [cuda.Device(id) for id in device_id]
+            raise NotImplementedError("Multi-GPU support is not implemented yet.")
+        else:
+            if isinstance(device_id, list):
+                if len(device_id) > 1:
+                    raise ValueError(
+                        "Single-GPU mode does not support multiple device IDs."
+                    )
+                device_id = device_id[0]
+            elif device_id is None:
+                device_id = 0
+            utils.check_cuda_device_availability(device_id)
+            self.device = cuda.Device(device_id)
+            self.context = self.device.make_context()
+
+        utils.check_cuda_capability(field_config, cuda_config, device_id)
+
+        # Config kernel
+        compiler.config_kernal(cuda_config, field_config)
+        compiler.config_object(int(0))
+        # compiler.config_sensor(int(0))
+
+        # Set constants
+        if field_config.data_type == "FP32":
+            self.DATA_TYPE = np.float32
+        else:
+            raise ValueError(f"Unsupported data type {field_config.data_type}.")
+
+        self.FIELD_SHAPE = tuple(
+            size * unit
+            for size, unit in zip(
+                field_config.field_dim_in_U, cuda_config.unit_dimensions
+            )
+        )
+        self.FIELD_SIZE = np.prod(self.FIELD_SHAPE)
+        self.LATTICE = field_config.lattice
+        self.DIM = field_config.dimensionality
+        if field_config.lattice == 9 and field_config.dimensionality == 2:
+            self.E = np.array(
+                [0, 0, 1, 0, 0, 1, -1, 0, 0, -1, 1, 1, -1, 1, -1, -1, 1, -1],
+                dtype=np.int32,
+            ).reshape(9, 2)
+            self.OPP = np.array([0, 3, 4, 1, 2, 7, 8, 5, 6], dtype=np.int32)
+            self.WW = np.array(
+                [4 / 9, 1 / 9, 1 / 9, 1 / 9, 1 / 9, 1 / 36, 1 / 36, 1 / 36, 1 / 36],
+                dtype=self.DATA_TYPE,
+            )
+        else:
+            raise NotImplementedError(
+                f"Unsupported lattice type {field_config.lattice} in {field_config.dimensionality} dimensions."
+            )
+
+        # Compile kernel
+        compiler.compile_kernel()
+        self.ptx = cuda.module_from_file(compiler.kernel_path("kernel.ptx"))
+        self.step = self.ptx.get_function("OneStep")
+        initflow = self.ptx.get_function("InitTubeFlow")
+
+        # Initialize memory
+        self.ddf = np.zeros(self.FIELD_SIZE * self.LATTICE, dtype=self.DATA_TYPE)
+        self.ddf_save = np.zeros(self.FIELD_SIZE * self.LATTICE, dtype=self.DATA_TYPE)
+        self.flag = np.ones(self.FIELD_SIZE, dtype=np.uint8)
+        self.indx = np.zeros(self.FIELD_SIZE, dtype=np.int32)
+        self.delta_curve = np.zeros(0, dtype=self.DATA_TYPE)
+        self.vortex_config = np.zeros(7, dtype=float)
+
+        self.ddf_gpu = cuda.mem_alloc(self.ddf.nbytes)
+        self.temp_gpu = cuda.mem_alloc(self.ddf.nbytes)
+        self.flag_gpu = cuda.mem_alloc(self.flag.nbytes)
+        self.indx_gpu = cuda.mem_alloc(self.indx.nbytes)
+        self.delta_gpu = cuda.mem_alloc(1)
+        self.vortex_gpu = cuda.mem_alloc(self.vortex_config.nbytes)
+        self.error_flag = np.zeros(1, dtype=np.uint32)
+        self.error_flag_gpu = cuda.mem_alloc(self.error_flag.nbytes)
+        self.last_error_flag = 0
+
+        self.objects = {}
+        self.action = np.zeros(0, dtype=self.DATA_TYPE)
+        self.obs = np.zeros(0, dtype=self.DATA_TYPE)
+
+        initflow(
+            self.flag_gpu,
+            self.ddf_gpu,
+            block=(self.cuda_config.threads_per_block, 1, 1),
+            grid=(
+                int(self.FIELD_SHAPE[0] / self.cuda_config.threads_per_block),
+                int(self.FIELD_SHAPE[1]),
+                int(self.FIELD_SHAPE[2]),
+            ),
+        )
+        cuda.memcpy_dtoh(self.flag, self.flag_gpu)
+        cuda.memcpy_dtoh(self.ddf, self.ddf_gpu)
+
+    def add_cylinder(self, center: Tuple[float, float, float], radius: float, id_obj: Optional[int] = None):
+        x_c, y_c, z_c = center
+
+        if (
+            x_c - radius <= 0
+            or x_c + radius >= self.FIELD_SHAPE[0] - 1
+            or y_c - radius <= 0
+            or y_c + radius >= self.FIELD_SHAPE[1] - 1
+        ):
+            raise ValueError("Cylinder is out of bounds.")
+
+        index = self.delta_curve.size if self.delta_curve.size > 0 else 0
+
+        if self.DATA_TYPE == np.float32:
+            id_object = np.int32(len(self.objects))
+            # max_id = max(self.objects.keys())
+        else:
+            raise ValueError(f"Unsupported data type {self.DATA_TYPE}.")
+        
+        for x in range(int(x_c - radius) - 1, int(x_c + radius) + 1):
+            for y in range(int(y_c - radius) - 1, int(y_c + radius) + 1):
+                if (x - x_c) ** 2 + (y - y_c) ** 2 < radius**2:
+                    k = x + y * self.FIELD_SHAPE[0]
+                    self.flag[k] = SOLID
+                    delta_temp = np.zeros(11, dtype=self.DATA_TYPE)
+                    delta_temp[0] = id_object.view(self.DATA_TYPE)
+                    for i in range(self.LATTICE):
+                        x_neb = x + self.E[i][0]
+                        y_neb = y + self.E[i][1]
+                        if (x_neb - x_c) ** 2 + (y_neb - y_c) ** 2 >= radius**2:
+                            self.flag[k] |= INTERFACE
+                            x_i, y_i = preproc.find_circle_intersection(
+                                x, y, x_neb, y_neb, x_c, y_c, radius
+                            )
+                            d_neb = np.sqrt((x_i - x_neb) ** 2 + (y_i - y_neb) ** 2)
+                            delta_temp[i] = d_neb / np.sqrt(
+                                self.E[i][0] ** 2 + self.E[i][1] ** 2
+                            )
+                    if self.flag[k] & INTERFACE:
+                        delta_temp[9] = (y_c - y) / radius
+                        delta_temp[10] = (x - x_c) / radius
+                        self.delta_curve = np.concatenate(
+                            (self.delta_curve, delta_temp)
+                        )
+                        self.indx[k] = index
+                        index += delta_temp.size
+
+        self.objects[id_object] = {
+            "type": "cylinder",
+            "center": center,
+            "radius": radius,
+        }
+
+        if hasattr(self, "delta_gpu"):
+            self.delta_gpu.free()
+        self.delta_gpu = cuda.mem_alloc(self.delta_curve.nbytes)
+
+        self.action = np.zeros(len(self.objects), dtype=self.DATA_TYPE)
+        if hasattr(self, "action_gpu"):
+            self.action_gpu.free()
+        self.action_gpu = cuda.mem_alloc(self.action.nbytes)
+
+        self.obs = np.zeros(len(self.objects) * self.DIM, dtype=self.DATA_TYPE)
+        if hasattr(self, "obs_gpu"):
+            self.obs_gpu.free()
+        self.obs_gpu = cuda.mem_alloc(self.obs.nbytes)
+
+        cuda.memcpy_htod(self.delta_gpu, self.delta_curve)
+        cuda.memcpy_htod(self.flag_gpu, self.flag)
+        cuda.memcpy_htod(self.indx_gpu, self.indx)
+
+        compiler.config_object(len(self.objects))
+        compiler.compile_kernel()
+        self.ptx = cuda.module_from_file(compiler.kernel_path("kernel.ptx"))
+        self.step = self.ptx.get_function("OneStep")
+
+    def add_sensor(self, center: Tuple[float, float, float], radius: float):
+        x_c, y_c, z_c = center
+
+        if (
+            x_c - radius <= 0
+            or x_c + radius >= self.FIELD_SHAPE[0] - 1
+            or y_c - radius <= 0
+            or y_c + radius >= self.FIELD_SHAPE[1] - 1
+        ):
+            raise ValueError("Sensor is out of bounds.")
+
+        id_object = len(self.objects)
+        for x in range(int(x_c - radius) - 1, int(x_c + radius) + 1):
+            for y in range(int(y_c - radius) - 1, int(y_c + radius) + 1):
+                if (x - x_c) ** 2 + (y - y_c) ** 2 < radius**2:
+                    k = x + y * self.FIELD_SHAPE[0]
+                    self.flag[k] |= SENSOR
+                    self.indx[k] = id_object
+
+        self.objects[id_object] = {
+            "type": "sensor",
+            "center": center,
+        }
+
+        self.action = np.zeros(len(self.objects), dtype=self.DATA_TYPE)
+        if hasattr(self, "action_gpu"):
+            self.action_gpu.free()
+        self.action_gpu = cuda.mem_alloc(self.action.nbytes)
+
+        self.obs = np.zeros(len(self.objects) * self.DIM, dtype=self.DATA_TYPE)
+        if hasattr(self, "force_gpu"):
+            self.obs_gpu.free()
+        self.obs_gpu = cuda.mem_alloc(self.obs.nbytes)
+
+        cuda.memcpy_htod(self.flag_gpu, self.flag)
+        cuda.memcpy_htod(self.indx_gpu, self.indx)
+
+        compiler.config_object(len(self.objects))
+        compiler.compile_kernel()
+        self.ptx = cuda.module_from_file(compiler.kernel_path("kernel.ptx"))
+        self.step = self.ptx.get_function("OneStep")
+
+    def add_vortex(self, center: Tuple[float, float, float], radius: float, strength: float, direction: float, type: str):
+        x_c, y_c, z_c = center
+
+        if (
+            x_c - radius <= 0
+            or x_c + radius >= self.FIELD_SHAPE[0] - 1
+            or y_c - radius <= 0
+            or y_c + radius >= self.FIELD_SHAPE[1] - 1
+        ):
+            raise ValueError("Vortex is out of bounds.")
+        
+        if type not in ["lamb", "oseen", "taylor"]:
+            raise ValueError("Vortex type" + type + " is not supported.")
+        
+        x = np.linspace(-x_c, self.FIELD_SHAPE[0] - 1 - x_c, self.FIELD_SHAPE[0])
+        y = np.linspace(-y_c, self.FIELD_SHAPE[1] - 1 - y_c, self.FIELD_SHAPE[1])
+        X, Y = np.meshgrid(x, y)
+        r = np.sqrt(X**2 + Y**2)
+        nu = self.field_config.viscosity
+        theta = np.arctan2(Y, X)
+        psi = np.zeros_like(r)
+
+        if type == "lamb":
+            b = 3.831705970207512
+            n = b / radius
+            u0 = strength
+            inside = r <= radius
+            outside = r > radius
+
+            psi[inside] = (2 * u0 / n / jv(0, b) * jv(1, n * r[inside]) - u0 * r[inside]) * np.sin(theta[inside])
+            psi[outside] = -u0 * radius**2 / r[outside] * np.sin(theta[outside])
+
+            u_vor = np.gradient(psi, axis=0)
+            v_vor = -np.gradient(psi, axis=1)
+            p_vor = -2 * (np.gradient(v_vor, axis=1) - np.gradient(u_vor, axis=0)) * psi - (u_vor**2 + v_vor**2) / 2
+        elif type == "oseen":
+            # 4 nu t = radius^2 / 4
+            kappa = 2 * np.pi * radius **2 * strength
+            u_vor = - kappa / (2 * np.pi * r) * (1 - np.exp(-4 * r**2 / radius**2)) * np.sin(theta)
+            v_vor = kappa / (2 * np.pi * r) * (1 - np.exp(-4 * r**2 / radius**2)) * np.cos(theta)
+            zeta = 4 * r**2 / radius**2
+            p_vor = -kappa**2 / 8 / np.pi**2 / r**2 * (-2 * zeta * (expi(-zeta) - expi(-2 * zeta)) + (1 - np.exp(-zeta))**2)
+        elif type == "taylor":
+            # 4 nu t = radius^2
+            M = strength * np.pi * radius**4 / 8 / nu
+            u_vor = - M * r * 4 * nu / radius**4 * np.exp(-r**2 / radius**2) * np.sin(theta)
+            v_vor = M * r * 4 * nu / radius**4 * np.exp(-r**2 / radius**2) * np.cos(theta)
+            p_vor = -4 * M**2 * nu**2 * np.exp(-2 * r**2 / radius**2) / np.pi**2 / radius**6
+
+        cuda.memcpy_dtoh(self.ddf, self.ddf_gpu)
+        ddf_temp = self.ddf.copy().reshape((self.LATTICE, self.FIELD_SHAPE[1], self.FIELD_SHAPE[0])).transpose(2, 1, 0)
+        u_ddf = ddf_temp[:, :, 1] + ddf_temp[:, :, 5] + ddf_temp[:, :, 8] - ddf_temp[:, :, 3] - ddf_temp[:, :, 6] - ddf_temp[:, :, 7]
+        v_ddf = ddf_temp[:, :, 2] + ddf_temp[:, :, 5] + ddf_temp[:, :, 6] - ddf_temp[:, :, 4] - ddf_temp[:, :, 7] - ddf_temp[:, :, 8]
+        p_ddf = np.sum(ddf_temp, axis=2) / 3
+
+        for i in range(self.FIELD_SHAPE[0]):
+            for j in range(self.FIELD_SHAPE[1]):
+                k = i + j * self.FIELD_SHAPE[0]
+                if (j == 0 or j == self.FIELD_SHAPE[1] - 1) or (i == 0 or i == self.FIELD_SHAPE[0] - 1):
+                    continue
+                else:
+                    for e in range(self.LATTICE):
+                        u = u_ddf[i, j] + u_vor[j, i]
+                        v = v_ddf[i, j] + v_vor[j, i]
+                        p = p_ddf[i, j] + p_vor[j, i]
+                        eu = self.E[e][0] * u + self.E[e][1] * v
+                        u2 = u ** 2 + v ** 2
+                        self.ddf[k + e * self.FIELD_SIZE] = self.WW[e] * (3 * p + 3 * eu + 4.5 * eu ** 2 - 1.5 * u2)
+            
+        cuda.memcpy_htod(self.ddf_gpu, self.ddf)
+
+    # def add_vortex_gpu(self, center: Tuple[float, float, float], radius: float, strength: float, direction: float, type: str):
+    #     x_c, y_c, z_c = center
+
+    #     if (
+    #         x_c - radius <= 0
+    #         or x_c + radius >= self.FIELD_SHAPE[0] - 1
+    #         or y_c - radius <= 0
+    #         or y_c + radius >= self.FIELD_SHAPE[1] - 1
+    #     ):
+    #         raise ValueError("Vortex is out of bounds.")
+        
+    #     if type not in ["lamb", "oseen", "taylor"]:
+    #         raise ValueError("Vortex type" + type + " is not supported.")
+        
+    #     add_vortex = self.ptx.get_function("AddVortex")
+
+    #     self.vortex_config[0:3] = np.array(center, dtype=float)
+    #     self.vortex_config[3] = radius
+    #     self.vortex_config[4] = strength
+    #     self.vortex_config[5] = direction
+    #     if type == "taylor":
+    #         self.vortex_config[6] = 
+
+    def run(self, num_steps: int, action_target: np.ndarray):
+        if (
+            action_target.size != len(self.objects)
+            or action_target.dtype != self.DATA_TYPE
+        ):
+            raise ValueError("action data type or size does not match the objects.")
+        elif len(self.objects) == 0:
+            raise ValueError("No objects have been added to the flow field.")
+
+        weight = 0.1
+        stream = cuda.Stream()
+        action_pinned = cuda.pagelocked_empty_like(self.action)
+        action_pinned[:] = self.action
+        obs_pinned = cuda.pagelocked_empty_like(self.obs)
+        self.error_flag[0] = 0
+        cuda.memcpy_htod(self.error_flag_gpu, self.error_flag)
+        self.obs[:] = 0
+        for i in range(num_steps):
+            action_pinned = (1 - weight) * action_pinned + weight * action_target
+            cuda.memcpy_htod_async(self.action_gpu, action_pinned, stream)
+            self.step(
+                self.flag_gpu,
+                self.ddf_gpu,
+                self.temp_gpu,
+                self.indx_gpu,
+                self.delta_gpu,
+                self.action_gpu,
+                self.obs_gpu,
+                self.error_flag_gpu,
+                block=(self.cuda_config.threads_per_block, 1, 1),
+                grid=(
+                    int(self.FIELD_SHAPE[0] / self.cuda_config.threads_per_block),
+                    int(self.FIELD_SHAPE[1]),
+                    int(self.FIELD_SHAPE[2]),
+                ),
+                stream=stream,
+            )
+            self.ddf_gpu, self.temp_gpu = self.temp_gpu, self.ddf_gpu
+            cuda.memcpy_dtoh_async(obs_pinned, self.obs_gpu, stream)
+            cuda.memset_d32_async(self.obs_gpu, 0, self.obs.size, stream)
+            self.obs += obs_pinned
+        stream.synchronize()
+        self.obs = (self.obs / num_steps).astype(self.DATA_TYPE)
+        cuda.memcpy_dtoh(self.error_flag, self.error_flag_gpu)
+        self.last_error_flag = int(self.error_flag[0])
+
+    def has_numeric_error(self) -> bool:
+        return bool(self.last_error_flag != 0)
+
+    def apply_ddf(self):
+        cuda.memcpy_htod(self.ddf_gpu, self.ddf)
+
+    def get_ddf(self):
+        cuda.memcpy_dtoh(self.ddf, self.ddf_gpu)
+
+    def save_ddf(self):
+        self.ddf_save = self.ddf.copy()
+
+    def restore_ddf(self):
+        self.ddf = self.ddf_save.copy()
+
+    def __del__(self):
+        # Shutdown order can invalidate current context before object cleanup.
+        ctx = getattr(self, "context", None)
+        if ctx is None:
+            return
+        try:
+            ctx.pop()
+        except Exception:
+            pass

LegacyCelerisLab/kernels/D2Q9.cu

@@ -0,0 +1,101 @@
+#include "macros.h"
+#include "const.h"
+
+__device__ void Index_lattice(int &x, int &y, int &k) {
+	// Only for D2
+	x = threadIdx.x + NT * blockIdx.x;
+	y = blockIdx.y;
+	k = y * NX + x;
+}
+
+__device__ void CollisionKernel(LBtype* g, LBtype* m) {
+	// Only for D2Q9
+	LBtype p, u, v;
+    LBtype niu = 1.0 / (0.5 + 3 * VIS);
+
+	u = (g[1]+g[5]+g[8]-g[3]-g[6]-g[7])/RHO;
+	v = (g[2]+g[5]+g[6]-g[4]-g[7]-g[8])/RHO;
+	p = (g[0]+g[1]+g[2]+g[3]+g[4]+g[5]+g[6]+g[7]+g[8])/3.0;
+
+	m[0]=   g[0]  +g[1]  +g[2]  +g[3]  +g[4]  +g[5]  +g[6]  +g[7]  +g[8];
+	m[1]=-4*g[0]  -g[1]  -g[2]  -g[3]  -g[4]+2*g[5]+2*g[6]+2*g[7]+2*g[8];
+	m[2]= 4*g[0]-2*g[1]-2*g[2]-2*g[3]-2*g[4]  +g[5]  +g[6]  +g[7]  +g[8];
+	m[3]=          g[1]         -g[3]         +g[5]  -g[6]  -g[7]  +g[8];
+	m[4]=       -2*g[1]       +2*g[3]         +g[5]  -g[6]  -g[7]  +g[8];
+	m[5]=                 g[2]         -g[4]  +g[5]  +g[6]  -g[7]  -g[8];
+	m[6]=              -2*g[2]       +2*g[4]  +g[5]  +g[6]  -g[7]  -g[8];
+	m[7]=          g[1]  -g[2]  +g[3]  -g[4];
+	m[8]=                                      g[5]  -g[6]  +g[7]  -g[8];	
+	
+	m[0]=1.00*( 3*p 	            -m[0]);
+	m[1]=1.20*(-6*p +3*RHO*(u*u+v*v)-m[1]);
+	m[2]=1.20*( 3*p -3*RHO*(u*u+v*v)-m[2]);
+	m[3]=1.00*( RHO*u               -m[3]);
+	m[4]=1.20*(-RHO*u               -m[4]);
+	m[5]=1.00*( RHO*v               -m[5]);
+	m[6]=1.20*(-RHO*v               -m[6]);
+	m[7]= niu*( RHO*(u*u-v*v)       -m[7]);
+	m[8]= niu*( RHO*u*v             -m[8]);
+
+	g[0]=g[0]+(  m[0]  -m[1]  +m[2]                                   )/ 9.0;
+	g[1]=g[1]+(4*m[0]  -m[1]-2*m[2]+6*m[3]-6*m[4]              +9*m[7])/36.0;
+	g[2]=g[2]+(4*m[0]  -m[1]-2*m[2]              +6*m[5]-6*m[6]-9*m[7])/36.0;
+	g[3]=g[3]+(4*m[0]  -m[1]-2*m[2]-6*m[3]+6*m[4]              +9*m[7])/36.0;
+	g[4]=g[4]+(4*m[0]  -m[1]-2*m[2]              -6*m[5]+6*m[6]-9*m[7])/36.0;
+	g[5]=g[5]+(4*m[0]+2*m[1]  +m[2]+6*m[3]+3*m[4]+6*m[5]+3*m[6]+9*m[8])/36.0;
+	g[6]=g[6]+(4*m[0]+2*m[1]  +m[2]-6*m[3]-3*m[4]+6*m[5]+3*m[6]-9*m[8])/36.0;
+	g[7]=g[7]+(4*m[0]+2*m[1]  +m[2]-6*m[3]-3*m[4]-6*m[5]-3*m[6]+9*m[8])/36.0;
+	g[8]=g[8]+(4*m[0]+2*m[1]  +m[2]+6*m[3]+3*m[4]-6*m[5]-3*m[6]-9*m[8])/36.0;
+}
+
+__device__ void ParabolicInlet(LBtype* f, LBtype* f_neb, LBtype y) {
+	LBtype p, u, v, yy;
+	LBtype feq1, feq5, feq8, feqn1, feqn5, feqn8;
+
+	p=(f_neb[0]+f_neb[1]+f_neb[2]+f_neb[3]+f_neb[4]+f_neb[5]+f_neb[6]+f_neb[7]+f_neb[8])/3.0;
+	yy=(y-0.5*(NY-1))/(NY-2.0);
+	u=U0*1.5*(1-4*yy*yy);
+	v=0.0;
+
+	feq1=(2*p+RHO*(2*u*u+2*u    -v*v)  )/ 6.0;
+	feq5=(  p+RHO*(  u*u+3*u*v+u+v*v+v))/12.0;
+	feq8=(  p+RHO*(  u*u-3*u*v+u+v*v-v))/12.0;
+
+	u=(f_neb[1]+f_neb[5]+f_neb[8]-f_neb[3]-f_neb[6]-f_neb[7])/RHO;
+	v=(f_neb[2]+f_neb[5]+f_neb[6]-f_neb[4]-f_neb[7]-f_neb[8])/RHO;
+
+	feqn1=(2*p+RHO*(2*u*u+2*u    -v*v)  )/ 6.0;
+	feqn5=(  p+RHO*(  u*u+3*u*v+u+v*v+v))/12.0;
+	feqn8=(  p+RHO*(  u*u-3*u*v+u+v*v-v))/12.0;
+
+	f[1]=f_neb[1]-feqn1+feq1;
+	f[5]=f_neb[5]-feqn5+feq5;
+	f[8]=f_neb[8]-feqn8+feq8;
+}
+
+__device__ void PressureOutlet(LBtype* f, LBtype* f_neb, LBtype y) {
+	// Edit to Parabolic Outlet temporarily
+	LBtype p, u, v, yy;	
+	LBtype feq3, feq6, feq7, feqn3, feqn6, feqn7;
+
+	p=0.0;
+
+	yy=(y-0.5*(NY-1))/(NY-2.0);
+	u=U0*1.5*(1-4*yy*yy);
+	v=0.0;
+
+	feq3=(2*p-RHO*(-2*u*u+2*u    +v*v)  )/ 6.0;
+	feq6=(  p+RHO*(   u*u-3*u*v-u+v*v+v))/12.0;
+	feq7=(  p+RHO*(   u*u+3*u*v-u+v*v-v))/12.0;
+
+	u=(f_neb[1]+f_neb[5]+f_neb[8]-f_neb[3]-f_neb[6]-f_neb[7])/RHO;
+	v=(f_neb[2]+f_neb[5]+f_neb[6]-f_neb[4]-f_neb[7]-f_neb[8])/RHO;
+	// p=(f_neb[0]+f_neb[1]+f_neb[2]+f_neb[3]+f_neb[4]+f_neb[5]+f_neb[6]+f_neb[7]+f_neb[8])/3.0;
+	feqn3=(2*p-RHO*(-2*u*u+2*u    +v*v)  )/ 6.0;
+	feqn6=(  p+RHO*(   u*u-3*u*v-u+v*v+v))/12.0;
+	feqn7=(  p+RHO*(   u*u+3*u*v-u+v*v-v))/12.0;
+
+	f[3]=f_neb[3]-feqn3+feq3;
+	f[6]=f_neb[6]-feqn6+feq6;
+	f[7]=f_neb[7]-feqn7+feq7;
+}

LegacyCelerisLab/kernels/const.h

@@ -0,0 +1,10 @@
+// CelerisLab/kernels/const.h
+
+#ifndef CONST_H
+#define CONST_H
+
+__constant__ int e[9][2] = {{0, 0}, {1, 0}, {0, 1}, {-1, 0}, {0, -1}, {1, 1}, {-1, 1}, {-1, -1}, {1, -1}};
+__constant__ int opp[9] = {0, 3, 4, 1, 2, 7, 8, 5, 6};
+__constant__ float w[9] = {4/9., 1/9., 1/9., 1/9., 1/9., 1/36., 1/36., 1/36., 1/36.};
+
+#endif

LegacyCelerisLab/kernels/kernel.cu

@@ -0,0 +1,234 @@
+// CelerisLab/kernels/kernel.cu
+
+#include <stdio.h>
+#include <stdint.h>
+#include <cuda.h>
+
+#include "macros.h"
+#include "const.h"
+#include "D2Q9.cu"
+
+extern "C"
+{
+	__global__ void OneStep(uint8_t *flag, LBtype *f, LBtype *f_temp, int32_t *indx, LBtype *delta, LBtype *action, LBtype *obs, uint32_t *error_flag)
+	{
+		__shared__ LBtype f_share[NT * NQ];
+		__shared__ LBtype obs_share[(N_OBJS * DIM > 0) ? N_OBJS * DIM : 1];
+
+		int x, y, k;
+		LBtype g[NQ], m[NQ];
+		Index_lattice(x, y, k); // Only for D2
+		int totalCells = NX * NY;
+		int id = indx[k];
+
+		for (int i = 0; i < NQ; i++)
+		{
+			f_share[threadIdx.x + i * NT] = f[k + i * totalCells];
+		}
+		for (int i = threadIdx.x; i < N_OBJS * DIM; i += NT)
+		{
+			obs_share[i] = 0;
+		}
+
+		__syncthreads();
+
+		for (int i = 0; i < NQ; i++)
+		{
+			g[i] = f_share[threadIdx.x + i * NT];
+		}
+
+		if (flag[k] & FLUID)
+		{
+			CollisionKernel(g, m);
+
+			for (int i = 0; i < NQ; i++)
+			{
+				if (isnan((double)g[i]) || isinf((double)g[i]))
+				{
+					atomicOr(error_flag, (uint32_t)1);
+				}
+				f_share[threadIdx.x + i * NT] = g[i];
+			}
+		}
+		else if (flag[k] & SOLID)
+		{
+			if (x == 0)
+			{
+				for (int i = 0; i < NQ; i++)
+				{
+					m[i] = f_share[threadIdx.x + i * NT + 1];
+				}
+				ParabolicInlet(g, m, y);
+			}
+			else if (x == NX - 1)
+			{
+				for (int i = 0; i < NQ; i++)
+				{
+					m[i] = f_share[threadIdx.x + i * NT - 1];
+				}
+				PressureOutlet(g, m, y);
+			}
+
+			for (int i = 0; i < NQ; i++)
+			{
+				if (isnan((double)g[i]) || isinf((double)g[i]))
+				{
+					atomicOr(error_flag, (uint32_t)1);
+				}
+				f_share[threadIdx.x + i * NT] = g[i];
+			}
+		}
+
+		__syncthreads();
+
+		for (int i = 0; i < NQ; i++)
+		{
+			int x_neb = x + e[i][0];
+			int y_neb = y + e[i][1];
+
+			if (y != 0 && y != NY - 1)
+			{
+				if ((y == 1 && y_neb == 0) || (y == NY - 2 && y_neb == NY - 1))
+				{
+					f_temp[k + opp[i] * totalCells] = f_share[threadIdx.x + i * NT];
+				}
+				else
+				{
+					int k_neb = ((y_neb * NX + x_neb) + totalCells) % totalCells;
+					f_temp[k_neb + i * totalCells] = f_share[threadIdx.x + i * NT];
+				}
+			}
+		}
+
+		__syncthreads();
+
+		if (flag[k] & SOLID && flag[k] & INTERFACE)
+		{
+			LBtype Uw, Vw;
+			int id_obj = *reinterpret_cast<int *>(&delta[id]);
+			Uw = action[id_obj] * delta[id + 9];
+			Vw = action[id_obj] * delta[id + 10];
+
+			int x_neb, y_neb, k_neb;
+			for (int i = 1; i < 9; i++)
+			{
+				x_neb = x + e[i][0];
+				y_neb = y + e[i][1];
+				k_neb = x_neb + y_neb * NX;
+				if (flag[k_neb] & FLUID)
+				{
+					LBtype q = delta[id + i];
+					int k_neb2 = (y + 2 * e[i][1]) * NX + (x + 2 * e[i][0]);
+					LBtype temp = 6 * w[i] * (e[i][0] * Uw + e[i][1] * Vw);
+					f_temp[k_neb + i * totalCells] = (q * f_temp[k + opp[i] * totalCells] \
+						+ (1 - q) * f_temp[k_neb + opp[i] * totalCells] \
+						+ q * f_temp[k_neb2 + i * totalCells] + temp) / (1 + q);
+					f_temp[k + i * totalCells] = temp * Uw;
+					k_neb2 = (y - e[i][1]) * NX + (x - e[i][0]);
+					f_temp[k_neb2 + i * totalCells] = temp * Vw;
+
+					temp = f_temp[k_neb + i * totalCells] + f_temp[k + opp[i] * totalCells];
+					k_neb2 = (y - e[i][1]) * NX + (x - e[i][0]);
+					atomicAdd(&obs_share[DIM * id_obj], -temp * e[i][0] + f_temp[k + i * totalCells]);
+					atomicAdd(&obs_share[DIM * id_obj + 1], -temp * e[i][1] + f_temp[k_neb2 + i * totalCells]);
+				}
+			}
+		}
+		if (flag[k] & SENSOR)
+		{
+			LBtype u, v;
+			u = (g[1] + g[5] + g[8] - g[3] - g[6] - g[7]) / RHO;
+			v = (g[2] + g[5] + g[6] - g[4] - g[7] - g[8]) / RHO;
+			if (isnan((double)u) || isinf((double)u) || isnan((double)v) || isinf((double)v))
+			{
+				atomicOr(error_flag, (uint32_t)1);
+			}
+			atomicAdd(&obs_share[DIM * id], u);
+			atomicAdd(&obs_share[DIM * id + 1], v);
+		}
+
+		__syncthreads();
+
+		for (int i = threadIdx.x; i < N_OBJS * DIM; i += NT)
+		{
+			atomicAdd(&obs[i], obs_share[i]);
+		}
+	}
+
+	__global__ void InitTubeFlow(uint8_t *flag, LBtype *f)
+	{
+		__shared__ LBtype f_share[NT * NQ];
+		__shared__ uint8_t flag_share[NT];
+		int x, y, k;
+		LBtype u;
+		Index_lattice(x, y, k);
+		int totalCells = NX * NY;
+
+		flag_share[threadIdx.x] = flag[k];
+		for (int i = 0; i < NQ; i++)
+		{
+			f_share[threadIdx.x + i * NT] = f[k + i * totalCells];
+		}
+
+		__syncthreads();
+
+		u = U0 * 1.5 * (1 - 4 * (y - 0.5 * (NY - 1)) * (y - 0.5 * (NY - 1)) / ((NY - 2) * (NY - 2)));
+		if (y == 0 || y == NY - 1 || x == 0 || x == NX - 1)
+		{
+			flag_share[threadIdx.x] = SOLID;
+			for (int i = 0; i < NQ; i++)
+			{
+				f_share[threadIdx.x + i * NT] = 0;
+			}
+		}
+		else
+		{
+			flag_share[threadIdx.x] = FLUID;
+			for (int i = 0; i < NQ; i++)
+			{
+				f_share[threadIdx.x + i * NT] = w[i] * RHO * (3 * e[i][0] * u + \
+					4.5 * e[i][0] * e[i][0] * u * u - 1.5 * u * u);
+			}
+		}
+
+		__syncthreads();
+
+		flag[k] = flag_share[threadIdx.x];
+		for (int i = 0; i < NQ; i++)
+		{
+			f[k + i * totalCells] = f_share[threadIdx.x + i * NT];
+		}
+	}
+
+	// __global__ void AddVortex(LBtype *f, int32_t *config)
+	// {
+	// 	__shared__ LBtype f_share[NT * NQ];
+	// 	int x, y, k;
+	// 	LBtype u, v, u_vor, v_vor;
+	// 	Index_lattice(x, y, k);
+	// 	int totalCells = NX * NY;
+
+	// 	for (int i = 0; i < NQ; i++)
+	// 	{
+	// 		f_share[threadIdx.x + i * NT] = f[k + i * totalCells];
+	// 	}
+
+	// 	__syncthreads();
+
+	// 	u = f_share[threadIdx.x + 1 * NT] - f_share[threadIdx.x + 3 * NT] + f_share[threadIdx.x + 5 * NT] - f_share[threadIdx.x + 6 * NT] - f_share[threadIdx.x + 7 * NT] + f_share[threadIdx.x + 8 * NT];
+	// 	v = f_share[threadIdx.x + 2 * NT] - f_share[threadIdx.x + 4 * NT] + f_share[threadIdx.x + 5 * NT] + f_share[threadIdx.x + 6 * NT] - f_share[threadIdx.x + 7 * NT] - f_share[threadIdx.x + 8 * NT];
+
+	// 	if type & V_TAYLOR
+	// 	{
+	// 		u_vor = -2 * PI * U0 * sin(2 * PI * x / NX) * sin(2 * PI * y / NY);
+	// 		v_vor = 2 * PI * U0 * cos(2 * PI * x / NX) * cos(2 * PI * y / NY);
+	// 	}
+	// 	else
+	// 	{
+	// 		u_vor = 0;
+	// 		v_vor = 0;
+	// 	}
+
+
+	// }
+}

LegacyCelerisLab/kernels/macros.h

@@ -0,0 +1,37 @@
+// CelerisLab/kernels/macros.h
+
+// cuda parameters
+#define MULT_GPU False
+#define NT 128
+#define X_1U 128
+#define Y_1U 32
+#define Z_1U 1
+
+// flow parameters
+#define LBtype float
+#define UX 10
+#define UY 16
+#define UZ 1
+#define NX 1280
+#define NY 512
+#define NZ 1
+#define DIM 2
+#define NQ 9
+#define VIS 0.008
+#define RHO 1.0
+#define U0 0.02
+
+// constants
+#define PI 3.141592653589793238
+#define FLUID       0b00000001
+#define SOLID       0b00000010
+#define GAS         0b00000100
+#define INTERFACE   0b00001000
+#define SENSOR      0b00010000
+
+// vortex type
+#define V_TAYLOR    0b00000001
+
+// variables
+#define N_OBJS 7
+// #define N_SENS 2

LegacyCelerisLab/kernels/preproc.cu

@@ -0,0 +1,2 @@
+#include "macros.h"
+#include "const.h"

LegacyCelerisLab/preprocess.py

@@ -0,0 +1,40 @@
+# CelerisLab/preprocess.py
+
+import math
+import numpy as np
+from typing import Tuple
+
+FLUID = 0b00000001
+SOLID = 0b00000010
+GAS = 0b00000100
+INTERFACE = 0b00001000
+SENSOR = 0b00010000
+
+
+def find_circle_intersection(x, y, x_neb, y_neb, xc, yc, r0):
+    dx, dy = x_neb - x, y_neb - y
+    a = dx ** 2 + dy ** 2
+    b = 2 * (dx * (x - xc) + dy * (y - yc))
+    c = (x - xc) ** 2 + (y - yc) ** 2 - r0 ** 2
+    det = b ** 2 - 4 * a * c
+
+    if det < 0:
+        return None
+
+    t1 = (-b + math.sqrt(det)) / (2 * a)
+    t2 = (-b - math.sqrt(det)) / (2 * a)
+
+    if 0 <= t1 <= 1:
+        return x + t1 * dx, y + t1 * dy
+    elif 0 <= t2 <= 1:
+        return x + t2 * dx, y + t2 * dy
+    else:
+        return None 
+    
+def find_sensor_area(radius):
+    area = 0
+    for i in range(np.floor(-radius), np.ceil(radius)):
+        for j in range(np.floor(-radius), np.ceil(radius)):
+            if i ** 2 + j ** 2 <= radius ** 2:
+                area += 1
+    return area

LegacyCelerisLab/utils.py

@@ -0,0 +1,256 @@
+# CelerisLab/utils.py
+
+import pycuda.driver as cuda
+import subprocess
+import json
+
+from typing import NamedTuple, Optional, List, Tuple, Union
+
+
+class CudaDeviceInfo(NamedTuple):
+    name: str
+    compute_capability: str
+    multiprocessors: int
+    total_global_memory: int
+    max_shared_memory_per_block: int
+    max_threads_per_block: int
+    max_blocks_per_multiprocessor: int
+    device_interconnect: Optional[str] = None
+
+
+class FlowFieldConfig(NamedTuple):
+    data_type: str
+    dimensionality: int
+    lattice: int
+    field_dim_in_U: Tuple[int, int, int]
+    viscosity: float
+    velocity: float
+    boundary_conditions: Tuple[str, str, str, str, str, str]
+
+
+class CudaConfig(NamedTuple):
+    multi_gpu: bool
+    gpu_connection: str
+    required_cuda_capability: str
+    threads_per_block: int
+    unit_dimensions: Tuple[int, int, int]
+
+
+def check_cuda_device_availability(device_id=0):
+    if cuda.Device.count() == 0:
+        raise RuntimeError("No CUDA device is available.")
+
+    if device_id < 0 or device_id >= cuda.Device.count():
+        raise ValueError(
+            f"Invalid device_id {device_id}. Must be between 0 and {cuda.Device.count() - 1}."
+        )
+
+    try:
+        subprocess.check_output(["nvidia-smi", "--version"])
+    except subprocess.CalledProcessError:
+        raise RuntimeError("nvidia-smi is not available or not installed correctly.")
+
+
+def query_cuda_device_info(device_id=0) -> CudaDeviceInfo:
+    check_cuda_device_availability(device_id)
+
+    try:
+        output = subprocess.check_output(
+            ["nvidia-smi", "-q", "-d", "TOPOLOGY", "-i", str(device_id)], text=True
+        )
+        if "NVLink" in output:
+            device_interconnect = "NVLink"
+        elif "PCIe" in output:
+            device_interconnect = "PCIe"
+        else:
+            device_interconnect = "Unknown"
+    except Exception as e:
+        device_interconnect = None
+
+    device = cuda.Device(device_id)
+
+    return CudaDeviceInfo(
+        name=device.name(),
+        compute_capability=f"{device.compute_capability()[0]}.{device.compute_capability()[1]}",
+        multiprocessors=device.get_attribute(
+            cuda.device_attribute.MULTIPROCESSOR_COUNT
+        ),
+        total_global_memory=device.total_memory(),
+        max_shared_memory_per_block=device.get_attribute(
+            cuda.device_attribute.MAX_SHARED_MEMORY_PER_BLOCK
+        ),
+        max_threads_per_block=device.get_attribute(
+            cuda.device_attribute.MAX_THREADS_PER_BLOCK
+        ),
+        max_blocks_per_multiprocessor=device.get_attribute(
+            cuda.device_attribute.MAX_BLOCKS_PER_MULTIPROCESSOR
+        ),
+        device_interconnect=device_interconnect,
+    )
+
+
+def load_flow_field_config(config_path: str) -> FlowFieldConfig:
+    try:
+        with open(config_path, "r") as file:
+            config = json.load(file)
+
+        required_keys = [
+            "data_type",
+            "dimensionality",
+            "lattice",
+            "field_dim_in_U",
+            "viscosity",
+            "boundary_conditions",
+        ]
+        if not all(key in config for key in required_keys):
+            raise ValueError("Missing required configuration items.")
+
+        if config["data_type"] not in ["FP32", "FP64"]:
+            raise ValueError("Data type must be either FP32 or FP64.")
+
+        if config["dimensionality"] not in [2, 3]:
+            raise ValueError("Dimensionality must be either 2 or 3.")
+
+        if config["dimensionality"] == 2 and config["field_dim_in_U"][2] != 1:
+            raise ValueError(
+                "Field dimensions must be 1 in the third dimension for 2D simulations."
+            )
+
+        if config["lattice"] not in [9]:
+            raise ValueError("Lattice must be either 9 or 19.")
+
+        boundary_conditions = tuple(
+            condition
+            for key in ["x", "y", "z"]
+            for condition in config["boundary_conditions"].get(key, [])
+        )
+        if len(boundary_conditions) != 6:
+            raise ValueError("Boundary conditions must contain exactly six elements.")
+
+        return FlowFieldConfig(
+            data_type=config["data_type"],
+            dimensionality=config["dimensionality"],
+            lattice=config["lattice"],
+            field_dim_in_U=tuple(config["field_dim_in_U"]),
+            viscosity=config["viscosity"],
+            velocity=config["velocity"],
+            boundary_conditions=boundary_conditions,
+        )
+    except Exception as e:
+        raise RuntimeError(f"Failed to load or parse the flow field configuration: {e}")
+
+
+def load_cuda_config(config_path: str) -> CudaConfig:
+    try:
+        with open(config_path, "r") as file:
+            config = json.load(file)
+
+        required_keys = [
+            "multi_gpu",
+            "gpu_connection",
+            "required_cuda_capability",
+            "threads_per_block",
+            "X_1U",
+            "Y_1U",
+            "Z_1U",
+        ]
+
+        if not all(key in config for key in required_keys):
+            raise ValueError("Missing required configuration items.")
+
+        return CudaConfig(
+            multi_gpu=config["multi_gpu"],
+            gpu_connection=config["gpu_connection"],
+            required_cuda_capability=config["required_cuda_capability"],
+            threads_per_block=config["threads_per_block"],
+            unit_dimensions=(config["X_1U"], config["Y_1U"], config["Z_1U"]),
+        )
+    except Exception as e:
+        raise RuntimeError(f"Failed to load or parse the CUDA configuration: {e}")
+
+
+def check_cuda_capability(
+    field_config: FlowFieldConfig,
+    cuda_config: CudaConfig,
+    device_id: Union[int, List[int]] = None,
+):
+    SAFE_FACTOR = 0.8
+
+    if cuda_config.multi_gpu:
+        if device_id is None or isinstance(device_id, int):
+            raise ValueError("Multi-GPU support requires a list of device IDs.")
+        raise NotImplementedError("Multi-GPU support is not implemented yet.")
+    else:
+        if isinstance(device_id, list):
+            if len(device_id) > 1:
+                raise ValueError(
+                    "Single-GPU mode does not support multiple device IDs."
+                )
+            device_id = device_id[0]
+        elif device_id is None:
+            device_id = 0
+        device_info = query_cuda_device_info(device_id)
+
+        if device_info.compute_capability != cuda_config.required_cuda_capability:
+            raise ValueError(
+                f"Device {device_info.name} has compute capability {device_info.compute_capability}, but {cuda_config.required_cuda_capability} is required."
+            )
+
+        field_size = sum(
+            size * unit
+            for size, unit in zip(
+                field_config.field_dim_in_U, cuda_config.unit_dimensions
+            )
+        )
+        if (
+            device_info.total_global_memory * SAFE_FACTOR
+            < calc_field_memory_consumption(
+                field_size,
+                field_config.dimensionality,
+                field_config.lattice,
+                field_config.data_type,
+            )
+        ):
+            raise ValueError(
+                f"Device {device_info.name} does not have enough memory to store the flow field."
+            )
+
+        if (
+            device_info.max_threads_per_block * SAFE_FACTOR
+            < cuda_config.threads_per_block
+        ):
+            raise ValueError(
+                f"Device {device_info.name} does not have enough threads per block to run the simulation."
+            )
+
+        block_size = cuda_config.threads_per_block
+        if (
+            device_info.max_shared_memory_per_block * SAFE_FACTOR
+            < 2
+            * calc_field_memory_consumption(
+                block_size,
+                field_config.dimensionality,
+                field_config.lattice,
+                field_config.data_type,
+            )
+        ):
+            raise ValueError(
+                f"Device {device_info.name} does not have enough shared memory per block to run the simulation."
+            )
+
+
+def calc_field_memory_consumption(
+    field_size: int, dimensionality: int, directions: int, data_type: str
+) -> int:
+    if data_type == "FP32":
+        data_size = 4
+    elif data_type == "FP64":
+        data_size = 8
+    else:
+        raise ValueError(f"Unsupported data type {data_type}.")
+
+    return (
+        field_size * directions * data_size * 2
+        + field_size * dimensionality * data_size
+        + field_size
+    )

README.md

@@ -1,8 +1,18 @@
 # DynamisLab
 
-**Machine Learning for Computational Fluid Dynamics**
+**Machine Learning meets Numerical Simulation**
 
-DynamisLab is a research framework for applying reinforcement learning and machine learning techniques to computational fluid dynamics problems. Built on top of [CelerisLab](https://github.com/frank14f/CelerisLab), it provides standardized environments and training pipelines for active flow control tasks.
+DynamisLab is a research framework for combining machine learning techniques with numerical simulations. Built on top of [CelerisLab](https://github.com/frank14f/CelerisLab), it provides standardized environments and training pipelines for various ML + CFD/Physics projects.
+
+## Current Projects
+
+### 🎯 FlowStealth
+
+Deep Reinforcement Learning for Active Flow Control, focusing on:
+- **Flow Stealth**: Drag reduction and flow signature minimization
+- **Flow Illusion**: Manipulating flow patterns for deception and control
+- **Methods**: DRL (PPO) + CFD (Lattice Boltzmann Method)
+- **Location**: `src/flow_stealth/`
 
 ## Features
 
@@ -10,25 +20,27 @@ DynamisLab is a research framework for applying reinforcement learning and machi
 - 🤖 **RL Integration**: Ready-to-use with Stable-Baselines3 and other RL libraries
 - 🚀 **GPU Acceleration**: Leverages CelerisLab's CUDA-accelerated LBM solver
 - 📊 **Experiment Tracking**: Built-in TensorBoard integration
-- 🔧 **Modular Design**: Clean separation of environments, configs, and training scripts
-- 📦 **Standard Structure**: Follows Python packaging best practices (src layout)
+- 🔧 **Modular Design**: Organized by research projects
+- 📦 **Standard Structure**: Follows Python packaging best practices
 
 ## Project Structure
 
 ```
-DynamisLabNew/
-├── src/                            # Source code (src layout)
+DynamisLab/
+├── src/                            # Source code (organized by project)
+│   └── flow_stealth/               # FlowStealth: DRL + CFD Active Control
 │       ├── __init__.py
 │       ├── config.py               # Configuration management
 │       └── environments/           # Gymnasium environments
 │           ├── __init__.py
 │           └── cfd_env.py          # CFD flow control environment
 ├── scripts/                        # Training and evaluation scripts
-│   └── train_ppo.py                # PPO training script
+│   └── train_ppo.py                # PPO training script for FlowStealth
 ├── configs/                        # Configuration files
 │   ├── config_cuda.json            # CUDA settings
 │   ├── config_flowfield.json       # Flow field parameters
 │   └── config_gym.json             # Environment settings
+├── CelerisLab/                     # CelerisLab submodule (GPU-accelerated CFD)
 ├── models/                         # Trained model checkpoints (gitignored)
 ├── output/                         # Training data and results (gitignored)
 ├── tensorboard/                    # TensorBoard logs (gitignored)
@@ -117,8 +129,8 @@ Then open http://localhost:6006 in your browser.
 ### Using the Environment Programmatically
 
 ```python
-from environments import CFDFlowControlEnv
-from config import load_celeris_configs
+from flow_stealth.environments import CFDFlowControlEnv
+from flow_stealth.config import load_celeris_configs
 
 # Load configurations
 config_cuda, config_field = load_celeris_configs()
@@ -231,15 +243,22 @@ The main environment for active flow control around a cylinder.
 - Follow PEP 8 style guide
 - Use type hints for function signatures
 - Document classes and functions with docstrings
-- Keep environments in `src/dynamis/environments/`
+- Organize projects under `src/` (e.g., `src/flow_stealth/`)
 - Keep training scripts in `scripts/`
 - Use `config.py` for all path and configuration management
 
-### Adding a New Environment
+### Adding a New Project
 
-1. Create new environment class in `src/dynamis/environments/`
+1. Create new project directory in `src/` (e.g., `src/my_new_project/`)
+2. Add `__init__.py`, `config.py`, and project-specific modules
+3. Create environments in `src/my_new_project/environments/`
+4. Create corresponding training scripts in `scripts/`
+
+### Adding a New Environment to FlowStealth
+
+1. Create new environment class in `src/flow_stealth/environments/`
 2. Inherit from `gym.Env`
-3. Register in `src/dynamis/environments/__init__.py`
+3. Register in `src/flow_stealth/environments/__init__.py`
 4. Create corresponding training script in `scripts/`
 
 ### Running Tests

archive/analysis_crossre_scripts/diagnose_equivariance.py

@@ -0,0 +1,350 @@
+# analysis_crossre/scripts/diagnose_equivariance.py
+"""Phase A2-A3: diagnose PPO control-law equivariance under G operator.
+
+Usage::
+
+    conda run -n pycuda_3_10 python diagnose_equivariance.py --re 100 --device 0
+
+    conda run -n pycuda_3_10 python diagnose_equivariance.py --re all --device 0
+
+Output per Re: ``output/analysis_crossre/diagnostic/equivariance_re{re}.json``
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from typing import Dict, List, Tuple
+
+import numpy as np
+
+_PROJ = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+if _PROJ not in sys.path:
+    sys.path.insert(0, _PROJ)
+from LegacyCelerisLab import FlowField  # noqa: E402
+from LegacyCelerisLab import utils as legacy_utils  # noqa: E402
+
+from utils import (
+    action_to_physical,
+    compute_dimensionless,
+    apply_G_x,
+    apply_G_alpha,
+    load_ppo_model,
+    nu_from_re,
+    load_legacy_configs,
+    build_karman_cloak_env,
+    add_pinball,
+    build_observation,
+    scale_action,
+)
+from cfg import (
+    CONFIG_DIR,
+    OUTPUT_DIR,
+    MODEL_DIR,
+    SAMPLE_INTERVAL,
+    FIFO_LEN,
+    CONV_LEN,
+    S_DIM,
+    A_DIM,
+    ACTION_SCALE,
+    ACTION_BIAS,
+    U0,
+    RE_CASES_TRAIN,
+    RE_LABEL_MAP,
+)
+
+DATA_TYPE = np.float32
+
+
+def diagnose_one_re(re_code: int, ppo_device: int, cfd_device: int, output_root: str) -> dict:
+    """Run equivariance diagnosis for one Re case."""
+    os.makedirs(output_root, exist_ok=True)
+
+    nu = nu_from_re(re_code, u0=U0)
+    mu = 2.0 / re_code
+    label = RE_LABEL_MAP.get(re_code, f"Re{re_code}")
+    print(f"\n{'='*60}")
+    print(f"Diagnosing: {label}   nu={nu:.6f}   mu={mu:.6f}")
+    print(f"{'='*60}")
+
+    # Build full environment (dist + sensors + pinball)
+    cuda_cfg, field_cfg = load_legacy_configs(CONFIG_DIR)
+    field_cfg = field_cfg._replace(viscosity=float(nu))
+    ff = FlowField(field_cfg, cuda_cfg, device_id=cfd_device)
+
+    # Stabilize and get to controlled state
+    target_states, _ = build_karman_cloak_env(
+        ff, u0=U0, l0=20.0, sample_interval=SAMPLE_INTERVAL,
+        fifo_len=FIFO_LEN, data_type=DATA_TYPE,
+    )
+    norm = add_pinball(
+        ff, l0=20.0, u0=U0, sample_interval=SAMPLE_INTERVAL,
+        fifo_len=FIFO_LEN, data_type=DATA_TYPE,
+        action_bias=ACTION_BIAS,
+    )
+
+    # Load PPO model
+    model_path = None
+    for rc, mn in RE_CASES_TRAIN:
+        if rc == re_code:
+            model_path = os.path.join(MODEL_DIR, "old", f"{mn}.zip")
+            break
+    if model_path is None or not os.path.isfile(model_path):
+        return {"re_code": re_code, "error": f"No model for Re{re_code}"}
+
+    model = load_ppo_model(model_path, device=f"cuda:{ppo_device}")
+    model.set_random_seed(0)
+
+    # Collect rollout data with PPO
+    ff.restore_ddf()
+    ff.apply_ddf()
+
+    # Bias FIFO
+    bias_action = scale_action(
+        np.zeros(3, dtype=np.float32),
+        scale=ACTION_SCALE, bias=ACTION_BIAS, u0=U0, n_total_bodies=7,
+    )
+    from collections import deque
+    fifo = deque(maxlen=FIFO_LEN)
+    for _ in range(FIFO_LEN):
+        ff.context.push()
+        try:
+            ff.run(SAMPLE_INTERVAL, bias_action)
+        finally:
+            ff.context.pop()
+        fifo.append(ff.obs.copy()[2:14])
+
+    n_steps = 150
+    obs_hist = np.zeros((n_steps, 12), dtype=np.float64)
+    alpha_hist = np.zeros((n_steps, 3), dtype=np.float64)
+    obs = np.zeros(S_DIM, dtype=np.float32)
+
+    for step in range(n_steps):
+        action, _ = model.predict(obs, deterministic=True)
+        action = action.astype(np.float32).flatten()
+
+        # Convert to physical
+        action_arr = scale_action(
+            action, scale=ACTION_SCALE, bias=ACTION_BIAS,
+            u0=U0, n_total_bodies=7,
+        )
+        ff.context.push()
+        try:
+            ff.run(SAMPLE_INTERVAL, action_arr)
+        finally:
+            ff.context.pop()
+
+        obs_slice = ff.obs.copy()[2:14]
+        fifo.append(obs_slice)
+        alpha = action_to_physical(
+            action.reshape(1, 3), scale=ACTION_SCALE, bias=ACTION_BIAS, u0=U0,
+        ).flatten()
+
+        obs_hist[step] = obs_slice
+        alpha_hist[step] = alpha
+        obs = build_observation(obs_slice, norm)
+
+    del ff
+
+    # ---- Equivariance diagnosis ----
+    dim = compute_dimensionless(obs_hist[:, 0:6], obs_hist[:, 6:12], u0=U0, d=20.0)
+
+    # Compute memory terms
+    a_prev = np.zeros_like(alpha_hist)
+    a_prev2 = np.zeros_like(alpha_hist)
+    a_prev[1:] = alpha_hist[:-1]
+    a_prev2[2:] = alpha_hist[:-2]
+
+    # Diagnostic 1: front bias check (mean of alpha_F)
+    mean_alpha_F = float(np.mean(alpha_hist[:, 0]))
+    std_alpha_F = float(np.std(alpha_hist[:, 0]))
+    front_bias_score = abs(mean_alpha_F) / (std_alpha_F + 1e-12)
+
+    # Diagnostic 2: check front equivariance
+    # For each point, compute PPO(Gx) by feeding G-transformed obs through model
+    eq_front_errors = []
+    eq_exchange_b_errors = []
+    eq_exchange_t_errors = []
+    eq_front_noise_floor = []
+
+    for t in range(2, n_steps):
+        # Get original obs and Gx
+        Gx = apply_G_x(
+            dim["u_hat_B"][t:t+1], dim["u_hat_C"][t:t+1], dim["u_hat_T"][t:t+1],
+            dim["v_hat_B"][t:t+1], dim["v_hat_C"][t:t+1], dim["v_hat_T"][t:t+1],
+            dim["Cd_F"][t:t+1], dim["Cd_T"][t:t+1], dim["Cd_B"][t:t+1],
+            dim["Cl_F"][t:t+1], dim["Cl_T"][t:t+1], dim["Cl_B"][t:t+1],
+            a_prev[t:t+1, 0], a_prev[t:t+1, 2], a_prev[t:t+1, 1],
+            a_prev2[t:t+1, 0] - a_prev[t:t+1, 0],
+            a_prev2[t:t+1, 2] - a_prev[t:t+1, 2],
+            a_prev2[t:t+1, 1] - a_prev[t:t+1, 1],
+        )
+
+        # Build Gx observation for PPO: we need the normalized obs
+        # The Gx in raw sensor/force space requires inverting the dimensionless transform
+        # Actually easier: compute what PPO would predict for the G state
+        # by transforming the raw obs and feeding it
+
+        # Build raw obs corresponding to Gx
+        raw_Gx = np.zeros(12, dtype=np.float64)
+        # Sensors: reorder + sign flip
+        # Original raw: [s0_ux, s0_uy, s1_ux, s1_uy, s2_ux, s2_uy] = top, center, bottom
+        # G: bottom->top, center->center, top->bottom
+        raw_Gx[0] = obs_hist[t, 4]   # s0_ux <- s2_ux (bottom -> top, streamwise no sign)
+        raw_Gx[1] = -obs_hist[t, 5]  # s0_uy <- -s2_uy (bottom -> top, cross sign flip)
+        raw_Gx[2] = obs_hist[t, 2]   # s1_ux maintains (center)
+        raw_Gx[3] = -obs_hist[t, 3]  # s1_uy = -s1_uy (center cross sign flip)
+        raw_Gx[4] = obs_hist[t, 0]   # s2_ux <- s0_ux (top -> bottom)
+        raw_Gx[5] = -obs_hist[t, 1]  # s2_uy <- -s0_uy (top -> bottom, cross sign flip)
+        # Forces: reorder + sign
+        # ordering: [front_fx, front_fy, bottom_fx, bottom_fy, top_fx, top_fy]
+        # G: front_fx -> front_fx (no sign), front_fy -> -front_fy
+        #    bottom <-> top
+        raw_Gx[6] = obs_hist[t, 6]    # front_fx unchanged
+        raw_Gx[7] = -obs_hist[t, 7]   # front_fy sign flip
+        raw_Gx[8] = obs_hist[t, 10]   # bottom_fx <- top_fx
+        raw_Gx[9] = -obs_hist[t, 11]  # bottom_fy <- -top_fy
+        raw_Gx[10] = obs_hist[t, 8]   # top_fx <- bottom_fx
+        raw_Gx[11] = -obs_hist[t, 9]  # top_fy <- -bottom_fy
+
+        # Build normalized PPO observation from Gx
+        obs_Gx = build_observation(raw_Gx, norm)
+
+        # Predict action for Gx
+        action_Gx, _ = model.predict(obs_Gx, deterministic=True)
+        action_Gx = action_Gx.astype(np.float32).flatten()
+        alpha_Gx = action_to_physical(
+            action_Gx.reshape(1, 3), scale=ACTION_SCALE, bias=ACTION_BIAS, u0=U0,
+        ).flatten()
+
+        # What equivariance says Gx should produce (with CORRECTED G)
+        # G([aF, aT, aB]) = [-aF, -aB, -aT]
+        alpha_Gx_expected = apply_G_alpha(alpha_hist[t])
+
+        # Front error: PPO(Gx)[0] should == G(PPO(x))[0] = -aF(x)
+        eq_front_errors.append(abs(float(alpha_Gx[0]) - float(alpha_Gx_expected[0])))
+
+        # Rear error (CORRECTED): PPO(Gx)[1] should == G(PPO(x))[1] = -aT(x)
+        # PPO(Gx)[2] should == G(PPO(x))[2] = -aB(x)
+        # Previously this incorrectly checked alpha_B(x) == alpha_T(Gx)
+        eq_exchange_b_errors.append(abs(float(alpha_Gx[1]) - float(alpha_Gx_expected[1])))
+        eq_exchange_t_errors.append(abs(float(alpha_Gx[2]) - float(alpha_Gx_expected[2])))
+
+        # Noise floor: difference between same-state replicate predictions
+        # (we approximate by checking prediction consistency)
+        action2, _ = model.predict(obs_Gx, deterministic=True)
+        alpha_Gx2 = action_to_physical(
+            action2.reshape(1, 3), scale=ACTION_SCALE, bias=ACTION_BIAS, u0=U0,
+        ).flatten()
+        eq_front_noise_floor.append(abs(float(alpha_Gx2[0]) - float(alpha_Gx[0])))
+
+    eq_front_errors = np.array(eq_front_errors)
+    eq_exchange_b = np.array(eq_exchange_b_errors)
+    eq_exchange_t = np.array(eq_exchange_t_errors)
+    eq_noise = np.array(eq_front_noise_floor)
+
+    # Scale equivariance errors by action range for relative measure
+    alpha_range = float(np.max(np.abs(alpha_hist[2:])))
+    rel_front_err = float(np.mean(eq_front_errors) / (alpha_range + 1e-12))
+    rel_exchange_b_err = float(np.mean(eq_exchange_b) / (alpha_range + 1e-12))
+    rel_exchange_t_err = float(np.mean(eq_exchange_t) / (alpha_range + 1e-12))
+
+    # Combined rear error (max of bottom and top)
+    rel_exchange_err = max(rel_exchange_b_err, rel_exchange_t_err)
+
+    # Diagnostic 3: cross-correlation between alpha_T and -alpha_B
+    if len(alpha_hist) > 10:
+        # After initial transient
+        tail = n_steps // 2
+        corr_TB = float(np.corrcoef(alpha_hist[tail:, 2], -alpha_hist[tail:, 1])[0, 1])
+    else:
+        corr_TB = float("nan")
+
+    result = {
+        "re_code": re_code,
+        "mu": mu,
+        "n_samples": n_steps,
+        "alpha_range": alpha_range,
+        "front_bias": {
+            "mean_alpha_F": mean_alpha_F,
+            "std_alpha_F": std_alpha_F,
+            "bias_over_std": front_bias_score,
+            "bias_significant": front_bias_score > 2.0,
+        },
+        "equivariance_front": {
+            "mean_abs_error": float(np.mean(eq_front_errors)),
+            "max_abs_error": float(np.max(eq_front_errors)),
+            "relative_error": rel_front_err,
+            "noise_floor": float(np.mean(eq_noise)),
+            "signal_to_noise": float(np.mean(eq_front_errors) / (np.mean(eq_noise) + 1e-12)),
+        },
+        "equivariance_rear_bottom": {
+            "mean_abs_error": float(np.mean(eq_exchange_b)),
+            "max_abs_error": float(np.max(eq_exchange_b)),
+            "relative_error": rel_exchange_b_err,
+        },
+        "equivariance_rear_top": {
+            "mean_abs_error": float(np.mean(eq_exchange_t)),
+            "max_abs_error": float(np.max(eq_exchange_t)),
+            "relative_error": rel_exchange_t_err,
+        },
+        "top_bottom_correlation": {
+            "corr_alphaT_vs_negAlphaB": corr_TB,
+        },
+        "equivariance_verdict": "PASS" if (rel_front_err < 0.20 and rel_exchange_err < 0.20) else "REVIEW",
+    }
+
+    print(f"  Front bias: mean_alpha_F={mean_alpha_F:.6f} |bias|/std={front_bias_score:.3f}")
+    print(f"  Front equiv err: mean={np.mean(eq_front_errors):.6f} rel={rel_front_err:.3%}")
+    print(f"  Rear-bot err:    mean={np.mean(eq_exchange_b):.6f} rel={rel_exchange_b_err:.3%}")
+    print(f"  Rear-top err:    mean={np.mean(eq_exchange_t):.6f} rel={rel_exchange_t_err:.3%}")
+    print(f"  T vs -B corr: {corr_TB:.4f}")
+    print(f"  Verdict: {result['equivariance_verdict']}")
+
+    with open(os.path.join(output_root, f"equivariance_re{re_code}.json"), "w") as f:
+        json.dump(result, f, indent=2)
+    print(f"  Saved to {output_root}/equivariance_re{re_code}.json")
+
+    return result
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Equivariance diagnosis for PPO cloak control")
+    ap.add_argument("--re", type=str, default="all",
+                    help='Re case: 50,100,200,400, or "all"')
+    ap.add_argument("--device", type=int, default=0, help="GPU device for PPO model")
+    ap.add_argument("--cfd-device", type=int, default=2, help="GPU device for CFD simulation")
+    args = ap.parse_args()
+
+    if args.re.lower() == "all":
+        re_list = [rc for rc, _ in RE_CASES_TRAIN]
+    else:
+        re_list = [int(args.re)]
+
+    # Store device args for use in diagnose_one_re
+    device_id = args.device
+    cfd_device = args.cfd_device
+
+    diag_root = os.path.join(OUTPUT_DIR, "diagnostic")
+    os.makedirs(diag_root, exist_ok=True)
+
+    all_results = []
+    for re_code in re_list:
+        res = diagnose_one_re(re_code, device_id, cfd_device, diag_root)
+        all_results.append(res)
+
+    summary = {
+        "summary": {
+            "equivariance_verdicts": {r["re_code"]: r.get("equivariance_verdict", "ERROR")
+                                      for r in all_results}
+        },
+        "details": all_results,
+    }
+    with open(os.path.join(diag_root, "equivariance_summary.json"), "w") as f:
+        json.dump(summary, f, indent=2)
+    print(f"\nSummary saved to {diag_root}/equivariance_summary.json")
+
+
+if __name__ == "__main__":
+    main()

archive/analysis_crossre_scripts/phase2_ablation.py

@@ -0,0 +1,439 @@
+# analysis_crossre/scripts/phase2_ablation.py
+"""Ablation runner: v2 baseline -> v2.1 -> v2.2 -> v2.3 -> v2.4.
+
+Each version differs by exactly one change from the previous.
+Run specific versions via --mode.
+
+Usage::
+
+    conda run -n pycuda_3_10 python phase2_ablation.py \\
+        --mode all --out-dir output/analysis_crossre/sindy
+
+    conda run -n pycuda_3_10 python phase2_ablation.py \\
+        --mode v21 --out-dir output/analysis_crossre/sindy
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from typing import Dict, List, Tuple
+
+import numpy as np
+
+from utils import (
+    action_to_physical,
+    compute_dimensionless,
+    compute_physical_symbols,
+    fit_channel,
+    print_control_law,
+)
+from cfg import (
+    OUTPUT_DIR,
+    RE_CASES_TRAIN,
+    ACTION_SCALE,
+    ACTION_BIAS,
+    U0,
+)
+
+THRESHOLDS = [0.0, 0.001, 0.002, 0.005, 0.01, 0.015, 0.02, 0.03, 0.05, 0.1]
+
+
+def load_case_data(re_code: int) -> Tuple:
+    case_dir = os.path.join(OUTPUT_DIR, f"re{re_code}")
+    npz_path = os.path.join(case_dir, "controlled.npz")
+    if not os.path.isfile(npz_path):
+        raise FileNotFoundError(f"Missing {npz_path}")
+    data = np.load(npz_path)
+    sensors = data["sensors"].astype(np.float64)
+    forces = data["forces"].astype(np.float64)
+    actions_norm = data["actions"].astype(np.float64)
+    rewards = data.get("rewards", np.zeros(sensors.shape[0])).astype(np.float64)
+    actions_phys = action_to_physical(
+        actions_norm, scale=ACTION_SCALE, bias=ACTION_BIAS, u0=U0)
+    mu = 2.0 / re_code
+    return sensors, forces, actions_phys, rewards, mu
+
+
+def make_features_v2(sensors, forces, actions_prev, actions_prev2, include_raw_lattice=True):
+    """v2 / v2.1 features: raw lattice physical symbols."""
+    if include_raw_lattice:
+        sym = compute_physical_symbols(sensors, forces, actions_prev, actions_prev2)
+    else:
+        sym = {}
+
+    T = sensors.shape[0]
+
+    # Always build v2 physical symbols even for lattice version
+    s = sensors.astype(np.float64)
+    f = forces.astype(np.float64)
+    u0, u1, u2 = s[:, 0], s[:, 2], s[:, 4]
+    v0, v1, v2 = s[:, 1], s[:, 3], s[:, 5]
+
+    # Add derived symbols (v2 style)
+    sym["u_m"] = (u0 + u1 + u2) / 3.0
+    sym["u_a"] = (u2 - u0) / 2.0
+    sym["u_c"] = u1.copy()
+    sym["u_curv"] = u0 - 2.0 * u1 + u2
+    sym["v_m"] = (v0 + v1 + v2) / 3.0
+    sym["v_a"] = (v2 - v0) / 2.0
+    sym["v_c"] = v1.copy()
+    sym["v_curv"] = v0 - 2.0 * v1 + v2
+    sym["sin_ua"] = np.sin(np.pi * sym["u_a"])
+    sym["cos_ua"] = np.cos(np.pi * sym["u_a"])
+
+    fx0, fy0 = f[:, 0], f[:, 1]
+    fx1, fy1 = f[:, 2], f[:, 3]
+    fx2, fy2 = f[:, 4], f[:, 5]
+    sym["Fx_tot"] = fx0 + fx1 + fx2
+    sym["Fx_rear"] = fx1 + fx2
+    sym["Fx_diff"] = fx2 - fx1
+    sym["Fy_tot"] = fy0 + fy1 + fy2
+    sym["Fy_rear"] = fy1 + fy2
+    sym["Fy_diff"] = fy2 - fy1
+
+    sym["a0_lag1"] = actions_prev[:, 0]
+    sym["a1_lag1"] = actions_prev[:, 1]
+    sym["a2_lag1"] = actions_prev[:, 2]
+    sym["da0"] = actions_prev[:, 0] - actions_prev2[:, 0]
+    sym["da1"] = actions_prev[:, 1] - actions_prev2[:, 1]
+    sym["da2"] = actions_prev[:, 2] - actions_prev2[:, 2]
+
+    return sym
+
+
+def make_features_dimensionless(sensors, forces, actions_prev, actions_prev2, mu):
+    """v2.2 features: fully dimensionless."""
+    dim = compute_dimensionless(sensors, forces, u0=U0, d=20.0)
+    T = actions_prev.shape[0]
+
+    # Nondim actions: alpha = omega_phys / U0
+    T = actions_prev.shape[0]
+    a_prev = np.zeros((T, 3), dtype=np.float64)
+    a_prev2 = np.zeros((T, 3), dtype=np.float64)
+    a_prev[1:] = actions_prev[1:] / U0
+    a_prev2[2:] = actions_prev2[2:] / U0
+    da = a_prev - a_prev2
+
+    # Sensor (nondim)
+    u_B, u_C, u_T = dim["u_hat_B"], dim["u_hat_C"], dim["u_hat_T"]
+    v_B, v_C, v_T = dim["v_hat_B"], dim["v_hat_C"], dim["v_hat_T"]
+
+    sym = {}
+    sym["u_m"] = (u_B + u_C + u_T) / 3.0
+    sym["u_a"] = (u_T - u_B) / 2.0
+    sym["u_c"] = u_C.copy()
+    sym["u_curv"] = u_B - 2.0 * u_C + u_T
+    sym["v_m"] = (v_B + v_C + v_T) / 3.0
+    sym["v_a"] = (v_T - v_B) / 2.0
+    sym["v_c"] = v_C.copy()
+    sym["v_curv"] = v_B - 2.0 * v_C + v_T
+    sym["sin_ua"] = np.sin(np.pi * sym["u_a"])
+    sym["cos_ua"] = np.cos(np.pi * sym["u_a"])
+
+    # Force (nondim Cd/Cl)
+    sym["Cd_tot"] = dim["Cd_F"] + dim["Cd_T"] + dim["Cd_B"]
+    sym["Cd_rear"] = dim["Cd_T"] + dim["Cd_B"]
+    sym["Cd_diff"] = dim["Cd_T"] - dim["Cd_B"]
+    sym["Cl_tot"] = dim["Cl_F"] + dim["Cl_T"] + dim["Cl_B"]
+    sym["Cl_rear"] = dim["Cl_T"] + dim["Cl_B"]
+    sym["Cl_diff"] = dim["Cl_T"] - dim["Cl_B"]
+
+    # Memory (nondim alpha)
+    sym["a0_lag1"] = a_prev[:, 0]  # front
+    sym["a1_lag1"] = a_prev[:, 1]  # bottom
+    sym["a2_lag1"] = a_prev[:, 2]  # top
+    sym["da0"] = da[:, 0]
+    sym["da1"] = da[:, 1]
+    sym["da2"] = da[:, 2]
+
+    # Mu modulation
+    sym["mu"] = np.full(T, mu, dtype=np.float64)
+    sym["mu_u_a"] = sym["u_a"] * mu
+    sym["mu_v_a"] = sym["v_a"] * mu
+    sym["mu_Cd_tot"] = sym["Cd_tot"] * mu
+    sym["mu_Cl_diff"] = sym["Cl_diff"] * mu
+
+    return sym
+
+
+def build_theta(sym, feature_keys, add_bias=True):
+    """Build feature matrix from symbol dict."""
+    T = sym[feature_keys[0]].shape[0]
+    cols = []
+    if add_bias:
+        cols.append(np.ones(T, dtype=np.float64))
+    for k in feature_keys:
+        cols.append(sym[k])
+    return np.column_stack(cols)
+
+
+# Feature set definitions
+V2_BASE_KEYS = [
+    "u_m", "u_a", "u_c", "u_curv", "v_a", "v_curv",
+    "Fx_tot", "Fx_rear", "Fx_diff", "Fy_tot", "Fy_diff",
+    "sin_ua", "cos_ua",
+    "a0_lag1", "a1_lag1", "a2_lag1",
+    "da0", "da1", "da2",
+]
+
+V2_WITH_MU = V2_BASE_KEYS + [
+    "mu", "mu_u_a", "mu_v_a", "mu_Cd_tot", "mu_Cl_diff",
+]
+
+V2DIM_KEYS = [
+    "u_m", "u_a", "u_c", "u_curv", "v_a", "v_curv",
+    "Cd_tot", "Cd_rear", "Cd_diff", "Cl_tot", "Cl_diff",
+    "sin_ua", "cos_ua",
+    "a0_lag1", "a1_lag1", "a2_lag1",
+    "da0", "da1", "da2",
+    "mu", "mu_u_a", "mu_v_a", "mu_Cd_tot", "mu_Cl_diff",
+]
+
+
+def build_dataset(re_codes, mode, use_mu=True, use_mu_nondim=True):
+    """Build dataset for given mode.
+
+    Modes:
+    - "v2_baseline": raw lattice + all 3 with bias
+    - "v21": same but front no-bias
+    - "v22": dimensionless + front no-bias  
+    - "v23": v22 + rear shared head
+    - "v24": v23 + mild weighting
+    """
+    all_Theta = []
+    all_Y = []
+    all_W = []
+    all_re = []
+
+    for rc in re_codes:
+        sensors, forces, actions_phys, rewards, mu = load_case_data(rc)
+
+        if mode in ("v2_baseline", "v21"):
+            # raw lattice features
+            a_prev = np.zeros_like(actions_phys)
+            a_prev2 = np.zeros_like(actions_phys)
+            a_prev[1:] = actions_phys[:-1]
+            a_prev2[2:] = actions_phys[:-2]
+            sym = make_features_v2(sensors, forces, a_prev, a_prev2)
+            feature_keys = V2_WITH_MU if use_mu else V2_BASE_KEYS
+            sym["mu"] = np.full(sensors.shape[0], mu, dtype=np.float64)
+            sym["mu_u_a"] = sym["u_a"] * mu
+            sym["mu_v_a"] = sym["v_a"] * mu
+            if use_mu:
+                # Add mu modulated forces
+                sym["mu_Cd_tot"] = sym["Fx_tot"] * mu
+                sym["mu_Cl_diff"] = sym["Fy_diff"] * mu
+            Y = actions_phys.copy()
+        else:
+            # dimensionless features
+            a_prev_d = np.zeros_like(actions_phys)
+            a_prev2_d = np.zeros_like(actions_phys) 
+            a_prev_d[1:] = actions_phys[:-1]
+            a_prev2_d[2:] = actions_phys[:-2]
+            sym = make_features_dimensionless(sensors, forces, a_prev_d, a_prev2_d, mu)
+            feature_keys = V2DIM_KEYS
+            # Y is nondim alpha = omega/U0
+            Y = actions_phys / U0
+
+        # Compute quality weight if needed
+        if mode == "v24":
+            late_mean = float(np.mean(rewards[-80:]))
+            weight = np.clip(0.3 + 0.7 * late_mean / 0.7, 0.2, 1.0)
+            W = np.full(sensors.shape[0], weight, dtype=np.float64)
+        else:
+            W = np.ones(sensors.shape[0], dtype=np.float64)
+
+        # Store for stacking (will trim warmup later)
+        all_Theta.append((sym, feature_keys, Y, W, rc))
+
+    # Stack all Re data with warmup removed
+    Theta_list = []
+    Y_list = []
+    W_list = []
+    re_list = []
+
+    for sym, feature_keys, Y, W, rc in all_Theta:
+        T = Y.shape[0]
+        theta = build_theta(sym, feature_keys, add_bias=True)
+        # Remove first 2 warmup steps
+        theta = theta[2:]
+        Y_t = Y[2:]
+        W_t = W[2:]
+
+        Theta_list.append(theta)
+        Y_list.append(Y_t)
+        W_list.append(W_t)
+        re_list.append(np.full(theta.shape[0], rc, dtype=np.int64))
+
+    Theta_stacked = np.vstack(Theta_list)
+    Y_stacked = np.vstack(Y_list)
+    W_stacked = np.concatenate(W_list)
+    Re_stacked = np.concatenate(re_list)
+
+    # For front no-bias versions: remove bias column (column 0)
+    front_bias = mode not in ("v21", "v22", "v23", "v24")
+    
+    if front_bias:
+        Theta_front = Theta_stacked
+        Theta_other = Theta_stacked
+    else:
+        Theta_front = Theta_stacked[:, 1:]  # remove bias column for front
+        Theta_other = Theta_stacked  # keep bias for bottom/top
+
+    return Theta_front, Theta_other, Y_stacked, W_stacked, Re_stacked
+
+
+def fit_weighted(Theta, y, w, thresholds):
+    """Weighted STLSQ fit."""
+    import pysindy as ps
+    std = np.sqrt(np.average((Theta - np.average(Theta, axis=0, weights=w))**2, 
+                              axis=0, weights=w))
+    std = np.where(std < 1e-8, 1.0, std)
+    Theta_s = Theta / std
+    best = None
+    rows = []
+    for th in thresholds:
+        opt = ps.STLSQ(threshold=th, alpha=1e-4, max_iter=25)
+        opt.fit(Theta_s, y, sample_weight=w)
+        coef = np.asarray(opt.coef_, dtype=np.float64).flatten() / std
+        y_pred = Theta @ coef
+        y_mean = np.average(y, weights=w)
+        ssr = np.sum(w * (y - y_pred)**2)
+        sst = np.sum(w * (y - y_mean)**2) + 1e-12
+        r2 = 1.0 - ssr / sst
+        mae = float(np.average(np.abs(y - y_pred), weights=w))
+        nz = int(np.sum(np.abs(coef) > 1e-8))
+        entry = {"threshold": float(th), "nz": nz, "r2": r2, "mae": mae, "coef": coef}
+        rows.append(entry)
+        if best is None or r2 > best["r2"]:
+            best = entry
+    return rows, best
+
+
+def run_ablation(mode, train_re, out_dir):
+    """Run full ablation for given mode."""
+    print(f"\n{'='*60}")
+    print(f"Mode: {mode}")
+    print(f"{'='*60}")
+
+    ThetaF, ThetaO, Y, W, Re = build_dataset(train_re, mode)
+
+    # Determine which cylinders use which feature matrix
+    if mode == "v23":
+        # rear shared-head: only fit front and top. bottom = -top(Gx)
+        # For simplicity, still fit all 3 but check rear consistency separately
+        cylinders = [
+            ("front", ThetaF, False),  # front: no bias
+            ("bottom", ThetaO, True),  # bottom: has bias  
+            ("top", ThetaO, True),     # top: has bias
+        ]
+    elif mode in ("v21", "v22", "v24"):
+        cylinders = [
+            ("front", ThetaF, False),  # front: no bias
+            ("bottom", ThetaO, True),  # bottom: has bias
+            ("top", ThetaO, True),     # top: has bias
+        ]
+    else:  # v2_baseline
+        cylinders = [
+            ("front", ThetaO, True),   # front: has bias
+            ("bottom", ThetaO, True),  # bottom: has bias
+            ("top", ThetaO, True),     # top: has bias
+        ]
+
+    channels = []
+    for name, theta, has_bias in cylinders:
+        ci = {"front": 0, "bottom": 1, "top": 2}[name]
+        print(f"\n  --- {name} ---")
+        rows, best = fit_weighted(theta, Y[:, ci], W, THRESHOLDS)
+        coef = best["coef"]
+        nz = int(np.sum(np.abs(coef) > 1e-8))
+        print(f"  {name}: R2={best['r2']:.6f}  MAE={best['mae']:.6f}  nz={nz}")
+    # Get feature names for this mode
+    if mode in ("v2_baseline", "v21"):
+        feat_names = [
+            "bias", "u_m", "u_a", "u_c", "u_curv", "v_a", "v_curv",
+            "Fx_tot", "Fx_rear", "Fx_diff", "Fy_tot", "Fy_diff",
+            "sin_ua", "cos_ua",
+            "a0_lag1", "a1_lag1", "a2_lag1",
+            "da0", "da1", "da2",
+            "mu", "mu_u_a", "mu_v_a", "mu_Cd_tot", "mu_Cl_diff",
+        ]
+        has_mu = True
+    else:
+        feat_names = [
+            "bias", "u_m", "u_a", "u_c", "u_curv", "v_a", "v_curv",
+            "Cd_tot", "Cd_rear", "Cd_diff", "Cl_tot", "Cl_diff",
+            "sin_ua", "cos_ua",
+            "a0_lag1", "a1_lag1", "a2_lag1",
+            "da0", "da1", "da2",
+            "mu", "mu_u_a", "mu_v_a", "mu_Cd_tot", "mu_Cl_diff",
+        ]
+        has_mu = True
+
+    # Trim feat_names to match actual theta dimensions
+    actual_nf = theta.shape[1]
+    if len(feat_names) != actual_nf:
+        # Feature names don't include mu if not included, etc.
+        # Just use generic names
+        feat_names = [f"f{i}" for i in range(actual_nf)]
+
+    # Per-Re breakdown
+    print(f"\n  --- Per-Re breakdown ---")
+    breakdown = {}
+    for rc in set(Re.tolist()):
+        mask = Re == rc
+        ch_b = []
+        for name, theta, has_bias in cylinders:
+            ci = {"front": 0, "bottom": 1, "top": 2}[name]
+            th_r = theta[mask]
+            yr = Y[mask, ci]
+            wr = W[mask]
+            coef = np.array([ch["best_coef"][ci] for ch in channels], dtype=np.float64).flatten()
+            # Actually get the right coefficient for this cylinder
+            coef_c = np.array(channels[ci]["best_coef"], dtype=np.float64)
+            y_pred = th_r @ coef_c
+            y_mean = np.average(yr, weights=wr)
+            ssr = np.sum(wr * (yr - y_pred)**2)
+            sst = np.sum(wr * (yr - y_mean)**2) + 1e-12
+            r2 = 1.0 - ssr / sst
+            mae = float(np.average(np.abs(yr - y_pred), weights=wr))
+            ch_b.append({"cylinder": name, "r2": float(r2), "mae": mae})
+        breakdown[f"re{int(rc)}"] = ch_b
+        r2s = ", ".join([f"{b['cylinder']}={b['r2']:.4f}" for b in ch_b])
+        print(f"    Re{int(rc)}: {r2s}")
+
+    return {
+        "mode": mode,
+        "train_re": train_re,
+        "channels": channels,
+        "per_re_breakdown": breakdown,
+    }
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Ablation runner v2->v2.4")
+    ap.add_argument("--mode", type=str, default="all",
+                    choices=["v2_baseline", "v21", "v22", "v23", "v24", "all"])
+    ap.add_argument("--out-dir", type=str, default=os.path.join(OUTPUT_DIR, "sindy"))
+    ap.add_argument("--train-re", type=str, default="50,100,200")
+    args = ap.parse_args()
+
+    train_re = [int(r) for r in args.train_re.split(",")]
+    os.makedirs(args.out_dir, exist_ok=True)
+
+    modes = ["v2_baseline", "v21", "v22", "v23", "v24"] if args.mode == "all" else [args.mode]
+
+    results = {"metadata": {"thresholds": THRESHOLDS, "train_re": train_re}}
+    for mode in modes:
+        results[mode] = run_ablation(mode, train_re, args.out_dir)
+
+    out_path = os.path.join(args.out_dir, "ablation_results.json")
+    with open(out_path, "w") as f:
+        json.dump(results, f, indent=2)
+    print(f"\nSaved: {out_path}")
+
+
+if __name__ == "__main__":
+    main()

archive/analysis_crossre_scripts/phase2_control_fit.py

@@ -0,0 +1,320 @@
+# analysis_crossre/scripts/phase2_control_fit.py
+"""Phase 2 v3: dimensionless + front-no-bias + quality-weighted SINDy fitting.
+
+Usage::
+
+    conda run -n pycuda_3_10 python phase2_control_fit.py \\
+        --cross-re --out-dir output/analysis_crossre/sindy
+
+    conda run -n pycuda_3_10 python phase2_control_fit.py \\
+        --leave-one-out --out-dir output/analysis_crossre/sindy
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from typing import Dict, List, Tuple
+
+import numpy as np
+
+from utils import (
+    action_to_physical,
+    compute_dimensionless,
+    compute_v3_symbols,
+    fit_channel,
+    print_control_law,
+)
+from cfg import (
+    OUTPUT_DIR,
+    RE_CASES_TRAIN,
+    ACTION_SCALE,
+    ACTION_BIAS,
+    U0,
+)
+
+THRESHOLDS = [0.0, 0.001, 0.002, 0.005, 0.01, 0.015, 0.02, 0.03, 0.05, 0.1]
+
+
+def load_case_data(re_code: int) -> Tuple:
+    """Load controlled NPZ for a single Re.
+
+    Returns (sensors, forces, actions_phys, rewards, mu).
+    """
+    case_dir = os.path.join(OUTPUT_DIR, f"re{re_code}")
+    npz_path = os.path.join(case_dir, "controlled.npz")
+    if not os.path.isfile(npz_path):
+        raise FileNotFoundError(f"Missing {npz_path}")
+
+    data = np.load(npz_path)
+    sensors = data["sensors"].astype(np.float64)
+    forces = data["forces"].astype(np.float64)
+    actions_norm = data["actions"].astype(np.float64)
+    rewards = data.get("rewards", np.zeros(sensors.shape[0])).astype(np.float64)
+
+    actions_phys = action_to_physical(
+        actions_norm, scale=ACTION_SCALE, bias=ACTION_BIAS, u0=U0)
+    mu = 2.0 / re_code  # 1 / Re_D
+    return sensors, forces, actions_phys, rewards, mu
+
+
+def compute_trajectory_weights(rewards: np.ndarray, late_window: int = 80) -> float:
+    """Compute a single quality weight for this trajectory.
+
+    Uses the mean reward over the last ``late_window`` steps.
+    Maps to weight via quantile-based scheme.
+    """
+    n = len(rewards)
+    if n < late_window:
+        late_mean = float(np.mean(rewards))
+    else:
+        late_mean = float(np.mean(rewards[-late_window:]))
+
+    # Map reward to weight via sigmoid-like scheme:
+    # reward 0.0 -> weight 0.1, reward 0.3 -> 0.3, reward 0.5 -> 0.6, reward 0.7 -> 0.9
+    weight = 1.0 / (1.0 + np.exp(-8.0 * (late_mean - 0.4)))
+    return float(np.clip(weight, 0.05, 1.0))
+
+
+def build_dataset_v3(
+    re_code: int,
+    include_mu: bool = True,
+) -> Tuple:
+    """Build v3 data: dimensionless features, front-no-bias, quality-weighted.
+
+    Returns
+    -------
+    Theta_front : (T, nf_f) for front model (no bias)
+    Theta_other : (T, nf_o) for top/bottom model (with bias)
+    Y : (T, 3) physical omegas
+    W : (T,) quality weight per sample
+    names : feature names (without "bias")
+    """
+    sensors, forces, actions_phys, rewards, mu = load_case_data(re_code)
+
+    # Dimensionless
+    dim = compute_dimensionless(sensors, forces, u0=U0, d=20.0)
+
+    # Memory terms
+    a_prev = np.zeros_like(actions_phys)
+    a_prev2 = np.zeros_like(actions_phys)
+    a_prev[1:] = actions_phys[:-1]
+    a_prev2[2:] = actions_phys[:-2]
+
+    # Build v3 features
+    Theta_f, Theta_top, names = compute_v3_symbols(
+        dim, a_prev, a_prev2, mu=mu, include_mu=include_mu)
+
+    # Quality weight per sample: inherit trajectory weight
+    traj_weight = compute_trajectory_weights(rewards)
+    W = np.full(Theta_f.shape[0], traj_weight, dtype=np.float64)
+
+    # Remove warmup (need 2 steps of memory)
+    Theta_f = Theta_f[2:]
+    Theta_top = Theta_top[2:]
+    Y = actions_phys[2:]
+    W = W[2:]
+
+    print(f"  Re{re_code}: {Theta_f.shape[0]} samples, {Theta_f.shape[1]} feats, "
+          f"mu={mu:.6f}, traj_weight={traj_weight:.4f}")
+    return Theta_f, Theta_top, Y, W, names, mu
+
+
+def fit_channel_weighted(
+    Theta: np.ndarray,
+    y: np.ndarray,
+    w: np.ndarray,
+    thresholds: list,
+    alpha: float = 1e-4,
+    max_iter: int = 25,
+) -> tuple:
+    """Weighted STLSQ fit."""
+    import pysindy as ps
+
+    # Weighted normalisation
+    std = np.sqrt(np.average((Theta - np.average(Theta, axis=0, weights=w)) ** 2,
+                              axis=0, weights=w))
+    std = np.where(std < 1e-8, 1.0, std)
+    Theta_s = Theta / std
+
+    best = None
+    rows = []
+    for th in thresholds:
+        opt = ps.STLSQ(threshold=th, alpha=alpha, max_iter=max_iter)
+        opt.fit(Theta_s, y, sample_weight=w)
+        coef = np.asarray(opt.coef_, dtype=np.float64).flatten() / std
+        y_pred = Theta @ coef
+        # Weighted R2
+        y_mean = np.average(y, weights=w)
+        ssr = np.sum(w * (y - y_pred) ** 2)
+        sst = np.sum(w * (y - y_mean) ** 2) + 1e-12
+        r2 = 1.0 - ssr / sst
+        mae = float(np.average(np.abs(y - y_pred), weights=w))
+        nz = int(np.sum(np.abs(coef) > 1e-8))
+        entry = {"threshold": float(th), "nz": nz, "r2": r2, "mae": mae, "coef": coef}
+        rows.append(entry)
+        if best is None or r2 > best["r2"]:
+            best = entry
+    return rows, best
+
+
+def build_cross_re_v3(
+    train_re_codes: List[int],
+    include_mu: bool = True,
+) -> Tuple:
+    """Stack multiple Re datasets with v3 features.
+
+    Front model uses Theta_front (no bias).
+    Top/Bottom models use Theta_other (with bias).
+
+    Returns three stacked datasets.
+    """
+    all_ThetaF, all_ThetaO, all_Y, all_W, all_re = [], [], [], [], []
+    names = None
+
+    for rc in train_re_codes:
+        tf, to, y, w, fn, mu = build_dataset_v3(rc, include_mu=include_mu)
+        all_ThetaF.append(tf)
+        all_ThetaO.append(to)
+        all_Y.append(y)
+        all_W.append(w)
+        all_re.append(np.full(tf.shape[0], rc, dtype=np.int64))
+        if names is None:
+            names = fn
+
+    ThetaF = np.vstack(all_ThetaF)
+    ThetaO = np.vstack(all_ThetaO)
+    Y = np.vstack(all_Y)
+    W = np.concatenate(all_W)
+    Re = np.concatenate(all_re)
+
+    print(f"\n  Cross-Re: {ThetaF.shape[0]} samples, "
+          f"front={ThetaF.shape[1]} feats (no bias), "
+          f"other={ThetaO.shape[1]} feats (w/ bias)")
+    return ThetaF, ThetaO, Y, W, names, Re
+
+
+def run_cross_re_fit(
+    train_re: List[int],
+    tag: str = "",
+    include_mu: bool = True,
+) -> dict:
+    """Fit all 3 cylinders independently.
+
+    Front: no bias.
+    Top/Bottom: with bias.
+    """
+    ThetaF, ThetaO, Y, W, names, re_labels = build_cross_re_v3(train_re, include_mu)
+
+    cylinders = [
+        {"name": "front", "theta": ThetaF, "label": "front (no bias)"},
+        {"name": "bottom", "theta": ThetaO, "label": "bottom (w/ bias)"},
+        {"name": "top", "theta": ThetaO, "label": "top (w/ bias)"},
+    ]
+
+    channels = []
+    for ci, cyl in enumerate(cylinders):
+        print(f"\n  --- {tag} {cyl['label']} ---")
+        rows, best = fit_channel_weighted(cyl["theta"], Y[:, ci], W, THRESHOLDS)
+        coef = best["coef"]
+        print_control_law(names, coef, channel_label=f"{cyl['name']}")
+        print(f"         R2={best['r2']:.6f}  MAE={best['mae']:.6f}")
+        channels.append({
+            "cylinder": cyl["name"],
+            "has_bias": cyl["name"] != "front",
+            "n_features": cyl["theta"].shape[1],
+            "best": {k: float(v) if isinstance(v, (np.floating, float)) else v
+                     for k, v in best.items() if k != "coef"},
+            "best_coef": [float(c) for c in coef],
+            "grid": [{k: float(v) for k, v in row.items() if k != "coef"}
+                     for row in rows],
+            "feature_names": names,
+        })
+
+    # Per-Re breakdown
+    print(f"\n  --- {tag} per-Re breakdown ---")
+    breakdown = {}
+    for re_code in set(re_labels.tolist()):
+        mask = re_labels == re_code
+        Yr, Wr = Y[mask], W[mask]
+        ch_b = []
+        for ci, cyl in enumerate(cylinders):
+            th = cyl["theta"][mask]
+            coef = np.array(channels[ci]["best_coef"], dtype=np.float64)
+            y_pred = th @ coef
+            y_t = Yr[:, ci]
+            y_mean = np.average(y_t, weights=Wr)
+            ssr = np.sum(Wr * (y_t - y_pred) ** 2)
+            sst = np.sum(Wr * (y_t - y_mean) ** 2) + 1e-12
+            r2 = 1.0 - ssr / sst
+            mae = float(np.average(np.abs(y_t - y_pred), weights=Wr))
+            ch_b.append({"cylinder": cyl["name"], "r2": float(r2), "mae": mae})
+        breakdown[f"re{int(re_code)}"] = ch_b
+        r2s = ", ".join([f"{b['cylinder']}={b['r2']:.4f}" for b in ch_b])
+        print(f"    Re{int(re_code)}: {r2s}")
+
+    return {
+        "tag": tag,
+        "train_re": train_re,
+        "n_samples": int(ThetaF.shape[0]),
+        "n_features_front": int(ThetaF.shape[1]),
+        "n_features_other": int(ThetaO.shape[1]),
+        "channels": channels,
+        "per_re_breakdown": breakdown,
+    }
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Phase 2 v3: dimensionless + constrained fitting")
+    ap.add_argument("--cross-re", action="store_true")
+    ap.add_argument("--leave-one-out", action="store_true")
+    ap.add_argument("--out-dir", type=str, default=os.path.join(OUTPUT_DIR, "sindy"))
+    ap.add_argument("--train-re", type=str, default="50,100,200")
+    ap.add_argument("--no-mu", action="store_true")
+    args = ap.parse_args()
+
+    if not (args.cross_re or args.leave_one_out):
+        print("ERROR: specify --cross-re and/or --leave-one-out")
+        return 1
+
+    train_re = [int(r) for r in args.train_re.split(",")]
+    include_mu = not args.no_mu
+    os.makedirs(args.out_dir, exist_ok=True)
+
+    results = {
+        "metadata": {
+            "method": "v3_dimensionless_front_nobias_weighted",
+            "thresholds": THRESHOLDS,
+            "include_mu": include_mu,
+        }
+    }
+
+    if args.cross_re:
+        print("\n" + "=" * 60)
+        print("v3 Cross-Re unified (dimensionless + front no-bias + weighted)")
+        print("=" * 60)
+        results["cross_re"] = run_cross_re_fit(
+            train_re, tag="v3-cross", include_mu=include_mu)
+
+    if args.leave_one_out:
+        print("\n" + "=" * 60)
+        print("v3 Leave-one-out cross-validation")
+        print("=" * 60)
+        loo_results = {}
+        for held_out in train_re:
+            train_set = [r for r in train_re if r != held_out]
+            print(f"\n--- LOO: train={train_set}, test={held_out} ---")
+            loo = run_cross_re_fit(
+                train_set, tag=f"v3-loo-{held_out}", include_mu=include_mu)
+            loo_results[f"holdout_{held_out}"] = loo
+        results["leave_one_out"] = loo_results
+
+    out_path = os.path.join(args.out_dir, "sindy_results_v3.json")
+    with open(out_path, "w") as f:
+        json.dump(results, f, indent=2)
+    print(f"\nSaved: {out_path}")
+
+
+if __name__ == "__main__":
+    main()

archive/analysis_crossre_scripts/phase3_ablation_val.py

@@ -0,0 +1,267 @@
+"""Phase 3: closed-loop for ablation modes.
+
+Usage::
+
+    conda run -n pycuda_3_10 python phase3_ablation_val.py \\
+        --ablation-json output/analysis_crossre/sindy/ablation_results.json \\
+        --mode v21 --validate-re 70 --device 2
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from collections import deque
+
+import numpy as np
+
+_PROJ = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+if _PROJ not in sys.path:
+    sys.path.insert(0, _PROJ)
+from LegacyCelerisLab import FlowField
+
+from utils import (
+    nu_from_re, load_legacy_configs, build_karman_cloak_env, add_pinball,
+    build_observation, scale_action, action_to_physical,
+    compute_dimensionless, compute_physical_symbols,
+    save_vorticity_png, vorticity_from_ddf, compute_similarity,
+)
+from cfg import (
+    CONFIG_DIR, OUTPUT_DIR, SAMPLE_INTERVAL, FIFO_LEN, CONV_LEN,
+    S_DIM, ACTION_SCALE, ACTION_BIAS, U0,
+)
+
+DATA_TYPE = np.float32
+
+
+def load_ablation_coef(ablation_path, mode, channels_to_load=("front", "bottom", "top")):
+    """Load coefficients for a specific ablation mode."""
+    with open(ablation_path) as f:
+        data = json.load(f)
+    
+    mode_data = data[mode]
+    coefs = {}
+    for ch in mode_data["channels"]:
+        name = ch["cylinder"]
+        if name in channels_to_load:
+            coefs[name] = {
+                "coef": np.array(ch["best_coef"], dtype=np.float64),
+                "has_bias": ch["has_bias"],
+            }
+    return coefs
+
+
+def predict_ablation(obs_slice, actions_prev, actions_prev2, coefs, mu, mode, u0=0.01):
+    """Predict action using ablation mode coefficients.
+
+    obs_slice: (12,) raw lattice [sensor(6), force(6)]
+    """
+    sensors = obs_slice[0:6].astype(np.float64).reshape(1, 6)
+    forces = obs_slice[6:12].astype(np.float64).reshape(1, 6)
+    a_prev = actions_prev.astype(np.float64).reshape(1, 3)
+    a_prev2 = actions_prev2.astype(np.float64).reshape(1, 3)
+
+    is_dim = "v22" in mode or "v23" in mode or "v24" in mode or mode in ("v2_dimless",)
+
+    if is_dim:
+        dim = compute_dimensionless(sensors, forces, u0=u0, d=20.0)
+        # Build dimensionless features
+        sym = _build_dimensionless_features(dim, a_prev[0], a_prev2[0], mu)
+        Y_scale = 1.0 / u0  # predict nondim alpha = omega / U0
+    else:
+        # Lattice features (v2/v21)
+        a_prev_f = np.zeros((1, 3), dtype=np.float64)
+        a_prev2_f = np.zeros((1, 3), dtype=np.float64)
+        a_prev_f[0] = a_prev
+        a_prev2_f[0] = a_prev2
+        sym = _build_lattice_features(sensors, forces, a_prev_f, a_prev2_f, mu)
+        Y_scale = 1.0  # predict raw omega
+
+    # Build feature vector
+    feat_keys = [k for k in sym.keys() if k not in ("mu", "mu_u_a", "mu_v_a", "mu_Cd_tot", "mu_Cl_diff")]
+    feat_keys_mu = ["mu", "mu_u_a", "mu_v_a", "mu_Cd_tot", "mu_Cl_diff"]
+    
+    feats = []
+    for k in feat_keys:
+        feats.append(float(sym[k][0]) if isinstance(sym[k], np.ndarray) else float(sym[k]))
+    if mu > 0:
+        for k in feat_keys_mu:
+            feats.append(float(sym[k][0]) if isinstance(sym[k], np.ndarray) else float(sym[k]))
+
+    omega = np.zeros(3, dtype=np.float64)
+    for ci, name in enumerate(["front", "bottom", "top"]):
+        c = coefs.get(name)
+        if c is None:
+            continue
+        coef_arr = c["coef"]
+        has_bias = c["has_bias"]
+        
+        if has_bias:
+            feat_vec = np.array([1.0] + feats) if len(coef_arr) == len(feats) + 1 else np.array(feats)
+        else:
+            feat_vec = np.array(feats) if len(coef_arr) == len(feats) else np.array([1.0] + feats)
+        
+        if len(feat_vec) != len(coef_arr):
+            feat_vec = np.array(feats)  # fallback
+        
+        pred = float(feat_vec @ coef_arr) * Y_scale
+        omega[ci] = pred
+    
+    return omega
+
+
+def _build_lattice_features(sensors, forces, a_prev, a_prev2, mu):
+    """Build v2-style lattice features. All args 2D (1, N)."""
+    # Ensure 2D
+    if sensors.ndim == 1:
+        sensors = sensors.reshape(1, -1)
+    if forces.ndim == 1:
+        forces = forces.reshape(1, -1)
+    if a_prev.ndim == 1:
+        a_prev = a_prev.reshape(1, -1)
+    if a_prev2.ndim == 1:
+        a_prev2 = a_prev2.reshape(1, -1)
+    sym = compute_physical_symbols(sensors, forces, a_prev, a_prev2)
+    sym["mu"] = np.array([mu])
+    sym["mu_u_a"] = sym["u_a"] * mu
+    sym["mu_v_a"] = sym["v_a"] * mu
+    sym["mu_Cd_tot"] = sym["Fx_tot"] * mu
+    sym["mu_Cl_diff"] = sym["Fy_diff"] * mu
+    return sym
+
+
+def _build_dimensionless_features(dim, a_prev, a_prev2, mu):
+    """Build dimensionless features. a_prev/a_prev2 are 1D (3,) arrays."""
+    if a_prev.ndim > 1:
+        a_prev = a_prev.flatten()
+    if a_prev2.ndim > 1:
+        a_prev2 = a_prev2.flatten()
+    """Build dimensionless features."""
+    T = 1
+    u_B, u_C, u_T = dim["u_hat_B"][0], dim["u_hat_C"][0], dim["u_hat_T"][0]
+    v_B, v_C, v_T = dim["v_hat_B"][0], dim["v_hat_C"][0], dim["v_hat_T"][0]
+    
+    sym = {}
+    sym["u_m"] = np.array([(u_B + u_C + u_T) / 3.0])
+    sym["u_a"] = np.array([(u_T - u_B) / 2.0])
+    sym["u_c"] = np.array([u_C])
+    sym["u_curv"] = np.array([u_B - 2.0*u_C + u_T])
+    sym["v_a"] = np.array([(v_T - v_B) / 2.0])
+    sym["v_curv"] = np.array([v_B - 2.0*v_C + v_T])
+    sym["sin_ua"] = np.sin(np.pi * sym["u_a"])
+    sym["cos_ua"] = np.cos(np.pi * sym["u_a"])
+    
+    sym["Cd_tot"] = np.array([dim["Cd_F"][0] + dim["Cd_T"][0] + dim["Cd_B"][0]])
+    sym["Cd_rear"] = np.array([dim["Cd_T"][0] + dim["Cd_B"][0]])
+    sym["Cd_diff"] = np.array([dim["Cd_T"][0] - dim["Cd_B"][0]])
+    sym["Cl_tot"] = np.array([dim["Cl_F"][0] + dim["Cl_T"][0] + dim["Cl_B"][0]])
+    sym["Cl_diff"] = np.array([dim["Cl_T"][0] - dim["Cl_B"][0]])
+    
+    # Nondim actions
+    a_prev_n = a_prev / U0
+    a_prev2_n = a_prev2 / U0
+    sym["a0_lag1"] = np.array([a_prev_n[0]])
+    sym["a1_lag1"] = np.array([a_prev_n[1]])
+    sym["a2_lag1"] = np.array([a_prev_n[2]])
+    sym["da0"] = np.array([a_prev_n[0] - a_prev2_n[0]])
+    sym["da1"] = np.array([a_prev_n[1] - a_prev2_n[1]])
+    sym["da2"] = np.array([a_prev_n[2] - a_prev2_n[2]])
+    
+    sym["mu"] = np.array([mu])
+    sym["mu_u_a"] = sym["u_a"] * mu
+    sym["mu_v_a"] = sym["v_a"] * mu
+    sym["mu_Cd_tot"] = sym["Cd_tot"] * mu
+    sym["mu_Cl_diff"] = sym["Cl_diff"] * mu
+    
+    return sym
+
+
+def run_closed_loop(re_code, coefs, mode, device_id, output_root, n_steps=100):
+    """Run closed-loop for one ablation mode."""
+    os.makedirs(output_root, exist_ok=True)
+    nu = nu_from_re(re_code, u0=U0)
+    mu = 2.0 / re_code
+    
+    cuda_cfg, field_cfg = load_legacy_configs(CONFIG_DIR)
+    field_cfg = field_cfg._replace(viscosity=float(nu))
+    ff = FlowField(field_cfg, cuda_cfg, device_id=device_id)
+    
+    target_states, _ = build_karman_cloak_env(
+        ff, u0=U0, l0=20.0, sample_interval=SAMPLE_INTERVAL,
+        fifo_len=FIFO_LEN, data_type=DATA_TYPE)
+    norm = add_pinball(
+        ff, l0=20.0, u0=U0, sample_interval=SAMPLE_INTERVAL,
+        fifo_len=FIFO_LEN, data_type=DATA_TYPE, action_bias=ACTION_BIAS)
+    
+    np.savez(os.path.join(output_root, "target.npz"), target_states=target_states)
+    
+    # Controlled rollout
+    ff.restore_ddf()
+    ff.apply_ddf()
+    fifo = deque(maxlen=FIFO_LEN)
+    bias_action = scale_action(
+        np.zeros(3, dtype=np.float32), scale=ACTION_SCALE,
+        bias=ACTION_BIAS, u0=U0, n_total_bodies=7)
+    for _ in range(FIFO_LEN):
+        ff.run(SAMPLE_INTERVAL, bias_action)
+        fifo.append(ff.obs.copy()[2:14])
+    
+    sens_sc = []
+    actions_prev = action_to_physical(
+        np.zeros((1,3), dtype=np.float32), scale=ACTION_SCALE,
+        bias=ACTION_BIAS, u0=U0).flatten()
+    actions_prev2 = actions_prev.copy()
+    
+    for step in range(n_steps):
+        obs_slice = fifo[-1] if len(fifo) > 0 else np.zeros(12, dtype=np.float32)
+        omega_pred = predict_ablation(obs_slice, actions_prev, actions_prev2, coefs, mu, mode, u0=U0)
+        
+        norm_action = (omega_pred / U0 - np.array(ACTION_BIAS, dtype=np.float64)) / ACTION_SCALE
+        norm_action = np.clip(norm_action, -1.0, 1.0).astype(np.float32)
+        action_arr = scale_action(
+            norm_action, scale=ACTION_SCALE, bias=ACTION_BIAS, u0=U0, n_total_bodies=7)
+        ff.run(SAMPLE_INTERVAL, action_arr)
+        
+        obs_slice_new = ff.obs.copy()[2:14]
+        fifo.append(obs_slice_new)
+        sens_sc.append(obs_slice_new[0:6])
+        actions_prev2 = actions_prev.copy()
+        actions_prev = omega_pred.copy()
+    
+    sens_arr = np.array(sens_sc, dtype=np.float32)
+    sim = compute_similarity(target_states, sens_arr, CONV_LEN)
+    
+    omega_vort = vorticity_from_ddf(ff, u0=U0)
+    save_vorticity_png(os.path.join(output_root, f"vorticity_{mode}.png"),
+                       omega_vort, title=f"Re{re_code} {mode}")
+    
+    del ff
+    result = {"re_code": re_code, "mode": mode, "similarity": sim}
+    with open(os.path.join(output_root, "result.json"), "w") as f:
+        json.dump(result, f, indent=2)
+    print(f"  Re{re_code} {mode}: similarity={sim:.4f}")
+    return result
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--ablation-json", type=str, required=True)
+    ap.add_argument("--mode", type=str, default="v21")
+    ap.add_argument("--validate-re", type=str, default="70")
+    ap.add_argument("--device", type=int, default=2)
+    ap.add_argument("--steps", type=int, default=100)
+    ap.add_argument("--out-dir", type=str, default=os.path.join(OUTPUT_DIR, "sindy_val"))
+    args = ap.parse_args()
+    
+    validate_re = [int(r) for r in args.validate_re.split(",")]
+    coefs = load_ablation_coef(args.ablation_json, args.mode)
+    os.makedirs(args.out_dir, exist_ok=True)
+    
+    for rc in validate_re:
+        out_sub = os.path.join(args.out_dir, f"re{rc}")
+        run_closed_loop(rc, coefs, args.mode, args.device, out_sub, n_steps=args.steps)
+
+
+if __name__ == "__main__":
+    main()

archive/analysis_crossre_scripts/phase3_validate.py

@@ -0,0 +1,306 @@
+# analysis_crossre/scripts/phase3_validate.py
+"""Phase 3: closed-loop validation using cross-Re SINDy control law.
+
+Usage::
+
+    conda run -n pycuda_3_10 python phase3_validate.py \\
+        --device 2 --out-dir output/analysis_crossre/sindy_val
+
+    conda run -n pycuda_3_10 python phase3_validate.py \\
+        --validate-re 35,70,150 --device 2
+
+    conda run -n pycuda_3_10 python phase3_validate.py \\
+        --baseline-only --validate-re 35 --device 2
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+from collections import deque
+
+import numpy as np
+
+_PROJ = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+if _PROJ not in sys.path:
+    sys.path.insert(0, _PROJ)
+from LegacyCelerisLab import FlowField  # noqa: E402
+
+from utils import (
+    nu_from_re,
+    load_legacy_configs,
+    build_karman_cloak_env,
+    add_pinball,
+    build_observation,
+    scale_action,
+    action_to_physical,
+    compute_dimensionless,
+    compute_v3_symbols,
+    save_vorticity_png,
+    vorticity_from_ddf,
+    compute_similarity,
+)
+from cfg import (
+    CONFIG_DIR,
+    OUTPUT_DIR,
+    MODEL_DIR,
+    SAMPLE_INTERVAL,
+    FIFO_LEN,
+    CONV_LEN,
+    S_DIM,
+    A_DIM,
+    ACTION_SCALE,
+    ACTION_BIAS,
+    U0,
+    RE_CASES_TRAIN,
+    RE_CASES_VALIDATION,
+    RE_LABEL_MAP,
+)
+
+DATA_TYPE = np.float32
+
+
+def load_cross_re_coef(sindy_results_path: str, threshold: float) -> dict:
+    """Load v3 cross-Re coefficients.
+
+    Returns dict ``{cylinder_name: {"coef": np.ndarray, "feat_names": list, "has_bias": bool}}``
+    """
+    with open(sindy_results_path) as f:
+        data = json.load(f)
+
+    cross = data["cross_re"]
+    coefs = {}
+    for ch_entry in cross["channels"]:
+        name = ch_entry["cylinder"]
+        feat_names = ch_entry["feature_names"]
+        coef_full = np.array(ch_entry["best_coef"], dtype=np.float64)
+        has_bias = ch_entry["has_bias"]
+
+        scale = np.max(np.abs(coef_full))
+        if scale > 0 and threshold > 0:
+            mask = np.abs(coef_full) / scale >= threshold
+        else:
+            mask = np.ones_like(coef_full, dtype=bool)
+        coef = coef_full * mask
+
+        nz = int(np.sum(mask))
+        print(f"  {name}: total={len(coef_full)} nz={nz} threshold={threshold} "
+              f"R2={ch_entry['best']['r2']:.4f}")
+
+        coefs[name] = {"coef": coef, "feat_names": feat_names,
+                       "has_bias": has_bias, "nz": nz, "r2": ch_entry["best"]["r2"]}
+    return coefs
+
+
+def predict_omega_v3(
+    obs_slice: np.ndarray,
+    actions_prev: np.ndarray,
+    actions_prev2: np.ndarray,
+    coefs: dict,
+    mu: float,
+    u0: float = 0.01,
+) -> np.ndarray:
+    """Predict physical omega using v3 dimensionless features.
+
+    Front: no bias term.
+    Bottom/Top: with bias term.
+    All 3 independently (no exchange symmetry constraint).
+
+    Parameters
+    ----------
+    obs_slice : (12,)  raw [sensor(6), force(6)] in lattice units
+    actions_prev : (3,)  omega(t-1)
+    actions_prev2 : (3,)  omega(t-2)
+    """
+    sensors = obs_slice[0:6].astype(np.float64).reshape(1, 6)
+    forces = obs_slice[6:12].astype(np.float64).reshape(1, 6)
+    a_prev = actions_prev.astype(np.float64).reshape(1, 3)
+    a_prev2 = actions_prev2.astype(np.float64).reshape(1, 3)
+
+    # Dimensionless
+    dim = compute_dimensionless(sensors, forces, u0=u0, d=20.0)
+
+    # Build v3 features
+    Theta_f, Theta_top, names = compute_v3_symbols(
+        dim, a_prev, a_prev2, mu=mu, include_mu=(mu > 0))
+
+    # Predict
+    omega = np.zeros(3, dtype=np.float64)
+    omega[0] = float(Theta_f[0] @ coefs["front"]["coef"])  # front (no bias)
+    omega[1] = float(Theta_top[0] @ coefs["bottom"]["coef"])  # bottom
+    omega[2] = float(Theta_top[0] @ coefs["top"]["coef"])  # top
+
+    return omega
+
+
+def run_sindy_controlled(
+    re_code: int,
+    coefs: dict,
+    device_id: int,
+    output_root: str,
+    *,
+    n_steps: int = 150,
+) -> dict:
+    """Run closed-loop validation with SINDy control law."""
+    os.makedirs(output_root, exist_ok=True)
+
+    nu = nu_from_re(re_code, u0=U0)
+    mu = 2.0 / re_code  # 1 / Re_D
+    label = RE_LABEL_MAP.get(re_code, f"Re{re_code}")
+    print(f"\n{'='*60}")
+    print(f"SINDy Validation: {label}   nu={nu:.6f}   mu={mu:.6f}")
+    print(f"{'='*60}")
+
+    # Build environment (same as Phase 1)
+    cuda_cfg, field_cfg = load_legacy_configs(CONFIG_DIR)
+    field_cfg = field_cfg._replace(viscosity=float(nu))
+
+    # Phase 1: dist + sensors + target
+    ff = FlowField(field_cfg, cuda_cfg, device_id=device_id)
+    target_states, _ = build_karman_cloak_env(
+        ff, u0=U0, l0=20.0, sample_interval=SAMPLE_INTERVAL,
+        fifo_len=FIFO_LEN, data_type=DATA_TYPE,
+    )
+
+    # Phase 2: pinball + norm
+    norm = add_pinball(
+        ff, l0=20.0, u0=U0, sample_interval=SAMPLE_INTERVAL,
+        fifo_len=FIFO_LEN, data_type=DATA_TYPE,
+        action_bias=ACTION_BIAS,
+    )
+    np.savez(os.path.join(output_root, "target.npz"), target_states=target_states)
+
+    # --- Uncontrolled rollout ---
+    print("  uncontrolled rollout ...")
+    ff.restore_ddf()
+    ff.apply_ddf()
+    sens_unc, forc_unc = [], []
+    for _ in range(n_steps):
+        ff.run(SAMPLE_INTERVAL, np.zeros(7, dtype=DATA_TYPE))
+        obs_slice = ff.obs.copy()[2:14]
+        sens_unc.append(obs_slice[0:6])
+        forc_unc.append(obs_slice[6:12])
+    np.savez(os.path.join(output_root, "uncontrolled.npz"),
+             sensors=np.array(sens_unc, dtype=np.float32),
+             forces=np.array(forc_unc, dtype=np.float32))
+
+    # Uncontrolled vorticity
+    omega_unc = vorticity_from_ddf(ff, u0=U0)
+    save_vorticity_png(os.path.join(output_root, "vorticity_uncontrolled.png"),
+                       omega_unc, title=f"{label} uncontrolled")
+
+    # --- SINDy controlled rollout ---
+    print(f"  SINDy controlled rollout ({n_steps} steps) ...")
+    ff.restore_ddf()
+    ff.apply_ddf()
+
+    # Bias FIFO
+    fifo = deque(maxlen=FIFO_LEN)
+    bias_action = scale_action(
+        np.zeros(3, dtype=np.float32),
+        scale=ACTION_SCALE, bias=ACTION_BIAS, u0=U0, n_total_bodies=7,
+    )
+    for _ in range(FIFO_LEN):
+        ff.run(SAMPLE_INTERVAL, bias_action)
+        fifo.append(ff.obs.copy()[2:14])
+
+    sens_sc, forc_sc, omega_sc = [], [], []
+    omega_bias = action_to_physical(
+        np.zeros((1, 3), dtype=np.float32),
+        scale=ACTION_SCALE, bias=ACTION_BIAS, u0=U0,
+    ).flatten()
+    actions_prev = omega_bias.copy()
+    actions_prev2 = omega_bias.copy()
+
+    for step in range(n_steps):
+        obs_slice = fifo[-1] if len(fifo) > 0 else np.zeros(12, dtype=np.float32)
+
+        omega_pred = predict_omega_v3(obs_slice, actions_prev, actions_prev2, coefs, mu, u0=U0)
+        omega_sc.append(omega_pred.copy())
+
+        # Convert action to legacy array and apply
+        norm_action = (omega_pred / U0 - np.array(ACTION_BIAS, dtype=np.float64)) / ACTION_SCALE
+        norm_action = np.clip(norm_action, -1.0, 1.0).astype(np.float32)
+        action_arr = scale_action(
+            norm_action,
+            scale=ACTION_SCALE, bias=ACTION_BIAS, u0=U0, n_total_bodies=7,
+        )
+        ff.run(SAMPLE_INTERVAL, action_arr)
+
+        obs_slice_new = ff.obs.copy()[2:14]
+        fifo.append(obs_slice_new)
+        sens_sc.append(obs_slice_new[0:6])
+        forc_sc.append(obs_slice_new[6:12])
+        actions_prev = omega_pred
+
+    sens_sc_arr = np.array(sens_sc, dtype=np.float32)
+    forc_sc_arr = np.array(forc_sc, dtype=np.float32)
+    omega_sc_arr = np.array(omega_sc, dtype=np.float32)
+    np.savez(os.path.join(output_root, "sindy_controlled.npz"),
+             sensors=sens_sc_arr, forces=forc_sc_arr,
+             omegas=omega_sc_arr)
+
+    # Vorticity
+    omega_vort = vorticity_from_ddf(ff, u0=U0)
+    save_vorticity_png(os.path.join(output_root, "vorticity_sindy_controlled.png"),
+                       omega_vort, title=f"{label} SINDy-controlled")
+
+    # Similarity
+    sim = compute_similarity(target_states, sens_sc_arr, CONV_LEN)
+    print(f"  SINDy similarity: {sim:.4f}")
+
+    del ff
+    result = {"re_code": re_code, "mu": mu,
+              "sindy_similarity": sim,
+              "n_steps": n_steps}
+    with open(os.path.join(output_root, "result.json"), "w") as f:
+        json.dump(result, f, indent=2)
+    return result
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Phase 3: cross-Re SINDy validation")
+    ap.add_argument("--sindy-results", type=str,
+                    default=os.path.join(OUTPUT_DIR, "sindy", "sindy_results_v3.json"),
+                    help="Path to Phase 2 SINDy results JSON (v3 dimensionless)")
+    ap.add_argument("--validate-re", type=str, default="35,70,150",
+                    help="Comma-separated validation Re codes")
+    ap.add_argument("--device", type=int, default=0, help="GPU device ID")
+    ap.add_argument("--steps", type=int, default=150,
+                    help="Number of inference steps")
+    ap.add_argument("--threshold", type=float, default=0.002,
+                    help="SINDy sparsity threshold (default: 0.002)")
+    ap.add_argument("--out-dir", type=str,
+                    default=os.path.join(OUTPUT_DIR, "sindy_val"),
+                    help="Output root for validation results")
+    args = ap.parse_args()
+
+    validate_re = [int(r) for r in args.validate_re.split(",")]
+    os.makedirs(args.out_dir, exist_ok=True)
+
+    # Load cross-Re coefficients
+    print(f"\nLoading cross-Re coefficients from {args.sindy_results}")
+    coefs = load_cross_re_coef(args.sindy_results, args.threshold)
+    for name in ["front", "bottom", "top"]:
+        print(f"  {name}: nz={coefs[name]['nz']}, R2={coefs[name]['r2']:.4f}, "
+              f"threshold={args.threshold}")
+
+    t_start = time.time()
+
+    # Run for each validation Re
+    for re_code in validate_re:
+        out_dir = os.path.join(args.out_dir, f"re{re_code}")
+        result = run_sindy_controlled(
+            re_code, coefs, args.device, out_dir, n_steps=args.steps,
+        )
+        print(f"  Done: Re{re_code}  -> {out_dir}")
+
+    elapsed = time.time() - t_start
+    print(f"\nTotal time: {elapsed:.1f}s")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

archive/analysis_crossre_scripts/validate_v22.py

@@ -0,0 +1,197 @@
+# analysis_crossre/scripts/validate_v22.py
+"""Validate v22: v2 coefficients + front bias zeroed.
+Direct standalone script to avoid JSON format issues.
+
+Usage:
+    conda run -n pycuda_3_10 python validate_v22.py --re 70 --device 2
+"""
+import argparse
+import json
+import os
+import sys
+from collections import deque
+
+import numpy as np
+
+_PROJ = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+if _PROJ not in sys.path:
+    sys.path.insert(0, _PROJ)
+from LegacyCelerisLab import FlowField
+from LegacyCelerisLab import utils as legacy_utils
+
+from utils import (
+    nu_from_re, action_to_physical, scale_action, build_karman_cloak_env,
+    add_pinball, build_observation, compute_physical_symbols,
+    save_vorticity_png, vorticity_from_ddf, compute_similarity,
+    load_legacy_configs,
+)
+from cfg import (
+    OUTPUT_DIR, SAMPLE_INTERVAL, FIFO_LEN, CONV_LEN, S_DIM,
+    ACTION_SCALE, ACTION_BIAS, U0, CONFIG_DIR,
+)
+
+DATA_TYPE = np.float32
+
+# v2 feature keys (matching sindy_results_v2.json layout exactly)
+V2_FEAT_KEYS = [
+    "u_m", "u_a", "u_c", "v_a",
+    "Fx_tot", "Fx_rear", "Fy_tot", "Fy_diff",
+    "sin_ua", "cos_ua",
+    "a0_lag1", "a1_lag1", "a2_lag1",
+    "da0", "da1", "da2",
+]
+V2_MU_KEYS = ["mu", "mu_u_a", "mu_v_a", "mu_Fx_tot", "mu_Fy_diff", "mu_Fy_tot"]
+V2_N_FEAT_NOBIAS = len(V2_FEAT_KEYS) + len(V2_MU_KEYS)  # 22
+V2_N_FEAT_BIAS = 1 + V2_N_FEAT_NOBIAS  # 23
+
+
+def build_feature_vec(obs_slice, actions_prev, actions_prev2, mu, add_bias):
+    """Build a single feature vector matching v2 feature layout."""
+    sensors = obs_slice[0:6].astype(np.float64).reshape(1, 6)
+    forces = obs_slice[6:12].astype(np.float64).reshape(1, 6)
+    ap = actions_prev.astype(np.float64).reshape(1, 3)
+    ap2 = actions_prev2.astype(np.float64).reshape(1, 3)
+
+    sym = compute_physical_symbols(sensors, forces, ap, ap2)
+    # Add mu terms
+    sym["mu"] = np.array([mu])
+    sym["mu_u_a"] = sym["u_a"] * mu
+    sym["mu_v_a"] = sym["v_a"] * mu
+    sym["mu_Fx_tot"] = sym["Fx_tot"] * mu
+    sym["mu_Fy_diff"] = sym["Fy_diff"] * mu
+    sym["mu_Fy_tot"] = sym["Fy_tot"] * mu
+
+    vals = []
+    if add_bias:
+        vals.append(1.0)
+    for k in V2_FEAT_KEYS:
+        vals.append(float(sym[k][0]))
+    for k in V2_MU_KEYS:
+        vals.append(float(sym[k][0]))
+    return np.array(vals, dtype=np.float64)
+
+
+def load_v2_coefs(v2_path):
+    """Load v2 coefficients, zero front bias."""
+    with open(v2_path) as f:
+        data = json.load(f)
+    cross = data["cross_re"]
+    coefs_list = cross["channels"]  # 3 channels: 0=front, 1=bottom, 2=top
+
+    # Zero front bias
+    coefs_list[0]["best_coef"][0] = 0.0
+
+    names = ["front", "bottom", "top"]
+    result = {}
+    for i, name in enumerate(names):
+        coef_list = coefs_list[i]["best_coef"]
+        # Check if first is bias (it is for v2)
+        has_bias = True
+        if name == "front":
+            has_bias = True  # v2 has bias for all, we just zeroed it
+        result[name] = {
+            "coef": np.array(coef_list, dtype=np.float64),
+            "has_bias": True,  # v2 has bias for all channels
+        }
+    return result
+
+
+def predict(obs_slice, a_prev, a_prev2, coefs, mu):
+    """Predict physical omega using v2 coefficients."""
+    omega = np.zeros(3, dtype=np.float64)
+    for i, name in enumerate(["front", "bottom", "top"]):
+        c = coefs[name]
+        feat = build_feature_vec(obs_slice, a_prev, a_prev2, mu, add_bias=c["has_bias"])
+        omega[i] = float(feat @ c["coef"])
+    return omega
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--re", type=int, default=70)
+    ap.add_argument("--device", type=int, default=2)
+    ap.add_argument("--steps", type=int, default=100)
+    ap.add_argument("--out-dir", type=str, default=os.path.join(OUTPUT_DIR, "sindy_val"))
+    ap.add_argument("--v2-results", type=str,
+                    default=os.path.join(OUTPUT_DIR, "sindy", "sindy_results_v2.json"))
+    args = ap.parse_args()
+
+    re_code = args.re
+    mu = 2.0 / re_code
+    output_root = os.path.join(args.out_dir, f"re{re_code}")
+    os.makedirs(output_root, exist_ok=True)
+
+    print(f"\n=== v22 validation: Re{re_code} (mu={mu:.6f}) ===")
+
+    # Load v2 coefs (front bias zeroed)
+    coefs = load_v2_coefs(args.v2_results)
+    for name in ["front", "bottom", "top"]:
+        print(f"  {name}: {len(coefs[name]['coef'])} coefs, "
+              f"bias={coefs[name]['coef'][0]:.6f}")
+
+    # Build environment (same as phase1)
+    cuda_cfg, field_cfg = load_legacy_configs(CONFIG_DIR)
+    field_cfg = field_cfg._replace(viscosity=float(nu_from_re(re_code, u0=U0)))
+    ff = FlowField(field_cfg, cuda_cfg, device_id=args.device)
+
+    target_states, _ = build_karman_cloak_env(
+        ff, u0=U0, l0=20.0, sample_interval=SAMPLE_INTERVAL,
+        fifo_len=FIFO_LEN, data_type=DATA_TYPE)
+    norm = add_pinball(
+        ff, l0=20.0, u0=U0, sample_interval=SAMPLE_INTERVAL,
+        fifo_len=FIFO_LEN, data_type=DATA_TYPE, action_bias=ACTION_BIAS)
+
+    # Controlled rollout
+    ff.restore_ddf()
+    ff.apply_ddf()
+    fifo = deque(maxlen=FIFO_LEN)
+    bias_action = scale_action(np.zeros(3, dtype=np.float32),
+                                scale=ACTION_SCALE, bias=ACTION_BIAS,
+                                u0=U0, n_total_bodies=7)
+    for _ in range(FIFO_LEN):
+        ff.run(SAMPLE_INTERVAL, bias_action)
+        fifo.append(ff.obs.copy()[2:14])
+
+    sens_sc = []
+    a_prev = action_to_physical(np.zeros((1,3), dtype=np.float32),
+                                 scale=ACTION_SCALE, bias=ACTION_BIAS, u0=U0).flatten()
+    a_prev2 = a_prev.copy()
+
+    for step in range(args.steps):
+        obs_slice = fifo[-1] if len(fifo) > 0 else np.zeros(12, dtype=np.float32)
+        omega = predict(obs_slice, a_prev, a_prev2, coefs, mu)
+
+        # Apply action (convert to normalized for legacy run())
+        norm_action = (omega / U0 - np.array(ACTION_BIAS, dtype=np.float64)) / ACTION_SCALE
+        norm_action = np.clip(norm_action, -1.0, 1.0).astype(np.float32)
+        action_arr = scale_action(norm_action, scale=ACTION_SCALE,
+                                   bias=ACTION_BIAS, u0=U0, n_total_bodies=7)
+        ff.run(SAMPLE_INTERVAL, action_arr)
+
+        obs_slice_new = ff.obs.copy()[2:14]
+        fifo.append(obs_slice_new)
+        sens_sc.append(obs_slice_new[0:6])
+        a_prev2 = a_prev.copy()
+        a_prev = omega.copy()
+
+    sens_arr = np.array(sens_sc, dtype=np.float32)
+    sim = compute_similarity(target_states, sens_arr, CONV_LEN)
+    print(f"  v22 similarity: {sim:.4f}")
+
+    # Vorticity
+    omega_vort = vorticity_from_ddf(ff, u0=U0)
+    save_vorticity_png(os.path.join(output_root, "vorticity_v22.png"),
+                       omega_vort, title=f"Re{re_code} v22 (front no-bias)")
+
+    # Save result
+    result = {"re_code": re_code, "mode": "v22", "similarity": sim}
+    with open(os.path.join(output_root, "result_v22.json"), "w") as f:
+        json.dump(result, f, indent=2)
+
+    del ff
+    print(f"  Done -> {output_root}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

archive/analysis_crossre_scripts/validate_v23.py

@@ -0,0 +1,237 @@
+# analysis_crossre/scripts/validate_v23.py
+"""Validate v23: front no-bias + rear shared-head.
+
+Front: v2 coeffs with bias=0.
+Top: v2 coeffs unchanged.
+Bottom: -top(Gx), using G-transformed raw observations.
+
+Usage:
+    conda run -n pycuda_3_10 python validate_v23.py --re 70 --device 2
+"""
+import argparse
+import json
+import os
+import sys
+from collections import deque
+
+import numpy as np
+
+_PROJ = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+if _PROJ not in sys.path:
+    sys.path.insert(0, _PROJ)
+from LegacyCelerisLab import FlowField
+
+from utils import (
+    nu_from_re, action_to_physical, scale_action, build_karman_cloak_env,
+    add_pinball, build_observation, compute_physical_symbols,
+    save_vorticity_png, vorticity_from_ddf, compute_similarity,
+    load_legacy_configs,
+)
+from cfg import (
+    OUTPUT_DIR, SAMPLE_INTERVAL, FIFO_LEN, CONV_LEN, S_DIM,
+    ACTION_SCALE, ACTION_BIAS, U0, CONFIG_DIR,
+)
+
+DATA_TYPE = np.float32
+
+# v2 feature keys matching sindy_results_v2.json
+V2_FEAT_KEYS = [
+    "u_m", "u_a", "u_c", "v_a",
+    "Fx_tot", "Fx_rear", "Fy_tot", "Fy_diff",
+    "sin_ua", "cos_ua",
+    "a0_lag1", "a1_lag1", "a2_lag1",
+    "da0", "da1", "da2",
+]
+V2_MU_KEYS = ["mu", "mu_u_a", "mu_v_a", "mu_Fx_tot", "mu_Fy_diff", "mu_Fy_tot"]
+
+
+def apply_G_raw(obs_slice, a_prev, a_prev2):
+    """Apply mirror operator G to raw observations and actions.
+
+    obs_slice: (12,) [s0_ux,s0_uy, s1_ux,s1_uy, s2_ux,s2_uy, front_fx,front_fy, bot_fx,bot_fy, top_fx,top_fy]
+    a_prev: (3,) [aF, aB, aT]
+    a_prev2: (3,) [aF_prev2, aB_prev2, aT_prev2]
+
+    Returns (G_obs, G_a_prev, G_a_prev2)
+    """
+    # Sensors: top<->bottom swap, cross components negate
+    G_obs = np.zeros(12, dtype=np.float64)
+    G_obs[0] = obs_slice[4]    # s0_ux <- s2_ux (streamwise: no sign)
+    G_obs[1] = -obs_slice[5]   # s0_uy <- -s2_uy (cross: negate)
+    G_obs[2] = obs_slice[2]    # s1_ux unchanged
+    G_obs[3] = -obs_slice[3]   # s1_uy negate
+    G_obs[4] = obs_slice[0]    # s2_ux <- s0_ux
+    G_obs[5] = -obs_slice[1]   # s2_uy <- -s0_uy
+
+    # Forces: front unchanged (but lift sign flips), bottom<->top with sign flips
+    G_obs[6] = obs_slice[6]      # front_fx unchanged
+    G_obs[7] = -obs_slice[7]     # front_fy negate
+    G_obs[8] = obs_slice[10]     # bot_fx <- top_fx
+    G_obs[9] = -obs_slice[11]    # bot_fy <- -top_fy
+    G_obs[10] = obs_slice[8]     # top_fx <- bot_fx
+    G_obs[11] = -obs_slice[9]    # top_fy <- -bot_fy
+
+    # Actions: all negate, B<->T swap
+    G_a_prev = np.array([-a_prev[0], -a_prev[2], -a_prev[1]], dtype=np.float64)
+    G_a_prev2 = np.array([-a_prev2[0], -a_prev2[2], -a_prev2[1]], dtype=np.float64)
+
+    return G_obs, G_a_prev, G_a_prev2
+
+
+def build_v2_feature_vec(obs_slice, actions_prev, actions_prev2, mu, add_bias):
+    """Build feature vector matching v2 layout."""
+    sensors = obs_slice[0:6].astype(np.float64).reshape(1, 6)
+    forces = obs_slice[6:12].astype(np.float64).reshape(1, 6)
+    ap = actions_prev.astype(np.float64).reshape(1, 3)
+    ap2 = actions_prev2.astype(np.float64).reshape(1, 3)
+
+    sym = compute_physical_symbols(sensors, forces, ap, ap2)
+    sym["mu"] = np.array([mu])
+    sym["mu_u_a"] = sym["u_a"] * mu
+    sym["mu_v_a"] = sym["v_a"] * mu
+    sym["mu_Fx_tot"] = sym["Fx_tot"] * mu
+    sym["mu_Fy_diff"] = sym["Fy_diff"] * mu
+    sym["mu_Fy_tot"] = sym["Fy_tot"] * mu
+
+    vals = []
+    if add_bias:
+        vals.append(1.0)
+    for k in V2_FEAT_KEYS:
+        vals.append(float(sym[k][0]))
+    for k in V2_MU_KEYS:
+        vals.append(float(sym[k][0]))
+    return np.array(vals, dtype=np.float64)
+
+
+def load_v2_coefs(v2_path):
+    """Load v2 coefficients. Zero front bias. Return front + top only."""
+    with open(v2_path) as f:
+        data = json.load(f)
+    cross = data["cross_re"]
+    coefs_list = cross["channels"]
+
+    # Zero front bias
+    coefs_list[0]["best_coef"][0] = 0.0
+
+    return {
+        "front": {
+            "coef": np.array(coefs_list[0]["best_coef"], dtype=np.float64),
+            "has_bias": True,
+        },
+        "top": {
+            "coef": np.array(coefs_list[2]["best_coef"], dtype=np.float64),
+            "has_bias": True,
+        },
+    }
+
+
+def predict_v23(obs_slice, a_prev, a_prev2, coefs, mu):
+    """Predict physical omega using v23 shared-head.
+
+    Front: v2 coefs (bias zeroed).
+    Top: v2 coefs unchanged.
+    Bottom: -top(Gx).
+    """
+    # Front prediction
+    feat = build_v2_feature_vec(obs_slice, a_prev, a_prev2, mu, add_bias=coefs["front"]["has_bias"])
+    front = float(feat @ coefs["front"]["coef"])
+
+    # Top prediction (from original state)
+    feat_top = build_v2_feature_vec(obs_slice, a_prev, a_prev2, mu, add_bias=coefs["top"]["has_bias"])
+    top = float(feat_top @ coefs["top"]["coef"])
+
+    # Bottom = -top(Gx)
+    G_obs, G_a_prev, G_a_prev2 = apply_G_raw(obs_slice, a_prev, a_prev2)
+    feat_G = build_v2_feature_vec(G_obs, G_a_prev, G_a_prev2, mu, add_bias=coefs["top"]["has_bias"])
+    top_at_Gx = float(feat_G @ coefs["top"]["coef"])
+    bottom = -top_at_Gx
+
+    return np.array([front, bottom, top], dtype=np.float64)
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--re", type=int, default=70)
+    ap.add_argument("--device", type=int, default=2)
+    ap.add_argument("--steps", type=int, default=100)
+    ap.add_argument("--out-dir", type=str, default=os.path.join(OUTPUT_DIR, "sindy_val"))
+    ap.add_argument("--v2-results", type=str,
+                    default=os.path.join(OUTPUT_DIR, "sindy", "sindy_results_v2.json"))
+    args = ap.parse_args()
+
+    re_code = args.re
+    mu = 2.0 / re_code
+    output_root = os.path.join(args.out_dir, f"re{re_code}")
+    os.makedirs(output_root, exist_ok=True)
+
+    print(f"\n=== v23 validation: Re{re_code} (mu={mu:.6f}) ===")
+
+    coefs = load_v2_coefs(args.v2_results)
+    for name in ["front", "top"]:
+        print(f"  {name}: {len(coefs[name]['coef'])} coefs")
+
+    # Build environment
+    cuda_cfg, field_cfg = load_legacy_configs(CONFIG_DIR)
+    field_cfg = field_cfg._replace(viscosity=float(nu_from_re(re_code, u0=U0)))
+    ff = FlowField(field_cfg, cuda_cfg, device_id=args.device)
+
+    target_states, _ = build_karman_cloak_env(
+        ff, u0=U0, l0=20.0, sample_interval=SAMPLE_INTERVAL,
+        fifo_len=FIFO_LEN, data_type=DATA_TYPE)
+    norm = add_pinball(
+        ff, l0=20.0, u0=U0, sample_interval=SAMPLE_INTERVAL,
+        fifo_len=FIFO_LEN, data_type=DATA_TYPE, action_bias=ACTION_BIAS)
+
+    # Controlled rollout
+    ff.restore_ddf()
+    ff.apply_ddf()
+    fifo = deque(maxlen=FIFO_LEN)
+    bias_action = scale_action(np.zeros(3, dtype=np.float32),
+                                scale=ACTION_SCALE, bias=ACTION_BIAS,
+                                u0=U0, n_total_bodies=7)
+    for _ in range(FIFO_LEN):
+        ff.run(SAMPLE_INTERVAL, bias_action)
+        fifo.append(ff.obs.copy()[2:14])
+
+    sens_sc = []
+    a_prev = action_to_physical(np.zeros((1,3), dtype=np.float32),
+                                 scale=ACTION_SCALE, bias=ACTION_BIAS, u0=U0).flatten()
+    a_prev2 = a_prev.copy()
+
+    for step in range(args.steps):
+        obs_slice = fifo[-1] if len(fifo) > 0 else np.zeros(12, dtype=np.float32)
+        omega = predict_v23(obs_slice, a_prev, a_prev2, coefs, mu)
+
+        # Apply action
+        norm_action = (omega / U0 - np.array(ACTION_BIAS, dtype=np.float64)) / ACTION_SCALE
+        norm_action = np.clip(norm_action, -1.0, 1.0).astype(np.float32)
+        action_arr = scale_action(norm_action, scale=ACTION_SCALE,
+                                   bias=ACTION_BIAS, u0=U0, n_total_bodies=7)
+        ff.run(SAMPLE_INTERVAL, action_arr)
+
+        obs_slice_new = ff.obs.copy()[2:14]
+        fifo.append(obs_slice_new)
+        sens_sc.append(obs_slice_new[0:6])
+        a_prev2 = a_prev.copy()
+        a_prev = omega.copy()
+
+    sens_arr = np.array(sens_sc, dtype=np.float32)
+    sim = compute_similarity(target_states, sens_arr, CONV_LEN)
+    print(f"  v23 similarity: {sim:.4f}")
+
+    # Vorticity
+    omega_vort = vorticity_from_ddf(ff, u0=U0)
+    save_vorticity_png(os.path.join(output_root, "vorticity_v23.png"),
+                       omega_vort, title=f"Re{re_code} v23 (shared-head)")
+
+    result = {"re_code": re_code, "mode": "v23", "similarity": sim}
+    with open(os.path.join(output_root, "result_v23.json"), "w") as f:
+        json.dump(result, f, indent=2)
+
+    del ff
+    print(f"  Done -> {output_root}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

archive/dante_pinball/dante_pinball/legacy/d1a3o12_250421_dante_v6.py

@@ -0,0 +1,755 @@
+"""
+DANTE v6 (full-adjustable, no SINDy pretraining)
+
+Core decisions for this version:
+1) Disable SINDy prior structure usage entirely.
+2) Use full simplified basis pool and optimize all controller coefficients.
+3) Keep minimal loop: no resume/checkpoint restore, live DB save + reward-only TB.
+4) Continuous rollout objective with protective reset only on done/truncated.
+"""
+
+import argparse
+import json
+import os
+import pickle
+import shutil
+import sys
+import time
+from pathlib import Path
+from typing import Dict, List
+
+import numpy as np
+
+os.environ["MKL_THREADING_LAYER"] = "GNU"
+os.environ["OMP_NUM_THREADS"] = "16"
+os.environ["MKL_NUM_THREADS"] = "16"
+
+try:
+    from torch.utils.tensorboard import SummaryWriter
+except Exception:
+    SummaryWriter = None
+
+
+CURRENT_DIR = os.path.dirname(os.path.abspath(__file__))
+ROOT = os.path.abspath(os.path.join(CURRENT_DIR, os.pardir))
+os.chdir(CURRENT_DIR)
+sys.path.insert(0, os.path.join(ROOT, "DANTE"))
+
+from dante.obj_functions import ObjectiveFunction
+from dante.tree_exploration import TreeExploration
+
+from dante_v6_surrogate_torch import FlowControlSurrogateV6
+from dante_pinball.env.gym_env_dante_total_force import CustomEnv
+
+
+N_OBS = 2
+N_ACT = 3
+BIAS_SCALE = 1.0
+COEF_SCALE = 2.0
+
+# Full simplified basis pool: all terms are trainable in v6.
+FULL_BASIS_TERMS = [
+    "obs0", "obs1", "dobs0", "dobs1",
+    "sin_obs0", "sin_obs1", "cos_obs0", "cos_obs1",
+    "tanh_obs0", "tanh_obs1",
+    "act0_l1", "act1_l1", "act2_l1",
+]
+
+BASIS_PROFILES = {
+    # Compact profile (<20 dims) with derivative + nonlinear terms.
+    "compact_deriv_nl": ["obs0", "obs1", "dobs0", "dobs1", "tanh_obs1"],
+    # Constrained search top performer (<20 dims) with nonlinear + history.
+    "compact_nl_hist": ["obs1", "sin_obs0", "cos_obs0", "act1_l1"],
+}
+
+
+# Fixed run configuration (kept in-file for reproducibility and stricter control)
+V6_CONFIG = {
+    "name": "d1a3o12_250421_forces02_dante_v6",
+    "device_id": 1,
+    "surrogate_gpu_id": 1,
+    "eval_steps": 300,
+    "tail_steps": 100,
+    "startup_steps": 0,
+    "max_recover_resets": 1,
+    "reset_each_candidate": True,
+    "obs_fail_bound": 2.0,
+    "obs_clip_bound": 3.0,
+    "basis_profile": "compact_deriv_nl",
+    # Use d-dependent initialization, then clamp into [min_num_initial, max_num_initial].
+    "num_initial_per_dim": 10,
+    "min_num_initial": 100,
+    "max_num_initial": 240,
+    "samples_per_acq": 18,
+    "max_init_attempts_factor": 2.0,
+    "surrogate_mode": "ensemble",  # mlp | cnn | ensemble
+    # Match PPO script budget: 100 learn iterations * 2048 rollout steps
+    "target_cfd_steps": 204800*2,
+    # Keep consistent with surrogate study runs in this repo.
+    "surrogate_epochs": 400,
+}
+
+
+class NullWriter:
+    def add_scalar(self, *_args, **_kwargs) -> None:
+        pass
+
+    def close(self) -> None:
+        pass
+
+
+class LinearBasisController:
+    def __init__(self, basis_terms: List[str]):
+        self.basis_terms = list(basis_terms)
+        self.num_basis = len(self.basis_terms)
+        self.total_params = N_ACT * (1 + self.num_basis)
+
+        self.params = np.zeros(self.total_params, dtype=np.float64)
+        self.obs_l1 = np.zeros(2, dtype=np.float64)
+        self.prev_action = np.zeros(3, dtype=np.float64)
+
+    def reset_state(self, obs0: np.ndarray) -> None:
+        obs0 = np.asarray(obs0, dtype=np.float64).reshape(-1)
+        if obs0.size < 2:
+            if obs0.size == 1:
+                obs0 = np.array([obs0[0], obs0[0]], dtype=np.float64)
+            else:
+                obs0 = np.zeros(2, dtype=np.float64)
+        self.obs_l1 = obs0[:2].copy()
+        self.prev_action = np.zeros(3, dtype=np.float64)
+
+    def set_params(self, x: np.ndarray) -> None:
+        x = np.asarray(x, dtype=np.float64).reshape(-1)
+        if x.size != self.total_params:
+            raise ValueError(f"controller params mismatch: {x.size} != {self.total_params}")
+        self.params = np.clip(x, -1.0, 1.0)
+
+    def _feature_dict(self, obs: np.ndarray) -> Dict[str, float]:
+        o = np.asarray(obs, dtype=np.float64).reshape(-1)
+        if o.size < 2:
+            if o.size == 1:
+                o = np.array([o[0], o[0]], dtype=np.float64)
+            else:
+                o = np.zeros(2, dtype=np.float64)
+
+        o0, o1 = float(o[0]), float(o[1])
+        o0_l1, o1_l1 = float(self.obs_l1[0]), float(self.obs_l1[1])
+        a0, a1, a2 = float(self.prev_action[0]), float(self.prev_action[1]), float(self.prev_action[2])
+
+        return {
+            "obs0": o0,
+            "obs1": o1,
+            "dobs0": o0 - o0_l1,
+            "dobs1": o1 - o1_l1,
+            "sin_obs0": float(np.sin(np.pi * o0)),
+            "sin_obs1": float(np.sin(np.pi * o1)),
+            "cos_obs0": float(np.cos(np.pi * o0)),
+            "cos_obs1": float(np.cos(np.pi * o1)),
+            "tanh_obs0": float(np.tanh(o0)),
+            "tanh_obs1": float(np.tanh(o1)),
+            "act0_l1": a0,
+            "act1_l1": a1,
+            "act2_l1": a2,
+        }
+
+    def predict(self, obs: np.ndarray) -> np.ndarray:
+        feat = self._feature_dict(obs)
+        out = np.zeros(3, dtype=np.float64)
+        stride = 1 + self.num_basis
+
+        for ch in range(3):
+            off = ch * stride
+            qb = np.tanh(1.25 * self.params[off])
+            y = BIAS_SCALE * qb
+            for k, term in enumerate(self.basis_terms):
+                qk = np.tanh(1.25 * self.params[off + 1 + k])
+                y += (COEF_SCALE * qk) * feat.get(term, 0.0)
+            out[ch] = y
+
+        out = np.clip(out, -1.0, 1.0)
+
+        obs2 = np.asarray(obs, dtype=np.float64).reshape(-1)
+        if obs2.size < 2:
+            if obs2.size == 1:
+                obs2 = np.array([obs2[0], obs2[0]], dtype=np.float64)
+            else:
+                obs2 = np.zeros(2, dtype=np.float64)
+
+        self.obs_l1 = obs2[:2].copy()
+        self.prev_action = out.copy()
+        return out.astype(np.float32)
+
+
+class FlowControlObjectiveV6(ObjectiveFunction):
+    def __init__(
+        self,
+        basis_terms: List[str],
+        eval_steps: int = 200,
+        tail_steps: int = 100,
+        startup_steps: int = 200,
+        max_recover_resets: int = 1,
+        turn: float = 0.05,
+        reset_each_candidate: bool = True,
+        obs_fail_bound: float = 2.0,
+        obs_clip_bound: float = 3.0,
+    ):
+        self.eval_steps = int(eval_steps)
+        self.tail_steps = int(tail_steps)
+        self.startup_steps = int(startup_steps)
+        self.max_recover_resets = int(max_recover_resets)
+        self.turn = float(turn)
+        self.reset_each_candidate = bool(reset_each_candidate)
+        self.obs_fail_bound = float(obs_fail_bound)
+        self.obs_clip_bound = float(obs_clip_bound)
+
+        self.basis_terms = list(basis_terms)
+        self.controller = LinearBasisController(self.basis_terms)
+        self.dims = int(self.controller.total_params)
+
+        self.lb = -1.0 * np.ones(self.dims)
+        self.ub = 1.0 * np.ones(self.dims)
+
+        self.env = None
+        self._device_id = 1
+        self.obs_current = None
+        self.recover_count = 0
+
+    def init_env(self, device_id: int = 1) -> None:
+        self._device_id = int(device_id)
+        if self.env is not None:
+            self.env.close()
+        self.env = CustomEnv(
+            device_id=int(device_id),
+            obs_fail_bound=float(self.obs_fail_bound),
+            obs_clip_bound=float(self.obs_clip_bound),
+        )
+        self._hard_reset_and_stabilize()
+
+    def _hard_reset_and_stabilize(self) -> None:
+        obs, _ = self.env.reset()
+        obs = np.asarray(obs, dtype=np.float32)
+        action = np.zeros(3, dtype=np.float32)
+
+        for _ in range(int(self.startup_steps)):
+            obs, _, done, trunc, _ = self.env.step(action)
+            if done or trunc:
+                obs, _ = self.env.reset()
+
+        self.obs_current = np.asarray(obs, dtype=np.float32)
+        self.controller.reset_state(self.obs_current)
+
+    @staticmethod
+    def _tail_mean(rewards: List[float], tail_steps: int) -> float:
+        rr = np.asarray(rewards, dtype=np.float64)
+        if rr.size == 0:
+            return 0.0
+        tail = rr[-tail_steps:] if rr.size >= tail_steps else rr
+        return float(np.mean(tail))
+
+    def evaluate_candidate(self, x: np.ndarray) -> Dict:
+        x = self._preprocess(x)
+        self.controller.set_params(x)
+
+        if self.env is None:
+            self.init_env(self._device_id)
+
+        # DANTE candidate evaluations are isolated from each other.
+        if self.reset_each_candidate:
+            self._hard_reset_and_stabilize()
+
+        for attempt in range(int(self.max_recover_resets) + 1):
+            obs = np.asarray(self.obs_current, dtype=np.float32)
+            self.controller.reset_state(obs)
+
+            rewards: List[float] = []
+            steps = 0
+            done = False
+            trunc = False
+            last_info: Dict = {}
+
+            for _ in range(int(self.eval_steps)):
+                action = self.controller.predict(obs)
+                obs, reward, done, trunc, step_info = self.env.step(action)
+                if isinstance(step_info, dict):
+                    last_info = step_info
+                rewards.append(float(reward))
+                steps += 1
+                if done or trunc:
+                    break
+
+            if done or trunc and attempt < int(self.max_recover_resets):
+                self.recover_count += 1
+                self._hard_reset_and_stabilize()
+                continue
+
+            self.obs_current = np.asarray(obs, dtype=np.float32)
+            y = self._tail_mean(rewards, tail_steps=int(self.tail_steps))
+            return {
+                "reward": float(y),
+                "scaled": float(y * 100.0),
+                "steps": int(steps),
+                "done": bool(done),
+                "truncated": bool(trunc),
+                "recoveries_used": int(attempt),
+                "failure_code": int(last_info.get("failure_code", 0)),
+            }
+
+        return {
+            "reward": 0.0,
+            "scaled": 0.0,
+            "steps": 0,
+            "done": True,
+            "truncated": True,
+            "recoveries_used": int(self.max_recover_resets),
+            "failure_code": 1,
+        }
+
+    def scaled(self, y: float) -> float:
+        return float(y * 100.0)
+
+    def __call__(self, x: np.ndarray, apply_scaling: bool = False, track: bool = True) -> float:
+        info = self.evaluate_candidate(x)
+        y = float(info["reward"])
+        return self.scaled(y) if apply_scaling else y
+
+
+def parse_args() -> argparse.Namespace:
+    p = argparse.ArgumentParser(description="DANTE v6 full-adjustable (no SINDy pretraining)")
+    p.add_argument(
+        "--name",
+        type=str,
+        default=V6_CONFIG["name"],
+        help="Optional run name override. Core budgets remain fixed in-file.",
+    )
+    p.add_argument(
+        "--basis-profile",
+        type=str,
+        default=V6_CONFIG["basis_profile"],
+        choices=sorted(BASIS_PROFILES.keys()),
+        help="Controller basis profile to optimize.",
+    )
+    return p.parse_args()
+
+
+def sample_params(dims: int, turn: float) -> np.ndarray:
+    x = np.random.uniform(-1.0, 1.0, size=dims)
+    x = np.round(x / turn) * turn
+    return np.clip(x, -1.0, 1.0)
+
+
+def save_live_db(path: str, x: np.ndarray, y: np.ndarray, meta: Dict) -> None:
+    np.savez(path, input_x=x, input_y=y, meta_json=np.array([json.dumps(meta, ensure_ascii=False)]))
+
+
+def print_progress_line(
+    phase: str,
+    idx: int,
+    total: int,
+    reward: float,
+    best_reward: float,
+    recover_total: int,
+    elapsed_sec: float,
+    global_step: int,
+    total_expected: int,
+) -> None:
+    print(
+        f"[{phase}] {idx}/{total} | reward={reward:.4f} | best={best_reward:.4f} | "
+        f"recover={recover_total} | eval={global_step}/{total_expected} | elapsed={elapsed_sec:.1f}s",
+        flush=True,
+    )
+
+
+def main() -> None:
+    args = parse_args()
+
+    name = str(args.name)
+    cfg = dict(V6_CONFIG)
+    cfg["name"] = name
+
+    basis_profile = str(args.basis_profile)
+    basis_terms = list(BASIS_PROFILES[basis_profile])
+
+    target_evals = int(cfg["target_cfd_steps"] // cfg["eval_steps"])
+
+    model_dir = os.path.join(ROOT, "models", "250421")
+    out_dir = os.path.join(ROOT, "output")
+    tb_dir = os.path.join(ROOT, "tensorboard", name)
+    os.makedirs(model_dir, exist_ok=True)
+    os.makedirs(out_dir, exist_ok=True)
+
+    obj = FlowControlObjectiveV6(
+        basis_terms=basis_terms,
+        eval_steps=int(cfg["eval_steps"]),
+        tail_steps=int(cfg["tail_steps"]),
+        startup_steps=int(cfg["startup_steps"]),
+        max_recover_resets=int(cfg["max_recover_resets"]),
+        reset_each_candidate=bool(cfg["reset_each_candidate"]),
+        obs_fail_bound=float(cfg["obs_fail_bound"]),
+        obs_clip_bound=float(cfg["obs_clip_bound"]),
+    )
+    obj.init_env(device_id=int(cfg["device_id"]))
+
+    controller_dims = int(obj.dims)
+    surrogate_gpu_id = int(cfg["surrogate_gpu_id"])
+    num_initial_raw = int(max(1, round(float(cfg["num_initial_per_dim"]) * controller_dims)))
+    num_initial = int(min(int(cfg["max_num_initial"]), max(int(cfg["min_num_initial"]), num_initial_raw)))
+    num_acquisitions = int((target_evals - int(num_initial)) // int(cfg["samples_per_acq"]))
+    if num_acquisitions <= 0:
+        raise RuntimeError(
+            f"computed num_acquisitions <= 0 with target_evals={target_evals}, "
+            f"num_initial={num_initial}, samples_per_acq={int(cfg['samples_per_acq'])}"
+        )
+    max_init_attempts = int(max(num_initial, round(float(cfg["max_init_attempts_factor"]) * num_initial)))
+    if max_init_attempts < num_initial:
+        raise RuntimeError("max_init_attempts must be >= num_initial")
+    total_expected = int(num_initial + num_acquisitions * int(cfg["samples_per_acq"]))
+
+    config_payload = {
+        "name": name,
+        "use_sindy_prior": False,
+        "reason": "forced_disabled_by_v6_full_adjustable",
+        "basis_profile": basis_profile,
+        "basis_terms": basis_terms,
+        "controller_dims": controller_dims,
+        "num_initial": num_initial,
+        "num_initial_raw": int(num_initial_raw),
+        "num_initial_per_dim": float(cfg["num_initial_per_dim"]),
+        "min_num_initial": int(cfg["min_num_initial"]),
+        "max_num_initial": int(cfg["max_num_initial"]),
+        "num_acquisitions": int(num_acquisitions),
+        "samples_per_acq": int(cfg["samples_per_acq"]),
+        "surrogate_mode": str(cfg["surrogate_mode"]),
+        "surrogate_gpu_id": int(surrogate_gpu_id),
+        "eval_steps": int(cfg["eval_steps"]),
+        "tail_steps": int(cfg["tail_steps"]),
+        "startup_steps": int(cfg["startup_steps"]),
+        "max_recover_resets": int(cfg["max_recover_resets"]),
+        "obs_fail_bound": float(cfg["obs_fail_bound"]),
+        "obs_clip_bound": float(cfg["obs_clip_bound"]),
+        "reset_each_candidate": bool(cfg["reset_each_candidate"]),
+        "max_init_attempts": int(max_init_attempts),
+        "max_init_attempts_factor": float(cfg["max_init_attempts_factor"]),
+        "target_cfd_steps": int(cfg["target_cfd_steps"]),
+        "target_total_evals": int(target_evals),
+        "matched_total_evals": int(total_expected),
+        "matched_cfd_steps": int(total_expected * int(cfg["eval_steps"])),
+    }
+    with open(os.path.join(out_dir, f"{name}_structure_decision.json"), "w", encoding="utf-8") as f:
+        json.dump(config_payload, f, indent=2, ensure_ascii=False)
+
+    print("use_sindy_prior:", False)
+    print("basis_profile:", basis_profile)
+    print("basis_terms:", len(basis_terms))
+    print("controller_dims:", controller_dims)
+    print("num_initial:", num_initial)
+    print("num_initial_raw:", int(num_initial_raw))
+    print("num_initial_per_dim:", float(cfg["num_initial_per_dim"]))
+    print("min_num_initial:", int(cfg["min_num_initial"]))
+    print("max_num_initial:", int(cfg["max_num_initial"]))
+    print("max_init_attempts:", max_init_attempts)
+    print("max_init_attempts_factor:", float(cfg["max_init_attempts_factor"]))
+    print("num_acquisitions:", int(num_acquisitions))
+    print("samples_per_acq:", int(cfg["samples_per_acq"]))
+    print("surrogate_mode:", str(cfg["surrogate_mode"]))
+    print("surrogate_gpu_id:", surrogate_gpu_id)
+    print("eval_steps:", int(cfg["eval_steps"]))
+    print("tail_steps:", int(cfg["tail_steps"]))
+    print("startup_steps:", int(cfg["startup_steps"]))
+    print("target_cfd_steps:", int(cfg["target_cfd_steps"]))
+    print("matched_cfd_steps:", int(total_expected * int(cfg["eval_steps"])))
+    print("expected_total_evals:", total_expected)
+
+    ckpt_path = Path(os.path.join(model_dir, f"{name}_surrogate.keras"))
+    surrogate = FlowControlSurrogateV6(
+        input_dims=controller_dims,
+        epochs=int(cfg["surrogate_epochs"]),
+        patience=30,
+        check_point_path=ckpt_path,
+        tf_device_id=int(surrogate_gpu_id),
+    )
+
+    live_db_path = os.path.join(out_dir, f"{name}_database_live.npz")
+    best_params_path = os.path.join(model_dir, f"{name}_best.npy")
+    best_meta_path = os.path.join(out_dir, f"{name}_best_meta.pkl")
+    final_meta_path = os.path.join(out_dir, f"{name}_final_meta.pkl")
+    dante_log_path = os.path.join(out_dir, f"{name}_dante_log.csv")
+
+    if SummaryWriter is None:
+        writer = NullWriter()
+    else:
+        writer = SummaryWriter(log_dir=tb_dir)
+
+    with open(dante_log_path, "w", encoding="utf-8") as f:
+        f.write("timestamp,phase,acq,candidate,reward,best_reward,dataset_size,recoveries_used,failure_code\n")
+
+    input_x = np.empty((0, controller_dims), dtype=np.float64)
+    input_y = np.empty((0,), dtype=np.float64)
+    history = []
+    best_reward = -1.0
+    best_params = np.zeros(controller_dims, dtype=np.float64)
+    invalid_skips = 0
+
+    t0 = time.time()
+    global_step = 0
+
+    try:
+        # Phase 1: random init points (collect exactly num_initial valid samples)
+        valid_init = 0
+        init_attempts = 0
+        while valid_init < num_initial:
+            if init_attempts >= max_init_attempts:
+                raise RuntimeError(
+                    f"init failed to collect enough valid samples: "
+                    f"valid={valid_init}/{num_initial}, attempts={init_attempts}/{max_init_attempts}, "
+                    f"invalid_skips={invalid_skips}"
+                )
+
+            init_attempts += 1
+            x = sample_params(controller_dims, obj.turn)
+            info = obj.evaluate_candidate(x)
+            reward = float(info["reward"])
+            is_valid = int(info.get("failure_code", 0)) == 0
+
+            if is_valid:
+                valid_init += 1
+                input_x = np.vstack((input_x, x.reshape(1, -1)))
+                input_y = np.append(input_y, float(info["scaled"]))
+                writer.add_scalar("Reward", reward, global_step)
+            else:
+                invalid_skips += 1
+                print(
+                    f"[init] invalid sample skipped: attempt={init_attempts}, "
+                    f"failure_code={info.get('failure_code', -1)}, "
+                    f"valid={valid_init}/{num_initial}, invalid_skips={invalid_skips}",
+                    flush=True,
+                )
+
+            if is_valid and reward > best_reward:
+                best_reward = reward
+                best_params = x.copy()
+                np.save(best_params_path, best_params)
+                with open(best_meta_path, "wb") as f:
+                    pickle.dump(
+                        {
+                            "best_reward": best_reward,
+                            "best_params": best_params,
+                            "basis_terms": basis_terms,
+                            "controller_dims": controller_dims,
+                            "config": config_payload,
+                            "timestamp": time.time(),
+                        },
+                        f,
+                    )
+
+            if is_valid:
+                save_live_db(
+                    live_db_path,
+                    input_x,
+                    input_y,
+                    {
+                        "name": name,
+                        "best_reward": best_reward,
+                        "dataset_size": int(len(input_y)),
+                        "basis_terms": basis_terms,
+                        "use_sindy_prior": False,
+                        "recover_count": int(obj.recover_count),
+                        "invalid_skips": int(invalid_skips),
+                    },
+                )
+
+            with open(dante_log_path, "a", encoding="utf-8") as f:
+                f.write(
+                    f"{time.time():.3f},init,0,{init_attempts},{reward:.8f},{best_reward:.8f},{len(input_y)},{info['recoveries_used']},{info.get('failure_code', 0)}\n"
+                )
+
+            global_step += 1
+            print(
+                f"[init-attempt {init_attempts}/{max_init_attempts}] "
+                f"valid={valid_init}/{num_initial} | reward={reward:.4f} | "
+                f"best={best_reward:.4f} | invalid_skips={invalid_skips} | "
+                f"recover={int(obj.recover_count)} | eval={global_step}/{total_expected}+ | "
+                f"elapsed={float(time.time() - t0):.1f}s",
+                flush=True,
+            )
+
+        # Phase 2: DANTE acquisitions
+        for acq in range(int(num_acquisitions)):
+            if len(input_y) < 2:
+                print(
+                    f"[acq {acq + 1}] skipped: insufficient valid samples ({len(input_y)})",
+                    flush=True,
+                )
+                continue
+            print(
+                f"[acq {acq + 1}/{int(num_acquisitions)}] fitting surrogate on {len(input_y)} samples...",
+                flush=True,
+            )
+            surrogate_mode = str(cfg.get("surrogate_mode", "mlp")).lower()
+            if surrogate_mode == "ensemble":
+                candidates = []
+                for arch in ["mlp", "cnn"]:
+                    cand_ckpt = Path(str(ckpt_path).replace(".keras", f"_{arch}.keras"))
+                    surr = FlowControlSurrogateV6(
+                        input_dims=controller_dims,
+                        epochs=int(cfg["surrogate_epochs"]),
+                        patience=30,
+                        check_point_path=cand_ckpt,
+                        tf_device_id=int(surrogate_gpu_id),
+                        architecture=arch,
+                    )
+                    try:
+                        m = surr(input_x, input_y, verbose=0)
+                        fm = dict(getattr(surr, "last_fit_metrics", {}) or {})
+                        candidates.append((arch, m, fm, cand_ckpt))
+                    except Exception as e:
+                        print(f"[acq {acq + 1}] surrogate {arch} failed: {e}", flush=True)
+                if not candidates:
+                    raise RuntimeError("all surrogate candidates failed in ensemble mode")
+                candidates.sort(key=lambda z: float(z[2].get("val_r2", -1e9)), reverse=True)
+                best_arch, model, fit_metrics, best_ckpt = candidates[0]
+                if best_ckpt.exists():
+                    shutil.copy2(best_ckpt, ckpt_path)
+                fit_metrics["selected_architecture"] = best_arch
+            else:
+                surrogate.architecture = "cnn" if surrogate_mode == "cnn" else "mlp"
+                model = surrogate(input_x, input_y, verbose=0)
+                fit_metrics = dict(getattr(surrogate, "last_fit_metrics", {}) or {})
+                fit_metrics["selected_architecture"] = str(surrogate.architecture)
+            if fit_metrics:
+                writer.add_scalar("Surrogate/val_r2", float(fit_metrics.get("val_r2", 0.0)), acq)
+                writer.add_scalar("Surrogate/val_mae", float(fit_metrics.get("val_mae", 0.0)), acq)
+                print(
+                    f"[acq {acq + 1}] surrogate metrics: "
+                    f"val_r2={fit_metrics.get('val_r2', float('nan')):.4f}, "
+                    f"val_mae={fit_metrics.get('val_mae', float('nan')):.4f}, "
+                    f"device={fit_metrics.get('device', 'CPU')}",
+                    flush=True,
+                )
+            print(
+                f"[acq {acq + 1}/{int(num_acquisitions)}] surrogate fit done, rolling out {int(cfg['samples_per_acq'])} candidates...",
+                flush=True,
+            )
+            if ckpt_path.exists():
+                shutil.copy2(ckpt_path, os.path.join(model_dir, f"{name}_surrogate_live.keras"))
+
+            explorer = TreeExploration(
+                func=obj,
+                model=model,
+                num_samples_per_acquisition=int(cfg["samples_per_acq"]),
+            )
+            candidates = explorer.rollout(input_x, input_y, iteration=acq)
+
+            acq_rewards = []
+            for j, x in enumerate(candidates):
+                info = obj.evaluate_candidate(x)
+                reward = float(info["reward"])
+                is_valid = int(info.get("failure_code", 0)) == 0
+                if is_valid:
+                    acq_rewards.append(reward)
+
+                    input_x = np.vstack((input_x, np.asarray(x, dtype=np.float64).reshape(1, -1)))
+                    input_y = np.append(input_y, float(info["scaled"]))
+                    writer.add_scalar("Reward", reward, global_step)
+
+                    if reward > best_reward:
+                        best_reward = reward
+                        best_params = np.asarray(x, dtype=np.float64).copy()
+                        np.save(best_params_path, best_params)
+                        with open(best_meta_path, "wb") as f:
+                            pickle.dump(
+                                {
+                                    "best_reward": best_reward,
+                                    "best_params": best_params,
+                                    "basis_terms": basis_terms,
+                                    "controller_dims": controller_dims,
+                                    "config": config_payload,
+                                    "timestamp": time.time(),
+                                },
+                                f,
+                            )
+
+                    save_live_db(
+                        live_db_path,
+                        input_x,
+                        input_y,
+                        {
+                            "name": name,
+                            "best_reward": best_reward,
+                            "dataset_size": int(len(input_y)),
+                            "basis_terms": basis_terms,
+                            "use_sindy_prior": False,
+                            "recover_count": int(obj.recover_count),
+                            "acq": int(acq + 1),
+                            "invalid_skips": int(invalid_skips),
+                        },
+                    )
+                else:
+                    invalid_skips += 1
+                    print(
+                        f"[acq {acq + 1}] invalid sample skipped: cand={j + 1}, failure_code={info.get('failure_code', -1)}",
+                        flush=True,
+                    )
+
+                with open(dante_log_path, "a", encoding="utf-8") as f:
+                    f.write(
+                        f"{time.time():.3f},acq,{acq + 1},{j + 1},{reward:.8f},{best_reward:.8f},{len(input_y)},{info['recoveries_used']},{info.get('failure_code', 0)}\n"
+                    )
+
+                global_step += 1
+                print_progress_line(
+                    phase=f"acq{acq + 1}",
+                    idx=j + 1,
+                    total=len(candidates),
+                    reward=reward,
+                    best_reward=best_reward,
+                    recover_total=int(obj.recover_count),
+                    elapsed_sec=float(time.time() - t0),
+                    global_step=global_step,
+                    total_expected=total_expected,
+                )
+
+            history.append(
+                {
+                    "iteration": int(acq + 1),
+                    "new_mean": float(np.mean(acq_rewards) if acq_rewards else 0.0),
+                    "new_max": float(np.max(acq_rewards) if acq_rewards else 0.0),
+                    "best_reward": float(best_reward),
+                    "dataset_size": int(len(input_y)),
+                    "recover_total": int(obj.recover_count),
+                }
+            )
+
+            print(
+                f"acq {acq + 1}/{num_acquisitions}: mean={history[-1]['new_mean']:.4f}, "
+                f"max={history[-1]['new_max']:.4f}, best={best_reward:.4f}, recover_total={obj.recover_count}"
+            )
+
+        with open(final_meta_path, "wb") as f:
+            pickle.dump(
+                {
+                    "name": name,
+                    "best_reward": best_reward,
+                    "best_params": best_params,
+                    "basis_terms": basis_terms,
+                    "controller_dims": controller_dims,
+                    "history": history,
+                    "elapsed_sec": float(time.time() - t0),
+                    "config": config_payload,
+                    "recover_total": int(obj.recover_count),
+                },
+                f,
+            )
+
+        print("Training done")
+        print("best_reward:", f"{best_reward:.4f}")
+        print("recover_total:", obj.recover_count)
+        print("invalid_skips:", invalid_skips)
+
+    finally:
+        writer.close()
+        if obj.env is not None:
+            obj.env.close()
+
+
+if __name__ == "__main__":
+    main()

archive/dante_pinball/dante_pinball/legacy/d1a3o12_250421_dante_v7_openloop.py

@@ -0,0 +1,911 @@
+"""
+DANTE v7 (open-loop periodic control)
+
+This version switches from closed-loop basis feedback to a periodic open-loop controller:
+1) Optimize control points of one cycle directly.
+2) Use continuous phase advance to support non-integer cycle lengths.
+3) Keep v6-compatible evaluation protocol (300-step rollout, tail100 score).
+"""
+
+import argparse
+import json
+import os
+import pickle
+import shutil
+import sys
+import time
+from pathlib import Path
+from typing import Dict, List, Optional
+
+import numpy as np
+
+os.environ["MKL_THREADING_LAYER"] = "GNU"
+os.environ["OMP_NUM_THREADS"] = "16"
+os.environ["MKL_NUM_THREADS"] = "16"
+
+try:
+    from torch.utils.tensorboard import SummaryWriter
+except Exception:
+    SummaryWriter = None
+
+
+CURRENT_DIR = os.path.dirname(os.path.abspath(__file__))
+ROOT = os.path.abspath(os.path.join(CURRENT_DIR, os.pardir))
+os.chdir(CURRENT_DIR)
+sys.path.insert(0, os.path.join(ROOT, "DANTE"))
+
+from dante.obj_functions import ObjectiveFunction
+from dante.tree_exploration import TreeExploration
+
+from dante_v6_surrogate_torch import FlowControlSurrogateV6
+from dante_pinball.env.gym_env_dante_total_force import CustomEnv
+
+
+N_ACT = 3
+
+V7_CONFIG = {
+    "name": "d1a3o12_250421_forces02_dante_v7_openloop",
+    "device_id": 0,
+    "surrogate_gpu_id": 0,
+    "eval_steps": 300,
+    "tail_steps": 100,
+    "startup_steps": 0,
+    "max_recover_resets": 1,
+    "reset_each_candidate": True,
+    "obs_fail_bound": 2.0,
+    "obs_clip_bound": 3.0,
+    "control_points_per_channel": 8,
+    "phase_interp": "linear",
+    "period_mode": "auto",  # auto | fixed | optimize
+    "fixed_period": 40.0,
+    "period_min": 15.0,
+    "period_max": 80.0,
+    "period_estimate_files": [
+        "output/report_dante_v2_v5_v6/raw_oldenv_seed_11.npz",
+        "output/report_dante_v2_v5_v6/raw_oldenv_seed_29.npz",
+        "output/report_dante_v2_v5_v6/raw_oldenv_seed_47.npz",
+    ],
+    "period_estimate_key": "ppo_actions",
+    "num_initial_per_dim": 10,
+    "min_num_initial": 100,
+    "max_num_initial": 320,
+    "samples_per_acq": 24,
+    "max_init_attempts_factor": 2.0,
+    "surrogate_mode": "ensemble",  # mlp | cnn | ensemble
+    "target_cfd_steps": 204800*2,
+    "surrogate_epochs": 400,
+}
+
+
+class NullWriter:
+    def add_scalar(self, *_args, **_kwargs) -> None:
+        pass
+
+    def close(self) -> None:
+        pass
+
+
+def map_unit_to_range(u: float, low: float, high: float) -> float:
+    u_clip = float(np.clip(u, -1.0, 1.0))
+    alpha = 0.5 * (u_clip + 1.0)
+    return float(low + alpha * (high - low))
+
+
+def map_range_to_unit(x: float, low: float, high: float) -> float:
+    if high <= low:
+        return 0.0
+    alpha = (float(x) - low) / (high - low)
+    return float(np.clip(2.0 * alpha - 1.0, -1.0, 1.0))
+
+
+def dominant_period_fft(x: np.ndarray, min_period: float, max_period: float) -> Optional[float]:
+    x = np.asarray(x, dtype=np.float64).reshape(-1)
+    n = int(x.size)
+    if n < 16:
+        return None
+
+    xc = x - np.mean(x)
+    std = float(np.std(xc))
+    if std < 1e-8:
+        return None
+
+    yf = np.fft.rfft(xc)
+    power = (np.abs(yf) ** 2).reshape(-1)
+    freq = np.fft.rfftfreq(n, d=1.0)
+
+    with np.errstate(divide="ignore", invalid="ignore"):
+        period = np.where(freq > 0.0, 1.0 / freq, np.inf)
+
+    valid = (freq > 0.0) & (period >= float(min_period)) & (period <= float(max_period))
+    if not np.any(valid):
+        return None
+
+    idx = np.argmax(power * valid.astype(np.float64))
+    f_peak = float(freq[idx])
+    if f_peak <= 0.0:
+        return None
+    return float(1.0 / f_peak)
+
+
+def load_action_array_from_npz(npz_path: str, key_hint: str = "ppo_actions") -> np.ndarray:
+    with np.load(npz_path) as z:
+        keys = list(z.keys())
+        if key_hint in z:
+            arr = z[key_hint]
+            return np.asarray(arr, dtype=np.float64)
+
+        for k in keys:
+            kl = k.lower()
+            if "ppo" in kl and "action" in kl:
+                arr = z[k]
+                return np.asarray(arr, dtype=np.float64)
+
+        for k in keys:
+            arr = np.asarray(z[k])
+            if arr.ndim == 2 and arr.shape[1] == N_ACT:
+                return np.asarray(arr, dtype=np.float64)
+
+    raise KeyError(f"no action array found in {npz_path}")
+
+
+def estimate_period_from_npz_list(
+    rel_paths: List[str],
+    key_hint: str,
+    min_period: float,
+    max_period: float,
+) -> Dict[str, object]:
+    periods: List[float] = []
+    details: List[Dict[str, object]] = []
+
+    for rel in rel_paths:
+        abs_path = os.path.join(ROOT, rel)
+        if not os.path.exists(abs_path):
+            details.append({"file": rel, "used": False, "reason": "missing"})
+            continue
+
+        try:
+            a = load_action_array_from_npz(abs_path, key_hint=key_hint)
+            if a.ndim != 2 or a.shape[1] != N_ACT:
+                details.append({
+                    "file": rel,
+                    "used": False,
+                    "reason": f"invalid_shape_{tuple(a.shape)}",
+                })
+                continue
+
+            file_periods = []
+            for ch in range(N_ACT):
+                p = dominant_period_fft(
+                    a[:, ch],
+                    min_period=float(min_period),
+                    max_period=float(max_period),
+                )
+                if p is not None and np.isfinite(p):
+                    file_periods.append(float(p))
+                    periods.append(float(p))
+
+            details.append({
+                "file": rel,
+                "used": len(file_periods) > 0,
+                "num_channels": int(len(file_periods)),
+                "channel_periods": [float(v) for v in file_periods],
+            })
+        except Exception as e:
+            details.append({"file": rel, "used": False, "reason": str(e)})
+
+    if len(periods) == 0:
+        return {
+            "period": None,
+            "source": "none",
+            "details": details,
+            "count": 0,
+        }
+
+    period_med = float(np.median(np.asarray(periods, dtype=np.float64)))
+    period_med = float(np.clip(period_med, min_period, max_period))
+
+    return {
+        "period": period_med,
+        "source": "fft_median",
+        "details": details,
+        "count": int(len(periods)),
+        "all_periods": [float(v) for v in periods],
+    }
+
+
+class PeriodicOpenLoopController:
+    def __init__(
+        self,
+        control_points_per_channel: int,
+        period_mode: str,
+        base_period_steps: float,
+        period_min: float,
+        period_max: float,
+        interp: str = "linear",
+    ):
+        self.k = int(control_points_per_channel)
+        if self.k < 3:
+            raise ValueError("control_points_per_channel must be >= 3")
+
+        self.period_mode = str(period_mode).lower()
+        if self.period_mode not in {"auto", "fixed", "optimize"}:
+            raise ValueError("period_mode must be one of auto|fixed|optimize")
+
+        self.base_period_steps = float(base_period_steps)
+        self.period_min = float(period_min)
+        self.period_max = float(period_max)
+        self.interp = str(interp).lower()
+        if self.interp not in {"linear"}:
+            raise ValueError("only linear interpolation is currently supported")
+
+        self.optimize_period = self.period_mode == "optimize"
+
+        self.ctrl_points = np.zeros((N_ACT, self.k), dtype=np.float64)
+        self.phase = 0.0
+        self.current_period_steps = float(np.clip(self.base_period_steps, self.period_min, self.period_max))
+
+        self.total_params = int(N_ACT * self.k + (1 if self.optimize_period else 0))
+
+    def reset_state(self) -> None:
+        self.phase = 0.0
+
+    def _eval_channel(self, points: np.ndarray, phase: float) -> float:
+        p = np.asarray(points, dtype=np.float64).reshape(-1)
+        z = float(np.mod(phase, 1.0)) * self.k
+        i0 = int(np.floor(z)) % self.k
+        frac = float(z - np.floor(z))
+        i1 = (i0 + 1) % self.k
+        return float((1.0 - frac) * p[i0] + frac * p[i1])
+
+    def set_params(self, x: np.ndarray) -> None:
+        x = np.asarray(x, dtype=np.float64).reshape(-1)
+        if x.size != self.total_params:
+            raise ValueError(f"controller params mismatch: {x.size} != {self.total_params}")
+
+        core = np.clip(x[: N_ACT * self.k], -1.0, 1.0)
+        self.ctrl_points = core.reshape(N_ACT, self.k)
+
+        if self.optimize_period:
+            p_unit = float(x[-1])
+            self.current_period_steps = map_unit_to_range(p_unit, self.period_min, self.period_max)
+        else:
+            self.current_period_steps = float(np.clip(self.base_period_steps, self.period_min, self.period_max))
+
+    def predict(self, _obs: np.ndarray) -> np.ndarray:
+        action = np.zeros(N_ACT, dtype=np.float64)
+        for ch in range(N_ACT):
+            action[ch] = self._eval_channel(self.ctrl_points[ch], self.phase)
+
+        action = np.clip(action, -1.0, 1.0)
+
+        step_phase = 1.0 / max(1e-6, float(self.current_period_steps))
+        self.phase = float((self.phase + step_phase) % 1.0)
+
+        return action.astype(np.float32)
+
+
+class FlowControlObjectiveV7(ObjectiveFunction):
+    def __init__(
+        self,
+        control_points_per_channel: int,
+        period_mode: str,
+        period_steps: float,
+        period_min: float,
+        period_max: float,
+        phase_interp: str = "linear",
+        eval_steps: int = 300,
+        tail_steps: int = 100,
+        startup_steps: int = 0,
+        max_recover_resets: int = 1,
+        turn: float = 0.05,
+        reset_each_candidate: bool = True,
+        obs_fail_bound: float = 2.0,
+        obs_clip_bound: float = 3.0,
+    ):
+        self.eval_steps = int(eval_steps)
+        self.tail_steps = int(tail_steps)
+        self.startup_steps = int(startup_steps)
+        self.max_recover_resets = int(max_recover_resets)
+        self.turn = float(turn)
+        self.reset_each_candidate = bool(reset_each_candidate)
+        self.obs_fail_bound = float(obs_fail_bound)
+        self.obs_clip_bound = float(obs_clip_bound)
+
+        self.control_points_per_channel = int(control_points_per_channel)
+        self.period_mode = str(period_mode)
+        self.period_steps = float(period_steps)
+        self.period_min = float(period_min)
+        self.period_max = float(period_max)
+        self.phase_interp = str(phase_interp)
+
+        self.controller = PeriodicOpenLoopController(
+            control_points_per_channel=self.control_points_per_channel,
+            period_mode=self.period_mode,
+            base_period_steps=self.period_steps,
+            period_min=self.period_min,
+            period_max=self.period_max,
+            interp=self.phase_interp,
+        )
+
+        self.dims = int(self.controller.total_params)
+        self.lb = -1.0 * np.ones(self.dims)
+        self.ub = 1.0 * np.ones(self.dims)
+
+        self.env = None
+        self._device_id = 0
+        self.obs_current = None
+        self.recover_count = 0
+
+    def init_env(self, device_id: int = 0) -> None:
+        self._device_id = int(device_id)
+        if self.env is not None:
+            self.env.close()
+        self.env = CustomEnv(
+            device_id=int(device_id),
+            obs_fail_bound=float(self.obs_fail_bound),
+            obs_clip_bound=float(self.obs_clip_bound),
+        )
+        self._hard_reset_and_stabilize()
+
+    def _hard_reset_and_stabilize(self) -> None:
+        obs, _ = self.env.reset()
+        obs = np.asarray(obs, dtype=np.float32)
+        action = np.zeros(N_ACT, dtype=np.float32)
+
+        for _ in range(int(self.startup_steps)):
+            obs, _, done, trunc, _ = self.env.step(action)
+            if done or trunc:
+                obs, _ = self.env.reset()
+
+        self.obs_current = np.asarray(obs, dtype=np.float32)
+        self.controller.reset_state()
+
+    @staticmethod
+    def _tail_mean(rewards: List[float], tail_steps: int) -> float:
+        rr = np.asarray(rewards, dtype=np.float64)
+        if rr.size == 0:
+            return 0.0
+        tail = rr[-tail_steps:] if rr.size >= tail_steps else rr
+        return float(np.mean(tail))
+
+    def evaluate_candidate(self, x: np.ndarray) -> Dict[str, object]:
+        x = self._preprocess(x)
+        self.controller.set_params(x)
+
+        if self.env is None:
+            self.init_env(self._device_id)
+
+        if self.reset_each_candidate:
+            self._hard_reset_and_stabilize()
+
+        for attempt in range(int(self.max_recover_resets) + 1):
+            obs = np.asarray(self.obs_current, dtype=np.float32)
+            self.controller.reset_state()
+
+            rewards: List[float] = []
+            steps = 0
+            done = False
+            trunc = False
+            last_info: Dict[str, object] = {}
+
+            for _ in range(int(self.eval_steps)):
+                action = self.controller.predict(obs)
+                obs, reward, done, trunc, step_info = self.env.step(action)
+                if isinstance(step_info, dict):
+                    last_info = step_info
+                rewards.append(float(reward))
+                steps += 1
+                if done or trunc:
+                    break
+
+            if done or trunc and attempt < int(self.max_recover_resets):
+                self.recover_count += 1
+                self._hard_reset_and_stabilize()
+                continue
+
+            self.obs_current = np.asarray(obs, dtype=np.float32)
+            y = self._tail_mean(rewards, tail_steps=int(self.tail_steps))
+            return {
+                "reward": float(y),
+                "scaled": float(y * 100.0),
+                "steps": int(steps),
+                "done": bool(done),
+                "truncated": bool(trunc),
+                "recoveries_used": int(attempt),
+                "failure_code": int(last_info.get("failure_code", 0)),
+                "period_steps": float(self.controller.current_period_steps),
+            }
+
+        return {
+            "reward": 0.0,
+            "scaled": 0.0,
+            "steps": 0,
+            "done": True,
+            "truncated": True,
+            "recoveries_used": int(self.max_recover_resets),
+            "failure_code": 1,
+            "period_steps": float(self.controller.current_period_steps),
+        }
+
+    def scaled(self, y: float) -> float:
+        return float(y * 100.0)
+
+    def __call__(self, x: np.ndarray, apply_scaling: bool = False, track: bool = True) -> float:
+        info = self.evaluate_candidate(x)
+        y = float(info["reward"])
+        return self.scaled(y) if apply_scaling else y
+
+
+def parse_args() -> argparse.Namespace:
+    p = argparse.ArgumentParser(description="DANTE v7 open-loop periodic controller")
+    p.add_argument("--name", type=str, default=V7_CONFIG["name"], help="Optional run name override")
+    p.add_argument(
+        "--control-points",
+        type=int,
+        default=V7_CONFIG["control_points_per_channel"],
+        help="Control points per channel for one cycle",
+    )
+    p.add_argument(
+        "--period-mode",
+        type=str,
+        default=V7_CONFIG["period_mode"],
+        choices=["auto", "fixed", "optimize"],
+        help="Cycle period mode",
+    )
+    p.add_argument("--fixed-period", type=float, default=V7_CONFIG["fixed_period"], help="Fixed period in steps")
+    p.add_argument("--period-min", type=float, default=V7_CONFIG["period_min"], help="Min period for clipping")
+    p.add_argument("--period-max", type=float, default=V7_CONFIG["period_max"], help="Max period for clipping")
+    p.add_argument(
+        "--phase-interp",
+        type=str,
+        default=V7_CONFIG["phase_interp"],
+        choices=["linear"],
+        help="Interpolation mode for phase to control point",
+    )
+    return p.parse_args()
+
+
+def sample_params(dims: int, turn: float, period_mode: str, period_guess: float, pmin: float, pmax: float) -> np.ndarray:
+    x = np.random.uniform(-1.0, 1.0, size=dims)
+    x = np.round(x / turn) * turn
+    x = np.clip(x, -1.0, 1.0)
+
+    if str(period_mode).lower() == "optimize":
+        x[-1] = map_range_to_unit(period_guess, pmin, pmax)
+    return x
+
+
+def save_live_db(path: str, x: np.ndarray, y: np.ndarray, meta: Dict[str, object]) -> None:
+    np.savez(path, input_x=x, input_y=y, meta_json=np.array([json.dumps(meta, ensure_ascii=False)]))
+
+
+def print_progress_line(
+    phase: str,
+    idx: int,
+    total: int,
+    reward: float,
+    best_reward: float,
+    recover_total: int,
+    elapsed_sec: float,
+    global_step: int,
+    total_expected: int,
+    period_steps: float,
+) -> None:
+    print(
+        f"[{phase}] {idx}/{total} | reward={reward:.4f} | best={best_reward:.4f} | "
+        f"period={period_steps:.3f} | recover={recover_total} | eval={global_step}/{total_expected} | elapsed={elapsed_sec:.1f}s",
+        flush=True,
+    )
+
+
+def main() -> None:
+    args = parse_args()
+
+    cfg = dict(V7_CONFIG)
+    cfg["name"] = str(args.name)
+    cfg["control_points_per_channel"] = int(args.control_points)
+    cfg["period_mode"] = str(args.period_mode)
+    cfg["fixed_period"] = float(args.fixed_period)
+    cfg["period_min"] = float(args.period_min)
+    cfg["period_max"] = float(args.period_max)
+    cfg["phase_interp"] = str(args.phase_interp)
+
+    period_info = estimate_period_from_npz_list(
+        rel_paths=list(cfg["period_estimate_files"]),
+        key_hint=str(cfg["period_estimate_key"]),
+        min_period=float(cfg["period_min"]),
+        max_period=float(cfg["period_max"]),
+    )
+
+    if str(cfg["period_mode"]).lower() == "fixed":
+        period_steps = float(np.clip(cfg["fixed_period"], cfg["period_min"], cfg["period_max"]))
+        period_source = "fixed"
+    else:
+        p_est = period_info.get("period", None)
+        if p_est is None:
+            period_steps = float(np.clip(cfg["fixed_period"], cfg["period_min"], cfg["period_max"]))
+            period_source = "fallback_fixed_no_estimate"
+        else:
+            period_steps = float(np.clip(float(p_est), cfg["period_min"], cfg["period_max"]))
+            period_source = "auto_from_ppo_fft"
+
+    target_evals = int(cfg["target_cfd_steps"] // cfg["eval_steps"])
+
+    obj = FlowControlObjectiveV7(
+        control_points_per_channel=int(cfg["control_points_per_channel"]),
+        period_mode=str(cfg["period_mode"]),
+        period_steps=float(period_steps),
+        period_min=float(cfg["period_min"]),
+        period_max=float(cfg["period_max"]),
+        phase_interp=str(cfg["phase_interp"]),
+        eval_steps=int(cfg["eval_steps"]),
+        tail_steps=int(cfg["tail_steps"]),
+        startup_steps=int(cfg["startup_steps"]),
+        max_recover_resets=int(cfg["max_recover_resets"]),
+        reset_each_candidate=bool(cfg["reset_each_candidate"]),
+        obs_fail_bound=float(cfg["obs_fail_bound"]),
+        obs_clip_bound=float(cfg["obs_clip_bound"]),
+    )
+    obj.init_env(device_id=int(cfg["device_id"]))
+
+    dims = int(obj.dims)
+    num_initial_raw = int(max(1, round(float(cfg["num_initial_per_dim"]) * dims)))
+    num_initial = int(min(int(cfg["max_num_initial"]), max(int(cfg["min_num_initial"]), num_initial_raw)))
+    num_acquisitions = int((target_evals - int(num_initial)) // int(cfg["samples_per_acq"]))
+    if num_acquisitions <= 0:
+        raise RuntimeError(
+            f"computed num_acquisitions <= 0 with target_evals={target_evals}, "
+            f"num_initial={num_initial}, samples_per_acq={int(cfg['samples_per_acq'])}"
+        )
+
+    max_init_attempts = int(max(num_initial, round(float(cfg["max_init_attempts_factor"]) * num_initial)))
+    total_expected = int(num_initial + num_acquisitions * int(cfg["samples_per_acq"]))
+
+    name = str(cfg["name"])
+    model_dir = os.path.join(ROOT, "models", "250421")
+    out_dir = os.path.join(ROOT, "output")
+    tb_dir = os.path.join(ROOT, "tensorboard", name)
+    os.makedirs(model_dir, exist_ok=True)
+    os.makedirs(out_dir, exist_ok=True)
+
+    config_payload = {
+        "name": name,
+        "control_mode": "open_loop_periodic",
+        "device_id": int(cfg["device_id"]),
+        "surrogate_gpu_id": int(cfg["surrogate_gpu_id"]),
+        "control_points_per_channel": int(cfg["control_points_per_channel"]),
+        "controller_dims": int(dims),
+        "period_mode": str(cfg["period_mode"]),
+        "period_steps": float(period_steps),
+        "period_source": period_source,
+        "period_min": float(cfg["period_min"]),
+        "period_max": float(cfg["period_max"]),
+        "period_estimate": period_info,
+        "phase_interp": str(cfg["phase_interp"]),
+        "num_initial": int(num_initial),
+        "num_initial_raw": int(num_initial_raw),
+        "num_initial_per_dim": float(cfg["num_initial_per_dim"]),
+        "min_num_initial": int(cfg["min_num_initial"]),
+        "max_num_initial": int(cfg["max_num_initial"]),
+        "num_acquisitions": int(num_acquisitions),
+        "samples_per_acq": int(cfg["samples_per_acq"]),
+        "surrogate_mode": str(cfg["surrogate_mode"]),
+        "eval_steps": int(cfg["eval_steps"]),
+        "tail_steps": int(cfg["tail_steps"]),
+        "startup_steps": int(cfg["startup_steps"]),
+        "max_recover_resets": int(cfg["max_recover_resets"]),
+        "obs_fail_bound": float(cfg["obs_fail_bound"]),
+        "obs_clip_bound": float(cfg["obs_clip_bound"]),
+        "reset_each_candidate": bool(cfg["reset_each_candidate"]),
+        "max_init_attempts": int(max_init_attempts),
+        "max_init_attempts_factor": float(cfg["max_init_attempts_factor"]),
+        "target_cfd_steps": int(cfg["target_cfd_steps"]),
+        "target_total_evals": int(target_evals),
+        "matched_total_evals": int(total_expected),
+        "matched_cfd_steps": int(total_expected * int(cfg["eval_steps"])),
+    }
+
+    with open(os.path.join(out_dir, f"{name}_structure_decision.json"), "w", encoding="utf-8") as f:
+        json.dump(config_payload, f, indent=2, ensure_ascii=False)
+
+    print("control_mode:", "open_loop_periodic")
+    print("device_id:", int(cfg["device_id"]))
+    print("surrogate_gpu_id:", int(cfg["surrogate_gpu_id"]))
+    print("control_points_per_channel:", int(cfg["control_points_per_channel"]))
+    print("controller_dims:", int(dims))
+    print("period_mode:", str(cfg["period_mode"]))
+    print("period_steps:", float(period_steps))
+    print("period_source:", period_source)
+    print("num_initial:", int(num_initial))
+    print("num_initial_raw:", int(num_initial_raw))
+    print("num_acquisitions:", int(num_acquisitions))
+    print("samples_per_acq:", int(cfg["samples_per_acq"]))
+    print("target_cfd_steps:", int(cfg["target_cfd_steps"]))
+    print("matched_cfd_steps:", int(total_expected * int(cfg["eval_steps"])))
+
+    ckpt_path = Path(os.path.join(model_dir, f"{name}_surrogate.keras"))
+    surrogate = FlowControlSurrogateV6(
+        input_dims=dims,
+        epochs=int(cfg["surrogate_epochs"]),
+        patience=30,
+        check_point_path=ckpt_path,
+        tf_device_id=int(cfg["surrogate_gpu_id"]),
+    )
+
+    live_db_path = os.path.join(out_dir, f"{name}_database_live.npz")
+    best_params_path = os.path.join(model_dir, f"{name}_best.npy")
+    best_meta_path = os.path.join(out_dir, f"{name}_best_meta.pkl")
+    final_meta_path = os.path.join(out_dir, f"{name}_final_meta.pkl")
+    dante_log_path = os.path.join(out_dir, f"{name}_dante_log.csv")
+
+    writer = NullWriter() if SummaryWriter is None else SummaryWriter(log_dir=tb_dir)
+
+    with open(dante_log_path, "w", encoding="utf-8") as f:
+        f.write("timestamp,phase,acq,candidate,reward,best_reward,dataset_size,recoveries_used,failure_code,period_steps\n")
+
+    input_x = np.empty((0, dims), dtype=np.float64)
+    input_y = np.empty((0,), dtype=np.float64)
+    history: List[Dict[str, object]] = []
+    best_reward = -1.0
+    best_params = np.zeros(dims, dtype=np.float64)
+    invalid_skips = 0
+
+    t0 = time.time()
+    global_step = 0
+
+    try:
+        valid_init = 0
+        init_attempts = 0
+        while valid_init < num_initial:
+            if init_attempts >= max_init_attempts:
+                raise RuntimeError(
+                    f"init failed to collect enough valid samples: valid={valid_init}/{num_initial}, "
+                    f"attempts={init_attempts}/{max_init_attempts}, invalid_skips={invalid_skips}"
+                )
+
+            init_attempts += 1
+            x = sample_params(
+                dims=dims,
+                turn=obj.turn,
+                period_mode=str(cfg["period_mode"]),
+                period_guess=float(period_steps),
+                pmin=float(cfg["period_min"]),
+                pmax=float(cfg["period_max"]),
+            )
+
+            info = obj.evaluate_candidate(x)
+            reward = float(info["reward"])
+            is_valid = int(info.get("failure_code", 0)) == 0
+
+            if is_valid:
+                valid_init += 1
+                input_x = np.vstack((input_x, x.reshape(1, -1)))
+                input_y = np.append(input_y, float(info["scaled"]))
+                writer.add_scalar("Reward", reward, global_step)
+            else:
+                invalid_skips += 1
+
+            if is_valid and reward > best_reward:
+                best_reward = reward
+                best_params = x.copy()
+                np.save(best_params_path, best_params)
+                with open(best_meta_path, "wb") as f:
+                    pickle.dump(
+                        {
+                            "best_reward": best_reward,
+                            "best_params": best_params,
+                            "config": config_payload,
+                            "timestamp": time.time(),
+                        },
+                        f,
+                    )
+
+            if is_valid:
+                save_live_db(
+                    live_db_path,
+                    input_x,
+                    input_y,
+                    {
+                        "name": name,
+                        "best_reward": best_reward,
+                        "dataset_size": int(len(input_y)),
+                        "control_mode": "open_loop_periodic",
+                        "recover_count": int(obj.recover_count),
+                        "invalid_skips": int(invalid_skips),
+                    },
+                )
+
+            with open(dante_log_path, "a", encoding="utf-8") as f:
+                f.write(
+                    f"{time.time():.3f},init,0,{init_attempts},{reward:.8f},{best_reward:.8f},{len(input_y)},{info['recoveries_used']},{info.get('failure_code', 0)},{float(info.get('period_steps', period_steps)):.6f}\n"
+                )
+
+            global_step += 1
+            print(
+                f"[init-attempt {init_attempts}/{max_init_attempts}] valid={valid_init}/{num_initial} | "
+                f"reward={reward:.4f} | best={best_reward:.4f} | period={float(info.get('period_steps', period_steps)):.3f} | "
+                f"invalid_skips={invalid_skips} | recover={int(obj.recover_count)} | "
+                f"eval={global_step}/{total_expected}+ | elapsed={float(time.time() - t0):.1f}s",
+                flush=True,
+            )
+
+        for acq in range(int(num_acquisitions)):
+            if len(input_y) < 2:
+                print(f"[acq {acq + 1}] skipped: insufficient valid samples ({len(input_y)})", flush=True)
+                continue
+
+            print(f"[acq {acq + 1}/{int(num_acquisitions)}] fitting surrogate on {len(input_y)} samples...", flush=True)
+
+            surrogate_mode = str(cfg.get("surrogate_mode", "mlp")).lower()
+            if surrogate_mode == "ensemble":
+                candidates = []
+                for arch in ["mlp", "cnn"]:
+                    cand_ckpt = Path(str(ckpt_path).replace(".keras", f"_{arch}.keras"))
+                    surr = FlowControlSurrogateV6(
+                        input_dims=dims,
+                        epochs=int(cfg["surrogate_epochs"]),
+                        patience=30,
+                        check_point_path=cand_ckpt,
+                        tf_device_id=int(cfg["surrogate_gpu_id"]),
+                        architecture=arch,
+                    )
+                    try:
+                        m = surr(input_x, input_y, verbose=0)
+                        fm = dict(getattr(surr, "last_fit_metrics", {}) or {})
+                        candidates.append((arch, m, fm, cand_ckpt))
+                    except Exception as e:
+                        print(f"[acq {acq + 1}] surrogate {arch} failed: {e}", flush=True)
+
+                if not candidates:
+                    raise RuntimeError("all surrogate candidates failed in ensemble mode")
+
+                candidates.sort(key=lambda z: float(z[2].get("val_r2", -1e9)), reverse=True)
+                best_arch, model, fit_metrics, best_ckpt = candidates[0]
+                if best_ckpt.exists():
+                    shutil.copy2(best_ckpt, ckpt_path)
+                fit_metrics["selected_architecture"] = best_arch
+            else:
+                surrogate.architecture = "cnn" if surrogate_mode == "cnn" else "mlp"
+                model = surrogate(input_x, input_y, verbose=0)
+                fit_metrics = dict(getattr(surrogate, "last_fit_metrics", {}) or {})
+                fit_metrics["selected_architecture"] = str(surrogate.architecture)
+
+            if fit_metrics:
+                writer.add_scalar("Surrogate/val_r2", float(fit_metrics.get("val_r2", 0.0)), acq)
+                writer.add_scalar("Surrogate/val_mae", float(fit_metrics.get("val_mae", 0.0)), acq)
+                print(
+                    f"[acq {acq + 1}] surrogate metrics: "
+                    f"val_r2={fit_metrics.get('val_r2', float('nan')):.4f}, "
+                    f"val_mae={fit_metrics.get('val_mae', float('nan')):.4f}, "
+                    f"selected={fit_metrics.get('selected_architecture', 'na')}, "
+                    f"device={fit_metrics.get('device', 'CPU')}",
+                    flush=True,
+                )
+
+            if ckpt_path.exists():
+                shutil.copy2(ckpt_path, os.path.join(model_dir, f"{name}_surrogate_live.keras"))
+
+            explorer = TreeExploration(
+                func=obj,
+                model=model,
+                num_samples_per_acquisition=int(cfg["samples_per_acq"]),
+            )
+            candidate_x = explorer.rollout(input_x, input_y, iteration=acq)
+
+            acq_rewards: List[float] = []
+            acq_periods: List[float] = []
+            for j, x in enumerate(candidate_x):
+                info = obj.evaluate_candidate(x)
+                reward = float(info["reward"])
+                period_used = float(info.get("period_steps", period_steps))
+                is_valid = int(info.get("failure_code", 0)) == 0
+
+                if is_valid:
+                    acq_rewards.append(reward)
+                    acq_periods.append(period_used)
+
+                    input_x = np.vstack((input_x, np.asarray(x, dtype=np.float64).reshape(1, -1)))
+                    input_y = np.append(input_y, float(info["scaled"]))
+                    writer.add_scalar("Reward", reward, global_step)
+
+                    if str(cfg["period_mode"]).lower() == "optimize":
+                        writer.add_scalar("Controller/period_steps", period_used, global_step)
+
+                    if reward > best_reward:
+                        best_reward = reward
+                        best_params = np.asarray(x, dtype=np.float64).copy()
+                        np.save(best_params_path, best_params)
+                        with open(best_meta_path, "wb") as f:
+                            pickle.dump(
+                                {
+                                    "best_reward": best_reward,
+                                    "best_params": best_params,
+                                    "config": config_payload,
+                                    "timestamp": time.time(),
+                                },
+                                f,
+                            )
+
+                    save_live_db(
+                        live_db_path,
+                        input_x,
+                        input_y,
+                        {
+                            "name": name,
+                            "best_reward": best_reward,
+                            "dataset_size": int(len(input_y)),
+                            "control_mode": "open_loop_periodic",
+                            "recover_count": int(obj.recover_count),
+                            "acq": int(acq + 1),
+                            "invalid_skips": int(invalid_skips),
+                        },
+                    )
+                else:
+                    invalid_skips += 1
+
+                with open(dante_log_path, "a", encoding="utf-8") as f:
+                    f.write(
+                        f"{time.time():.3f},acq,{acq + 1},{j + 1},{reward:.8f},{best_reward:.8f},{len(input_y)},{info['recoveries_used']},{info.get('failure_code', 0)},{period_used:.6f}\n"
+                    )
+
+                global_step += 1
+                print_progress_line(
+                    phase=f"acq{acq + 1}",
+                    idx=j + 1,
+                    total=len(candidate_x),
+                    reward=reward,
+                    best_reward=best_reward,
+                    recover_total=int(obj.recover_count),
+                    elapsed_sec=float(time.time() - t0),
+                    global_step=global_step,
+                    total_expected=total_expected,
+                    period_steps=period_used,
+                )
+
+            history.append(
+                {
+                    "iteration": int(acq + 1),
+                    "new_mean": float(np.mean(acq_rewards) if acq_rewards else 0.0),
+                    "new_max": float(np.max(acq_rewards) if acq_rewards else 0.0),
+                    "period_mean": float(np.mean(acq_periods) if acq_periods else period_steps),
+                    "period_std": float(np.std(acq_periods) if acq_periods else 0.0),
+                    "best_reward": float(best_reward),
+                    "dataset_size": int(len(input_y)),
+                    "recover_total": int(obj.recover_count),
+                }
+            )
+
+            print(
+                f"acq {acq + 1}/{num_acquisitions}: mean={history[-1]['new_mean']:.4f}, "
+                f"max={history[-1]['new_max']:.4f}, best={best_reward:.4f}, "
+                f"period_mean={history[-1]['period_mean']:.3f}, recover_total={obj.recover_count}",
+                flush=True,
+            )
+
+        with open(final_meta_path, "wb") as f:
+            pickle.dump(
+                {
+                    "name": name,
+                    "best_reward": best_reward,
+                    "best_params": best_params,
+                    "history": history,
+                    "elapsed_sec": float(time.time() - t0),
+                    "config": config_payload,
+                    "recover_total": int(obj.recover_count),
+                },
+                f,
+            )
+
+        print("Training done")
+        print("best_reward:", f"{best_reward:.4f}")
+        print("recover_total:", obj.recover_count)
+        print("invalid_skips:", invalid_skips)
+
+    finally:
+        writer.close()
+        if obj.env is not None:
+            obj.env.close()
+
+
+if __name__ == "__main__":
+    main()

archive/dante_pinball/dante_pinball/legacy/dante_v6_initial_surrogate_analysis.md

@@ -0,0 +1,51 @@
+# DANTE v6 Initial-Region Surrogate Failure Analysis
+
+## Scope
+
+- initial_samples: 100
+- dims: 42
+- note: analysis uses only init phase, not acquisition samples
+
+## Data Geometry
+
+- rank_ratio: 1.000
+- unique_ratio_rounded_0p05: 1.000
+- cov_condition_number: 1.53e+01
+- pca_components_for_90pct_var: 30
+- avg_nn_dist: 4.1265
+
+## Classical Baselines
+
+- ridge_std: r2_mean=-1.0772 ± 0.4586, mae_mean=6.0836
+- knn_std_k5: r2_mean=-0.2933 ± 0.2589, mae_mean=4.9774
+- rf_300: r2_mean=-0.2074 ± 0.2602, mae_mean=4.6365
+
+## TensorFlow Models
+
+- tf_device: GPU:1
+- tf_v4_like_no_scaling: r2_mean=-1.8222 ± 0.8408, mae_mean=7.1709
+- tf_v4_like_with_scaling: r2_mean=-0.7289 ± 0.2800, mae_mean=5.9893
+- tf_mid_128_64_32_with_scaling: r2_mean=-0.6206 ± 0.4865, mae_mean=5.6784
+
+## Recovery/Noise Signal
+
+- recoveries_ratio_ge1: 0.880
+- mean_scaled(recover>=1): 17.945237696501337
+- mean_scaled(recover=0): 15.966237587414065
+- std_scaled(recover>=1): 4.7475266358578665
+- std_scaled(recover=0): 9.213494585712375
+
+## Temporal Drift
+
+- corr(index, y): -0.1209
+- forward RF on x: r2=-0.0394, mae=5.0576
+- forward RF on [x,index]: r2=0.0153, mae=4.9602
+- forward ridge on index only: r2=0.0023, mae=4.9557
+
+## Diagnosis
+
+- Even non-neural baselines fail on init set: weakly learnable mapping or high label noise.
+- Input/output scaling is a first-order factor: original no-scaling setup underfits init region.
+- Model capacity/optimization also matters after scaling (mid_128_64_32 > v4-like).
+- Most init samples require recovery reset; this indicates environment-transition induced label noise in init pool.
+- Adding sample index improves forward prediction, indicating temporal/state drift beyond static x->y mapping.

archive/dante_pinball/dante_pinball/legacy/dante_v6_ppo_diag.md

@@ -0,0 +1,28 @@
+# DANTE v6 vs PPO 诊断报告
+
+## 1) PPO新terms重拟合与可达性
+
+- features: ['bias1', 'obs0', 'obs1', 'dobs0', 'dobs1', 'sin_obs0', 'sin_obs1', 'cos_obs0', 'cos_obs1', 'tanh_obs0', 'tanh_obs1', 'act0_l1', 'act1_l1', 'act2_l1']
+- ch0: R2_test=1.0000, MAE_test=0.00002, nz=14
+- ch1: R2_test=1.0000, MAE_test=0.00001, nz=14
+- ch2: R2_test=1.0000, MAE_test=0.00002, nz=14
+- 参数空间可达性: out_of_range_terms=0, coef_abs_err_mean=0.000000, coef_abs_err_max=0.000000
+
+## 2) PPO拟合控制率环境回放
+
+- rollout steps=300, recoveries=0, tail60=0.5041, max_reward=0.7223
+- reward曲线图: dante_v6_ppo_reward_curve.png
+- 流场速度图: dante_v6_ppo_flow_speed.png
+
+## 3) DANTE数据库与PPO目标点
+
+- samples=818, num_initial=100, best_reward=0.3311
+- PCA距离: init_mean=0.6812, last_mean=5.3179, min=0.0080 at eval=196
+- PCA图: dante_v6_pca_overlay.png
+- 距离趋势图: dante_v6_distance_to_ppo.png
+- best曲线图: dante_v6_best_curve.png
+
+## 4) 结论
+
+- 是否趋近PPO点: False
+- 最高reward不更新判断: DANTE未明显趋近PPO目标点，代理采样方向与目标结构存在偏移，需修正采集策略或特征归一化。

archive/dante_pinball/dante_pinball/legacy/dante_v6_surrogate_study.md

@@ -0,0 +1,23 @@
+# DANTE v6 Surrogate Study
+
+- db_path: output/d1a3o12_250421_forces02_dante_v6_database_live.npz
+- n_samples: 976
+- dims: 42
+- holdout: 0.2
+- gpu_id: 1
+
+## Ranking (by test_r2)
+
+| rank | design | test_r2 | test_mae | val_r2 | epochs_ran | device |
+|---:|---|---:|---:|---:|---:|---|
+| 1 | mid_128_64_32 | 0.8647 | 1.2556 | 0.8778 | 88 | GPU:1 |
+| 2 | compact_128_64 | 0.8610 | 1.2621 | 0.8836 | 84 | GPU:1 |
+| 3 | wide_256_128_64 | 0.8528 | 1.2508 | 0.8786 | 68 | GPU:1 |
+| 4 | strong_reg_128_64_32 | 0.8463 | 1.3380 | 0.8592 | 138 | GPU:1 |
+
+## Recommended
+
+- design: mid_128_64_32
+- test_r2: 0.8647
+- test_mae: 1.2556
+- config: {"name": "mid_128_64_32", "hidden_units": [128, 64, 32], "dropout": 0.1, "weight_decay": 1e-06, "learning_rate": 0.001, "batch_size": 64}

archive/dante_pinball/dante_pinball/legacy/dante_v6_surrogate_torch.py

@@ -0,0 +1,253 @@
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, Optional, Sequence
+
+import numpy as np
+from sklearn.metrics import mean_absolute_error, r2_score
+from sklearn.model_selection import train_test_split
+from sklearn.preprocessing import StandardScaler
+
+try:
+    import torch
+    import torch.nn as nn
+    import torch.optim as optim
+    _TORCH_IMPORT_ERROR = None
+except Exception as exc:
+    torch = None
+    nn = None
+    optim = None
+    _TORCH_IMPORT_ERROR = exc
+
+
+class TorchScaledPredictWrapper:
+    def __init__(self, torch_model: Any, x_scaler: StandardScaler, y_scaler: StandardScaler, device: str):
+        self.torch_model = torch_model
+        self.x_scaler = x_scaler
+        self.y_scaler = y_scaler
+        self.device = str(device)
+
+    def predict(self, x_in, **kwargs):
+        x_in = np.asarray(x_in, dtype=np.float64)
+        if x_in.ndim == 3 and x_in.shape[-1] == 1:
+            x_in = x_in.squeeze(axis=-1)
+        if x_in.ndim > 2:
+            x_in = x_in.reshape(len(x_in), -1)
+        x_scaled = self.x_scaler.transform(x_in).astype(np.float32)
+        xt = torch.as_tensor(x_scaled, dtype=torch.float32, device=self.device)
+        if xt.ndim == 2:
+            pass
+        else:
+            xt = xt.reshape(len(xt), -1)
+
+        self.torch_model.eval()
+        with torch.no_grad():
+            if hasattr(self.torch_model, "expects_channel") and self.torch_model.expects_channel:
+                # Conv1d on this runtime can hit intermittent cuDNN mapping errors;
+                # keep GPU execution but bypass cuDNN for CNN forward passes.
+                with torch.backends.cudnn.flags(enabled=False):
+                    y_scaled = self.torch_model(xt.unsqueeze(1)).detach().cpu().numpy().reshape(-1, 1)
+            else:
+                y_scaled = self.torch_model(xt).detach().cpu().numpy().reshape(-1, 1)
+
+        y_raw = self.y_scaler.inverse_transform(y_scaled)
+        return y_raw.reshape(-1, 1)
+
+
+class TorchMLPRegressor(nn.Module):
+    expects_channel = False
+
+    def __init__(self, input_dims: int, hidden_units: Sequence[int], dropout: float):
+        super().__init__()
+        layers = []
+        prev = int(input_dims)
+        for w in hidden_units:
+            layers.append(nn.Linear(prev, int(w)))
+            layers.append(nn.ELU())
+            if dropout > 1e-8:
+                layers.append(nn.Dropout(float(dropout)))
+            prev = int(w)
+        layers.append(nn.Linear(prev, 1))
+        self.net = nn.Sequential(*layers)
+
+    def forward(self, x):
+        return self.net(x)
+
+
+class TorchCNNRegressor(nn.Module):
+    expects_channel = True
+
+    def __init__(self, input_dims: int, dropout: float):
+        super().__init__()
+        flat_dim = 16 * max(1, int(input_dims) - 2)
+        self.net = nn.Sequential(
+            nn.Conv1d(1, 128, kernel_size=3, padding=1),
+            nn.ELU(),
+            nn.MaxPool1d(kernel_size=2, stride=1),
+            nn.Dropout(float(dropout)),
+            nn.Conv1d(128, 64, kernel_size=3, padding=1),
+            nn.ELU(),
+            nn.MaxPool1d(kernel_size=2, stride=1),
+            nn.Dropout(float(dropout)),
+            nn.Conv1d(64, 32, kernel_size=3, padding=1),
+            nn.ELU(),
+            nn.Conv1d(32, 16, kernel_size=3, padding=1),
+            nn.ELU(),
+            nn.Flatten(),
+            nn.Linear(flat_dim, 64),
+            nn.ELU(),
+            nn.Linear(64, 1),
+        )
+
+    def forward(self, x):
+        return self.net(x)
+
+
+@dataclass
+class FlowControlSurrogateV6:
+    input_dims: int
+    learning_rate: float = 1e-3
+    batch_size: int = 64
+    epochs: int = 500
+    test_size: float = 0.2
+    train_test_split_random_state: int = 42
+    patience: int = 30
+    check_point_path: Path = Path("surrogate_v6.pt")
+    hidden_units: Sequence[int] = field(default_factory=lambda: (128, 64, 32))
+    architecture: str = "mlp"
+    dropout: float = 0.10
+    weight_decay: float = 1e-6
+    tf_device_id: Optional[int] = None
+    require_gpu: bool = True
+
+    def __post_init__(self):
+        self.model: Optional[Any] = None
+        self.x_scaler = StandardScaler()
+        self.y_scaler = StandardScaler()
+        self.last_fit_metrics: Dict[str, float] = {}
+
+    @staticmethod
+    def _forward_with_runtime_guard(model: Any, x: Any):
+        if hasattr(model, "expects_channel") and model.expects_channel:
+            with torch.backends.cudnn.flags(enabled=False):
+                return model(x.unsqueeze(1))
+        return model(x)
+
+    @staticmethod
+    def _ensure_torch_ready() -> None:
+        if torch is None:
+            raise ImportError(
+                f"PyTorch is required for FlowControlSurrogateV6 but is not available: {_TORCH_IMPORT_ERROR}"
+            )
+
+    def _pick_device(self) -> str:
+        self._ensure_torch_ready()
+        if not torch.cuda.is_available():
+            if self.require_gpu:
+                raise RuntimeError("FlowControlSurrogateV6 requires GPU but torch.cuda is not available")
+            return "cpu"
+
+        if self.tf_device_id is None:
+            return "cuda:0"
+        idx = int(max(0, min(torch.cuda.device_count() - 1, int(self.tf_device_id))))
+        return f"cuda:{idx}"
+
+    def _build_model(self):
+        arch = str(self.architecture).lower()
+        if arch == "cnn":
+            return TorchCNNRegressor(input_dims=self.input_dims, dropout=float(self.dropout))
+        return TorchMLPRegressor(
+            input_dims=self.input_dims,
+            hidden_units=self.hidden_units,
+            dropout=float(self.dropout),
+        )
+
+    def __call__(self, x, y, verbose: int = 0):
+        self._ensure_torch_ready()
+        x = np.asarray(x, dtype=np.float64)
+        y = np.asarray(y, dtype=np.float64).reshape(-1)
+
+        x_train, x_val, y_train, y_val = train_test_split(
+            x,
+            y,
+            test_size=self.test_size,
+            random_state=self.train_test_split_random_state,
+            shuffle=True,
+        )
+
+        x_train_s = self.x_scaler.fit_transform(x_train).astype(np.float32)
+        x_val_s = self.x_scaler.transform(x_val).astype(np.float32)
+        y_train_s = self.y_scaler.fit_transform(y_train.reshape(-1, 1)).reshape(-1).astype(np.float32)
+
+        device = self._pick_device()
+        model = self._build_model().to(device)
+        optimizer = optim.Adam(model.parameters(), lr=float(self.learning_rate), weight_decay=float(self.weight_decay))
+        criterion = nn.MSELoss()
+
+        xt = torch.as_tensor(x_train_s, dtype=torch.float32, device=device)
+        yt = torch.as_tensor(y_train_s, dtype=torch.float32, device=device).reshape(-1, 1)
+
+        xv = torch.as_tensor(x_val_s, dtype=torch.float32, device=device)
+
+        batch = int(max(8, min(int(self.batch_size), len(x_train_s))))
+        best_loss = np.inf
+        best_state = None
+        bad_epochs = 0
+        epochs_ran = 0
+
+        model.train()
+        for ep in range(int(self.epochs)):
+            perm = torch.randperm(xt.shape[0], device=device)
+            epoch_loss = 0.0
+            n_batches = 0
+
+            for i in range(0, xt.shape[0], batch):
+                idx = perm[i : i + batch]
+                xb = xt[idx]
+                yb = yt[idx]
+                optimizer.zero_grad(set_to_none=True)
+                pred = self._forward_with_runtime_guard(model, xb)
+                loss = criterion(pred, yb)
+                loss.backward()
+                optimizer.step()
+                epoch_loss += float(loss.item())
+                n_batches += 1
+
+            train_loss = epoch_loss / max(1, n_batches)
+            epochs_ran = ep + 1
+
+            if train_loss + 1e-10 < best_loss:
+                best_loss = train_loss
+                best_state = {k: v.detach().cpu().clone() for k, v in model.state_dict().items()}
+                bad_epochs = 0
+            else:
+                bad_epochs += 1
+
+            if bad_epochs >= int(self.patience):
+                break
+
+        if best_state is not None:
+            model.load_state_dict(best_state)
+
+        model.eval()
+        with torch.no_grad():
+            y_val_pred_s = self._forward_with_runtime_guard(model, xv).detach().cpu().numpy().reshape(-1, 1)
+
+        y_val_pred = self.y_scaler.inverse_transform(y_val_pred_s).reshape(-1)
+
+        arch = str(self.architecture).lower()
+        gpu_idx = int(str(device).split(":")[1]) if str(device).startswith("cuda") else -1
+        self.last_fit_metrics = {
+            "val_r2": float(r2_score(y_val, y_val_pred)),
+            "val_mae": float(mean_absolute_error(y_val, y_val_pred)),
+            "val_count": int(len(y_val)),
+            "best_val_loss": float(best_loss),
+            "epochs_ran": int(epochs_ran),
+            "architecture": arch,
+            "device": f"GPU:{gpu_idx}" if gpu_idx >= 0 else "CPU",
+            "gpu_count": int(torch.cuda.device_count() if torch.cuda.is_available() else 0),
+            "selected_gpu": int(gpu_idx),
+        }
+
+        self.model = model
+        return TorchScaledPredictWrapper(model, self.x_scaler, self.y_scaler, device=device)

archive/dante_pinball/dante_pinball/legacy/fit_ppo_control_sindy.py

@@ -0,0 +1,289 @@
+import json
+import os
+import pickle
+from typing import Dict, List, Tuple
+
+import numpy as np
+import pysindy as ps
+
+
+CURRENT_DIR = os.path.dirname(os.path.abspath(__file__))
+ROOT = os.path.abspath(os.path.join(CURRENT_DIR, os.pardir))
+
+DATA_PATH = os.path.join(ROOT, "output", "d1a3o12_250421_forces02_sindy_dataset.pkl")
+OUT_DIR = os.path.join(ROOT, "output", "report_dante_v3_v4")
+OUT_JSON = os.path.join(OUT_DIR, "ppo_sindy_control_fit.json")
+
+WARMUP_STEPS = 0
+MAX_LAG = 1
+THRESHOLDS = [0.0, 0.005, 0.01, 0.015, 0.02, 0.03, 0.05]
+NZ_RATIO_THRESHOLD = 0.70
+
+
+def episode_metric(rewards: np.ndarray, warmup: int = 150) -> float:
+    r = np.asarray(rewards, dtype=np.float64).reshape(-1)
+    if r.size == 0:
+        return 0.0
+    eff = r[warmup:] if r.size > warmup else r[-1:]
+    return float(np.mean(eff[-100:])) if eff.size >= 100 else float(np.mean(eff))
+
+
+def load_episodes(path: str) -> Tuple[List[Dict], Dict]:
+    with open(path, "rb") as f:
+        data = pickle.load(f)
+
+    if isinstance(data, dict) and "episodes" in data:
+        return list(data["episodes"]), dict(data.get("meta", {}))
+    if isinstance(data, list):
+        return data, {}
+    raise RuntimeError(f"Unsupported dataset format: {type(data)}")
+
+
+def extract_episode_arrays(ep: Dict) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+    actions = np.asarray(ep.get("actions", []), dtype=np.float64)
+    observations = np.asarray(ep.get("observations", []), dtype=np.float64)
+    rewards = np.asarray(ep.get("rewards", []), dtype=np.float64)
+
+    if actions.ndim != 2:
+        actions = actions.reshape(actions.shape[0], -1)
+    actions = actions[:, :3]
+
+    if observations.ndim != 2:
+        observations = observations.reshape(observations.shape[0], -1)
+    observations = observations[:, :2]
+
+    n = min(actions.shape[0], observations.shape[0], rewards.shape[0])
+    return actions[:n], observations[:n], rewards[:n]
+
+
+def build_dataset(episodes: List[Dict], warmup: int = 150) -> Tuple[np.ndarray, np.ndarray, List[str], Dict]:
+    x_rows = []
+    y_rows = []
+
+    feat_names = [
+        "bias1",
+        "obs0",
+        "obs1",
+        "dobs0",
+        "dobs1",
+        "sin_obs0",
+        "sin_obs1",
+        "cos_obs0",
+        "cos_obs1",
+        "tanh_obs0",
+        "tanh_obs1",
+        "act0_l1",
+        "act1_l1",
+        "act2_l1",
+    ]
+
+    stats = {"episodes_used": 0, "samples_used": 0}
+
+    for ep in episodes:
+        actions, obs2, rewards = extract_episode_arrays(ep)
+        t_len = min(actions.shape[0], obs2.shape[0], rewards.shape[0])
+        if t_len <= (MAX_LAG + warmup + 1):
+            continue
+
+        for t in range(MAX_LAG, t_len):
+            if t < warmup:
+                continue
+
+            o = obs2[t]
+            o1 = obs2[t - 1]
+            a_prev = actions[t - 1]
+
+            x_rows.append(
+                [
+                    1.0,
+                    o[0],
+                    o[1],
+                    o[0] - o1[0],
+                    o[1] - o1[1],
+                    np.sin(np.pi * o[0]),
+                    np.sin(np.pi * o[1]),
+                    np.cos(np.pi * o[0]),
+                    np.cos(np.pi * o[1]),
+                    np.tanh(o[0]),
+                    np.tanh(o[1]),
+                    a_prev[0],
+                    a_prev[1],
+                    a_prev[2],
+                ]
+            )
+            y_rows.append(actions[t])
+
+        stats["episodes_used"] += 1
+
+    if len(x_rows) < 512:
+        raise RuntimeError(f"Too few samples for fitting: {len(x_rows)}")
+
+    x = np.asarray(x_rows, dtype=np.float64)
+    y = np.asarray(y_rows, dtype=np.float64)
+    stats["samples_used"] = int(x.shape[0])
+    return x, y, feat_names, stats
+
+
+def r2(y: np.ndarray, yp: np.ndarray) -> float:
+    ssr = float(np.sum((y - yp) ** 2))
+    sst = float(np.sum((y - np.mean(y)) ** 2) + 1e-12)
+    return float(1.0 - ssr / sst)
+
+
+def fit_channel_grid(x: np.ndarray, y: np.ndarray, thresholds: List[float]):
+    std = np.std(x, axis=0)
+    std = np.where(std < 1e-8, 1.0, std)
+    xs = x / std
+
+    rows = []
+    for th in thresholds:
+        opt = ps.STLSQ(threshold=th, alpha=1e-4, max_iter=25)
+        opt.fit(xs, y)
+        coef = np.asarray(opt.coef_, dtype=np.float64).reshape(-1) / std
+        yp = x @ coef
+        rows.append(
+            {
+                "threshold": float(th),
+                "nz": int(np.sum(np.abs(coef) > 1e-8)),
+                "r2": r2(y, yp),
+                "mae": float(np.mean(np.abs(y - yp))),
+                "coef": coef,
+            }
+        )
+
+    best = max(rows, key=lambda z: z["r2"])
+    return rows, best
+
+
+def top_terms(feat_names: List[str], coef: np.ndarray, topk: int = 10) -> List[Dict]:
+    idx = np.argsort(np.abs(coef))[::-1]
+    out = []
+    for i in idx:
+        c = float(coef[i])
+        if abs(c) < 1e-8:
+            continue
+        out.append({"term": feat_names[i], "coef": c, "abs_coef": float(abs(c))})
+        if len(out) >= topk:
+            break
+    return out
+
+
+def main() -> None:
+    os.makedirs(OUT_DIR, exist_ok=True)
+    episodes_all, meta = load_episodes(DATA_PATH)
+
+    ppo_eps = [ep for ep in episodes_all if str(ep.get("source", "unknown")) == "ppo_eval"]
+    if len(ppo_eps) < 10:
+        # Fallback only when ppo episodes are too few.
+        ppo_eps = episodes_all
+
+    metrics = []
+    for i, ep in enumerate(ppo_eps):
+        _, _, rewards = extract_episode_arrays(ep)
+        metrics.append((i, episode_metric(rewards, warmup=WARMUP_STEPS)))
+    metrics_sorted = sorted(metrics, key=lambda x: x[1], reverse=True)
+
+    x, y, feat_names, data_stats = build_dataset(ppo_eps, warmup=WARMUP_STEPS)
+
+    channel_models = []
+    votes = np.zeros(len(feat_names), dtype=np.int64)
+    coef_abs_sum = np.zeros(len(feat_names), dtype=np.float64)
+    nz_ratios = []
+
+    for ch in range(3):
+        rows, best = fit_channel_grid(x, y[:, ch], THRESHOLDS)
+        coef = best["coef"]
+        active = np.abs(coef) >= 0.01
+        votes += active.astype(np.int64)
+        coef_abs_sum += np.abs(coef)
+        nz_nonbias = int(np.sum(np.abs(coef[1:]) > 1e-8))
+        denom_nonbias = int(max(1, len(feat_names) - 1))
+        nz_ratio = float(nz_nonbias / denom_nonbias)
+        nz_ratios.append(nz_ratio)
+
+        channel_models.append(
+            {
+                "channel": ch,
+                "r2": float(best["r2"]),
+                "mae": float(best["mae"]),
+                "best_sparse": {
+                    "threshold": float(best["threshold"]),
+                    "nz": int(best["nz"]),
+                    "nz_nonbias": nz_nonbias,
+                    "nz_ratio": nz_ratio,
+                },
+                "top_terms": top_terms(feat_names, coef, topk=10),
+                "grid": [
+                    {
+                        "threshold": float(z["threshold"]),
+                        "nz": int(z["nz"]),
+                        "r2": float(z["r2"]),
+                        "mae": float(z["mae"]),
+                    }
+                    for z in rows
+                ],
+            }
+        )
+
+    score_idx = sorted(
+        range(len(feat_names)),
+        key=lambda k: (int(votes[k]), float(coef_abs_sum[k])),
+        reverse=True,
+    )
+    global_top = [feat_names[k] for k in score_idx if feat_names[k] != "bias1"]
+    over_complex_channels = [int(cm["channel"]) for cm in channel_models if cm["best_sparse"]["nz_ratio"] >= NZ_RATIO_THRESHOLD]
+    use_sindy_prior = len(over_complex_channels) == 0
+
+    if use_sindy_prior:
+        prior_reason = (
+            f"all channels nz_ratio < {NZ_RATIO_THRESHOLD:.2f}; sparse structure is sufficiently compressible"
+        )
+    else:
+        prior_reason = (
+            f"channels {over_complex_channels} have nz_ratio >= {NZ_RATIO_THRESHOLD:.2f}; sparse structure is too dense"
+        )
+
+    result = {
+        "data_path": DATA_PATH,
+        "dataset_meta": meta,
+        "warmup_steps": WARMUP_STEPS,
+        "max_lag": MAX_LAG,
+        "nz_ratio_threshold": NZ_RATIO_THRESHOLD,
+        "episodes_total": len(episodes_all),
+        "episodes_used_source": "ppo_eval" if len([ep for ep in episodes_all if str(ep.get("source", "")) == "ppo_eval"]) >= 10 else "all",
+        "episodes_used_count": len(ppo_eps),
+        "episode_metrics_top10": metrics_sorted[:10],
+        "fit_data_stats": data_stats,
+        "threshold_grid": THRESHOLDS,
+        "feature_names": feat_names,
+        "channel_models": channel_models,
+        "global_term_votes": {feat_names[k]: int(votes[k]) for k in range(len(feat_names))},
+        "global_term_abs_coef_sum": {feat_names[k]: float(coef_abs_sum[k]) for k in range(len(feat_names))},
+        "global_top_terms": global_top[:12],
+        "complexity_decision": {
+            "nz_ratio_threshold": float(NZ_RATIO_THRESHOLD),
+            "channel_nz_ratio": {f"ch{i}": float(z) for i, z in enumerate(nz_ratios)},
+            "over_complex_channels": over_complex_channels,
+            "use_sindy_prior": bool(use_sindy_prior),
+            "reason": prior_reason,
+        },
+    }
+
+    with open(OUT_JSON, "w", encoding="utf-8") as f:
+        json.dump(result, f, indent=2, ensure_ascii=False)
+
+    print(f"saved: {OUT_JSON}")
+    print("episodes used:", len(ppo_eps), "/", len(episodes_all))
+    print("samples:", data_stats["samples_used"])
+    print("global top terms:", result["global_top_terms"][:8])
+    for cm in channel_models:
+        print(
+            f"ch{cm['channel']} r2={cm['r2']:.4f} mae={cm['mae']:.5f} "
+            f"nz={cm['best_sparse']['nz']} nz_ratio={cm['best_sparse']['nz_ratio']:.3f}"
+        )
+    print("use_sindy_prior:", result["complexity_decision"]["use_sindy_prior"])
+    print("reason:", result["complexity_decision"]["reason"])
+
+
+if __name__ == "__main__":
+    main()

archive/dante_pinball/dante_pinball/legacy/generate_v6_v7_ppo_briefing.py

@@ -0,0 +1,658 @@
+import json
+import os
+import pickle
+from dataclasses import dataclass
+from typing import Dict, List, Tuple
+
+import matplotlib.pyplot as plt
+import numpy as np
+from sklearn.decomposition import PCA
+from sklearn.preprocessing import StandardScaler
+
+from dante_pinball.env.gym_env_dante_total_force import CustomEnv
+
+
+ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir))
+OUT_DIR = os.path.join(ROOT, "output", "report_dante_v2_v5_v6")
+os.makedirs(OUT_DIR, exist_ok=True)
+
+V6_RUN = "d1a3o12_250421_forces02_dante_v6_3"
+V7_RUN = "d1a3o12_250421_forces02_dante_v7_1"
+SEEDS = [11, 29, 47]
+N_ACT = 3
+EVAL_STEPS = 300
+
+
+def feature_dict(obs_t: np.ndarray, obs_prev: np.ndarray, act_prev: np.ndarray) -> Dict[str, float]:
+    o0, o1 = float(obs_t[0]), float(obs_t[1])
+    p0, p1 = float(obs_prev[0]), float(obs_prev[1])
+    a0, a1, a2 = float(act_prev[0]), float(act_prev[1]), float(act_prev[2])
+    return {
+        "obs0": o0,
+        "obs1": o1,
+        "dobs0": o0 - p0,
+        "dobs1": o1 - p1,
+        "sin_obs0": float(np.sin(np.pi * o0)),
+        "sin_obs1": float(np.sin(np.pi * o1)),
+        "cos_obs0": float(np.cos(np.pi * o0)),
+        "cos_obs1": float(np.cos(np.pi * o1)),
+        "tanh_obs0": float(np.tanh(o0)),
+        "tanh_obs1": float(np.tanh(o1)),
+        "act0_l1": a0,
+        "act1_l1": a1,
+        "act2_l1": a2,
+    }
+
+
+def inv_tanh_map(q: float) -> float:
+    qq = float(np.clip(q, -0.999, 0.999))
+    x = np.arctanh(qq) / 1.25
+    return float(np.clip(x, -1.0, 1.0))
+
+
+@dataclass
+class RunData:
+    name: str
+    x: np.ndarray
+    y: np.ndarray
+    num_initial: int
+    cfg: Dict
+
+
+def load_run(name: str) -> RunData:
+    db_path = os.path.join(ROOT, "output", f"{name}_database_live.npz")
+    cfg_path = os.path.join(ROOT, "output", f"{name}_structure_decision.json")
+
+    z = np.load(db_path, allow_pickle=True)
+    x = np.asarray(z["input_x"], dtype=np.float64)
+    y = np.asarray(z["input_y"], dtype=np.float64)
+    with open(cfg_path, "r", encoding="utf-8") as f:
+        cfg = json.load(f)
+
+    return RunData(name=name, x=x, y=y, num_initial=int(cfg["num_initial"]), cfg=cfg)
+
+
+def ppo_npz(seed: int) -> str:
+    return os.path.join(OUT_DIR, f"raw_oldenv_seed_{seed}.npz")
+
+
+def ppo_point_for_v6(seed: int, basis_terms: List[str]) -> np.ndarray:
+    z = np.load(ppo_npz(seed))
+    obs = np.asarray(z["ppo_obs"], dtype=np.float64)
+    act = np.asarray(z["ppo_actions"], dtype=np.float64)
+
+    rows_x = []
+    rows_y = []
+    for t in range(1, len(obs)):
+        fd = feature_dict(obs[t], obs[t - 1], act[t - 1])
+        rows_x.append([1.0] + [float(fd[k]) for k in basis_terms])
+        rows_y.append(act[t])
+
+    X = np.asarray(rows_x, dtype=np.float64)
+    Y = np.asarray(rows_y, dtype=np.float64)
+
+    params = []
+    for ch in range(3):
+        coef, *_ = np.linalg.lstsq(X, Y[:, ch], rcond=None)
+        bias = float(coef[0])
+        params.append(inv_tanh_map(bias / 1.0))
+        for c in coef[1:]:
+            params.append(inv_tanh_map(float(c) / 2.0))
+
+    return np.asarray(params, dtype=np.float64)
+
+
+def phase_weights(phase: float, k: int) -> np.ndarray:
+    z = float(np.mod(phase, 1.0)) * k
+    i0 = int(np.floor(z)) % k
+    frac = float(z - np.floor(z))
+    i1 = (i0 + 1) % k
+    w = np.zeros(k, dtype=np.float64)
+    w[i0] += (1.0 - frac)
+    w[i1] += frac
+    return w
+
+
+def ppo_point_for_v7(seed: int, k: int, period_steps: float) -> np.ndarray:
+    z = np.load(ppo_npz(seed))
+    act = np.asarray(z["ppo_actions"], dtype=np.float64)
+
+    n = int(act.shape[0])
+    phase = 0.0
+    step_phase = 1.0 / max(1e-6, float(period_steps))
+
+    W = np.zeros((n, k), dtype=np.float64)
+    for t in range(n):
+        W[t] = phase_weights(phase, k)
+        phase = (phase + step_phase) % 1.0
+
+    params = []
+    for ch in range(3):
+        coef, *_ = np.linalg.lstsq(W, act[:, ch], rcond=None)
+        coef = np.clip(coef, -1.0, 1.0)
+        params.extend(coef.tolist())
+
+    return np.asarray(params, dtype=np.float64)
+
+
+def fit_pca_and_project(x: np.ndarray, extra: np.ndarray) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+    scaler = StandardScaler()
+    xs = scaler.fit_transform(x)
+    extra_s = scaler.transform(extra)
+
+    pca = PCA(n_components=2, random_state=0)
+    x2 = pca.fit_transform(xs)
+    extra2 = pca.transform(extra_s)
+    return x2, extra2, pca.explained_variance_ratio_
+
+
+def plot_pca(run_name: str, x2: np.ndarray, y: np.ndarray, ppo2: np.ndarray, evr: np.ndarray, out_png: str) -> None:
+    plt.figure(figsize=(8, 6))
+    sc = plt.scatter(x2[:, 0], x2[:, 1], c=y, cmap="viridis", s=12, alpha=0.78)
+    plt.colorbar(sc, label="reward_scaled")
+
+    colors = ["#e41a1c", "#377eb8", "#ff7f00"]
+    for i, seed in enumerate(SEEDS):
+        plt.scatter(
+            [ppo2[i, 0]],
+            [ppo2[i, 1]],
+            s=130,
+            c=colors[i],
+            marker="*",
+            edgecolors="k",
+            linewidths=0.9,
+            label=f"PPO fitted seed {seed}",
+            zorder=6,
+        )
+
+    plt.title(f"{run_name}: PCA with 3 PPO fitted points\\nPC1 {evr[0]*100:.1f}% | PC2 {evr[1]*100:.1f}%")
+    plt.xlabel("PC1")
+    plt.ylabel("PC2")
+    plt.legend(loc="best", fontsize=9)
+    plt.grid(alpha=0.25)
+    plt.tight_layout()
+    plt.savefig(out_png, dpi=170)
+    plt.close()
+
+
+class LinearBasisController:
+    def __init__(self, basis_terms: List[str]):
+        self.basis_terms = list(basis_terms)
+        self.num_basis = len(self.basis_terms)
+        self.total_params = N_ACT * (1 + self.num_basis)
+        self.params = np.zeros(self.total_params, dtype=np.float64)
+        self.obs_l1 = np.zeros(2, dtype=np.float64)
+        self.prev_action = np.zeros(3, dtype=np.float64)
+
+    def reset_state(self, obs0: np.ndarray) -> None:
+        obs0 = np.asarray(obs0, dtype=np.float64).reshape(-1)
+        if obs0.size < 2:
+            obs0 = np.zeros(2, dtype=np.float64)
+        self.obs_l1 = obs0[:2].copy()
+        self.prev_action = np.zeros(3, dtype=np.float64)
+
+    def set_params(self, x: np.ndarray) -> None:
+        x = np.asarray(x, dtype=np.float64).reshape(-1)
+        if x.size != self.total_params:
+            raise ValueError(f"controller params mismatch: {x.size} != {self.total_params}")
+        self.params = np.clip(x, -1.0, 1.0)
+
+    def _feature_dict(self, obs: np.ndarray) -> Dict[str, float]:
+        o = np.asarray(obs, dtype=np.float64).reshape(-1)
+        if o.size < 2:
+            o = np.zeros(2, dtype=np.float64)
+
+        o0, o1 = float(o[0]), float(o[1])
+        o0_l1, o1_l1 = float(self.obs_l1[0]), float(self.obs_l1[1])
+        a0, a1, a2 = float(self.prev_action[0]), float(self.prev_action[1]), float(self.prev_action[2])
+
+        return {
+            "obs0": o0,
+            "obs1": o1,
+            "dobs0": o0 - o0_l1,
+            "dobs1": o1 - o1_l1,
+            "sin_obs0": float(np.sin(np.pi * o0)),
+            "sin_obs1": float(np.sin(np.pi * o1)),
+            "cos_obs0": float(np.cos(np.pi * o0)),
+            "cos_obs1": float(np.cos(np.pi * o1)),
+            "tanh_obs0": float(np.tanh(o0)),
+            "tanh_obs1": float(np.tanh(o1)),
+            "act0_l1": a0,
+            "act1_l1": a1,
+            "act2_l1": a2,
+        }
+
+    def predict(self, obs: np.ndarray) -> np.ndarray:
+        feat = self._feature_dict(obs)
+        out = np.zeros(3, dtype=np.float64)
+        stride = 1 + self.num_basis
+
+        for ch in range(3):
+            off = ch * stride
+            y = np.tanh(1.25 * self.params[off])
+            for k, term in enumerate(self.basis_terms):
+                y += (2.0 * np.tanh(1.25 * self.params[off + 1 + k])) * feat.get(term, 0.0)
+            out[ch] = y
+
+        out = np.clip(out, -1.0, 1.0)
+        obs2 = np.asarray(obs, dtype=np.float64).reshape(-1)
+        if obs2.size < 2:
+            obs2 = np.zeros(2, dtype=np.float64)
+        self.obs_l1 = obs2[:2].copy()
+        self.prev_action = out.copy()
+        return out.astype(np.float32)
+
+
+class PeriodicOpenLoopController:
+    def __init__(self, control_points_per_channel: int, period_steps: float):
+        self.k = int(control_points_per_channel)
+        self.ctrl_points = np.zeros((N_ACT, self.k), dtype=np.float64)
+        self.phase = 0.0
+        self.current_period_steps = float(period_steps)
+        self.total_params = int(N_ACT * self.k)
+
+    def reset_state(self) -> None:
+        self.phase = 0.0
+
+    def _eval_channel(self, points: np.ndarray, phase: float) -> float:
+        p = np.asarray(points, dtype=np.float64).reshape(-1)
+        z = float(np.mod(phase, 1.0)) * self.k
+        i0 = int(np.floor(z)) % self.k
+        frac = float(z - np.floor(z))
+        i1 = (i0 + 1) % self.k
+        return float((1.0 - frac) * p[i0] + frac * p[i1])
+
+    def set_params(self, x: np.ndarray) -> None:
+        x = np.asarray(x, dtype=np.float64).reshape(-1)
+        if x.size != self.total_params:
+            raise ValueError(f"controller params mismatch: {x.size} != {self.total_params}")
+        core = np.clip(x, -1.0, 1.0)
+        self.ctrl_points = core.reshape(N_ACT, self.k)
+
+    def predict(self, _obs: np.ndarray) -> np.ndarray:
+        action = np.zeros(N_ACT, dtype=np.float64)
+        for ch in range(N_ACT):
+            action[ch] = self._eval_channel(self.ctrl_points[ch], self.phase)
+        action = np.clip(action, -1.0, 1.0)
+        step_phase = 1.0 / max(1e-6, float(self.current_period_steps))
+        self.phase = float((self.phase + step_phase) % 1.0)
+        return action.astype(np.float32)
+
+
+def extract_ux_uy(env: CustomEnv) -> Tuple[np.ndarray, np.ndarray]:
+    nx = env.flow_field.FIELD_SHAPE[0]
+    ny = env.flow_field.FIELD_SHAPE[1]
+    env.flow_field.get_ddf()
+    ddf = env.flow_field.ddf.copy().reshape((9, ny, nx)).transpose(2, 1, 0)
+    ux = ddf[:, :, 1] + ddf[:, :, 5] + ddf[:, :, 8] - ddf[:, :, 3] - ddf[:, :, 6] - ddf[:, :, 7]
+    uy = ddf[:, :, 2] + ddf[:, :, 5] + ddf[:, :, 6] - ddf[:, :, 4] - ddf[:, :, 7] - ddf[:, :, 8]
+    return ux.astype(np.float64), uy.astype(np.float64)
+
+
+def vorticity_from_ux_uy(ux: np.ndarray, uy: np.ndarray) -> np.ndarray:
+    dvy_dx = np.gradient(uy, axis=0)
+    dvx_dy = np.gradient(ux, axis=1)
+    return (dvy_dx - dvx_dy).astype(np.float64)
+
+
+def rollout_controller_v6(params: np.ndarray, basis_terms: List[str], device_id: int = 1) -> Dict[str, np.ndarray]:
+    env = CustomEnv(device_id=int(device_id))
+    ctrl = LinearBasisController(basis_terms)
+    ctrl.set_params(params)
+
+    obs, _ = env.reset()
+    obs = np.asarray(obs, dtype=np.float32)
+    ctrl.reset_state(obs)
+
+    obs_hist = []
+    act_hist = []
+    rew_hist = []
+
+    try:
+        for _ in range(EVAL_STEPS):
+            act = ctrl.predict(obs)
+            next_obs, reward, done, trunc, _ = env.step(act)
+            obs_hist.append(np.asarray(obs, dtype=np.float64).copy())
+            act_hist.append(np.asarray(act, dtype=np.float64).copy())
+            rew_hist.append(float(reward))
+            obs = np.asarray(next_obs, dtype=np.float32)
+            if done or trunc:
+                obs, _ = env.reset()
+                obs = np.asarray(obs, dtype=np.float32)
+                ctrl.reset_state(obs)
+
+        ux, uy = extract_ux_uy(env)
+    finally:
+        env.close()
+
+    return {
+        "obs": np.asarray(obs_hist, dtype=np.float64),
+        "act": np.asarray(act_hist, dtype=np.float64),
+        "rew": np.asarray(rew_hist, dtype=np.float64),
+        "ux": ux,
+        "uy": uy,
+    }
+
+
+def rollout_controller_v7(params: np.ndarray, k: int, period_steps: float, device_id: int = 0) -> Dict[str, np.ndarray]:
+    env = CustomEnv(device_id=int(device_id))
+    ctrl = PeriodicOpenLoopController(control_points_per_channel=k, period_steps=float(period_steps))
+    ctrl.set_params(params)
+
+    obs, _ = env.reset()
+    obs = np.asarray(obs, dtype=np.float32)
+    ctrl.reset_state()
+
+    obs_hist = []
+    act_hist = []
+    rew_hist = []
+
+    try:
+        for _ in range(EVAL_STEPS):
+            act = ctrl.predict(obs)
+            next_obs, reward, done, trunc, _ = env.step(act)
+            obs_hist.append(np.asarray(obs, dtype=np.float64).copy())
+            act_hist.append(np.asarray(act, dtype=np.float64).copy())
+            rew_hist.append(float(reward))
+            obs = np.asarray(next_obs, dtype=np.float32)
+            if done or trunc:
+                obs, _ = env.reset()
+                obs = np.asarray(obs, dtype=np.float32)
+                ctrl.reset_state()
+
+        ux, uy = extract_ux_uy(env)
+    finally:
+        env.close()
+
+    return {
+        "obs": np.asarray(obs_hist, dtype=np.float64),
+        "act": np.asarray(act_hist, dtype=np.float64),
+        "rew": np.asarray(rew_hist, dtype=np.float64),
+        "ux": ux,
+        "uy": uy,
+    }
+
+
+def best_ppo_seed() -> Tuple[int, float]:
+    best_seed = None
+    best_tail = -1e18
+    for s in SEEDS:
+        z = np.load(ppo_npz(s))
+        r = np.asarray(z["ppo_rewards"], dtype=np.float64)
+        tail = float(np.mean(r[-100:]))
+        if tail > best_tail:
+            best_tail = tail
+            best_seed = s
+    return int(best_seed), float(best_tail)
+
+
+def load_ppo_series(seed: int) -> Dict[str, np.ndarray]:
+    z = np.load(ppo_npz(seed))
+    return {
+        "obs": np.asarray(z["ppo_obs"], dtype=np.float64),
+        "act": np.asarray(z["ppo_actions"], dtype=np.float64),
+        "rew": np.asarray(z["ppo_rewards"], dtype=np.float64),
+    }
+
+
+def plot_obs_act_time(ppo: Dict[str, np.ndarray], v6: Dict[str, np.ndarray], v7: Dict[str, np.ndarray], out_png: str) -> None:
+    t = np.arange(EVAL_STEPS)
+    fig, axes = plt.subplots(5, 1, figsize=(12, 12), sharex=True, constrained_layout=True)
+
+    series = [
+        (0, "obs0", ppo["obs"][:, 0], v6["obs"][:, 0], v7["obs"][:, 0]),
+        (1, "obs1", ppo["obs"][:, 1], v6["obs"][:, 1], v7["obs"][:, 1]),
+        (2, "act0", ppo["act"][:, 0], v6["act"][:, 0], v7["act"][:, 0]),
+        (3, "act1", ppo["act"][:, 1], v6["act"][:, 1], v7["act"][:, 1]),
+        (4, "act2", ppo["act"][:, 2], v6["act"][:, 2], v7["act"][:, 2]),
+    ]
+
+    for idx, name, y0, y1, y2 in series:
+        ax = axes[idx]
+        ax.plot(t, y0, lw=1.2, label="PPO")
+        ax.plot(t, y1, lw=1.2, label="v6")
+        ax.plot(t, y2, lw=1.2, label="v7")
+        ax.set_ylabel(name)
+        ax.grid(alpha=0.25)
+        if idx == 0:
+            ax.legend(loc="best", ncol=3)
+    axes[-1].set_xlabel("time step")
+    fig.suptitle("Obs-Act time series comparison (300 steps)")
+    fig.savefig(out_png, dpi=170)
+    plt.close(fig)
+
+
+def plot_vorticity_maps(omega_ppo: np.ndarray, omega_v6: np.ndarray, omega_v7: np.ndarray, out_png: str) -> float:
+    gmax = float(max(np.max(np.abs(omega_ppo)), np.max(np.abs(omega_v6)), np.max(np.abs(omega_v7))))
+    vmax = max(1e-12, 0.1 * gmax)
+
+    fig, axes = plt.subplots(1, 3, figsize=(15, 4.8), constrained_layout=True)
+    data = [(omega_ppo, "PPO"), (omega_v6, "v6"), (omega_v7, "v7")]
+    for ax, (om, title) in zip(axes, data):
+        im = ax.imshow(om.T, origin="lower", cmap="RdBu_r", vmin=-vmax, vmax=vmax)
+        ax.set_title(title)
+        ax.set_xlabel("x")
+        ax.set_ylabel("y")
+    cbar = fig.colorbar(im, ax=axes.ravel().tolist(), shrink=0.95)
+    cbar.set_label("vorticity")
+    fig.suptitle(f"Final vorticity maps, unified range +/-{vmax:.4f} (10% global max)")
+    fig.savefig(out_png, dpi=170)
+    plt.close(fig)
+    return float(vmax)
+
+
+def build_design(obs: np.ndarray, act: np.ndarray, terms: List[str]) -> Tuple[np.ndarray, np.ndarray]:
+    X_rows = []
+    Y_rows = []
+    for t in range(1, len(obs)):
+        fd = feature_dict(obs[t], obs[t - 1], act[t - 1])
+        X_rows.append([1.0] + [float(fd[k]) for k in terms])
+        Y_rows.append(act[t])
+    return np.asarray(X_rows, dtype=np.float64), np.asarray(Y_rows, dtype=np.float64)
+
+
+def fit_multi_seed_linear(terms: List[str]) -> Dict[str, object]:
+    Ws = []
+    r2s = []
+    for s in SEEDS:
+        z = np.load(ppo_npz(s))
+        obs = np.asarray(z["ppo_obs"], dtype=np.float64)
+        act = np.asarray(z["ppo_actions"], dtype=np.float64)
+        X, Y = build_design(obs, act, terms)
+        W = []
+        r2_ch = []
+        for ch in range(3):
+            c, *_ = np.linalg.lstsq(X, Y[:, ch], rcond=None)
+            pred = X @ c
+            ssr = float(np.sum((Y[:, ch] - pred) ** 2))
+            sst = float(np.sum((Y[:, ch] - np.mean(Y[:, ch])) ** 2) + 1e-12)
+            r2 = float(1.0 - ssr / sst)
+            W.append(c)
+            r2_ch.append(r2)
+        Ws.append(np.asarray(W, dtype=np.float64))
+        r2s.append(np.asarray(r2_ch, dtype=np.float64))
+    Wm = np.mean(np.asarray(Ws), axis=0)
+    r2m = np.mean(np.asarray(r2s), axis=0)
+    return {
+        "terms": ["bias1"] + list(terms),
+        "W_mean": Wm,
+        "r2_by_action_mean": r2m,
+        "r2_mean": float(np.mean(r2m)),
+    }
+
+
+def matrix_to_latex(W: np.ndarray, precision: int = 4) -> str:
+    rows = []
+    for i in range(W.shape[0]):
+        rows.append(" & ".join([f"{float(v):.{precision}f}" for v in W[i]]))
+    body = " \\\\ ".join(rows)
+    return "\\begin{bmatrix}" + body + "\\end{bmatrix}"
+
+
+def main() -> None:
+    v6 = load_run(V6_RUN)
+    v7 = load_run(V7_RUN)
+
+    v6_basis = list(v6.cfg["basis_terms"])
+    v6_ppo_pts = np.vstack([ppo_point_for_v6(s, v6_basis) for s in SEEDS])
+
+    k = int(v7.cfg["control_points_per_channel"])
+    period_steps = float(v7.cfg["period_steps"])
+    v7_ppo_pts = np.vstack([ppo_point_for_v7(s, k=k, period_steps=period_steps) for s in SEEDS])
+
+    v6_x2, v6_p2, v6_evr = fit_pca_and_project(v6.x, v6_ppo_pts)
+    v7_x2, v7_p2, v7_evr = fit_pca_and_project(v7.x, v7_ppo_pts)
+
+    fig_v6_pca = os.path.join(OUT_DIR, "brief_v6_3_pca_with_ppo3.png")
+    fig_v7_pca = os.path.join(OUT_DIR, "brief_v7_1_pca_with_ppo3.png")
+    plot_pca(v6.name, v6_x2, v6.y, v6_p2, v6_evr, fig_v6_pca)
+    plot_pca(v7.name, v7_x2, v7.y, v7_p2, v7_evr, fig_v7_pca)
+
+    with open(os.path.join(ROOT, "output", f"{V6_RUN}_best_meta.pkl"), "rb") as f:
+        v6_meta = pickle.load(f)
+    with open(os.path.join(ROOT, "output", f"{V7_RUN}_best_meta.pkl"), "rb") as f:
+        v7_meta = pickle.load(f)
+
+    v6_best = np.asarray(v6_meta["best_params"], dtype=np.float64)
+    v7_best = np.asarray(v7_meta["best_params"], dtype=np.float64)
+
+    v6_roll = rollout_controller_v6(v6_best, basis_terms=v6_basis, device_id=1)
+    v7_roll = rollout_controller_v7(v7_best, k=k, period_steps=period_steps, device_id=0)
+
+    seed_star, tail_star = best_ppo_seed()
+    ppo_series = load_ppo_series(seed_star)
+
+    fig_ts = os.path.join(OUT_DIR, "brief_v6_v7_ppo_obs_act_time.png")
+    plot_obs_act_time(ppo_series, v6_roll, v7_roll, fig_ts)
+
+    ppo_flow_npz = os.path.join(OUT_DIR, "fig_oldenv_flow_best.npz")
+    zf = np.load(ppo_flow_npz)
+    ppo_ux = np.asarray(zf["ux"], dtype=np.float64)
+    ppo_uy = np.asarray(zf["uy"], dtype=np.float64)
+
+    omega_ppo = vorticity_from_ux_uy(ppo_ux, ppo_uy)
+    omega_v6 = vorticity_from_ux_uy(v6_roll["ux"], v6_roll["uy"])
+    omega_v7 = vorticity_from_ux_uy(v7_roll["ux"], v7_roll["uy"])
+
+    fig_omega = os.path.join(OUT_DIR, "brief_v6_v7_ppo_final_vorticity.png")
+    omega_vmax = plot_vorticity_maps(omega_ppo, omega_v6, omega_v7, fig_omega)
+
+    with open(os.path.join(OUT_DIR, "sindy_group_sparsity_scan.json"), "r", encoding="utf-8") as f:
+        group_scan = json.load(f)
+    with open(os.path.join(OUT_DIR, "sindy_constrained_profile_search.json"), "r", encoding="utf-8") as f:
+        constrained = json.load(f)
+    with open(os.path.join(OUT_DIR, "dante_ackley_highdim_sweep.json"), "r", encoding="utf-8") as f:
+        highdim = json.load(f)
+    with open(os.path.join(OUT_DIR, "v6_v7_reaudit_frozen_facts_20260323.json"), "r", encoding="utf-8") as f:
+        frozen = json.load(f)
+    with open(os.path.join(OUT_DIR, "v6_v7_acq_diagnostics_summary_20260323.json"), "r", encoding="utf-8") as f:
+        acq = json.load(f)
+
+    full_terms = [
+        "obs0", "obs1", "dobs0", "dobs1", "sin_obs0", "sin_obs1", "cos_obs0", "cos_obs1",
+        "tanh_obs0", "tanh_obs1", "act0_l1", "act1_l1", "act2_l1",
+    ]
+    reduced_terms = list(constrained["best_chrono"]["basis_terms"])
+
+    full_fit = fit_multi_seed_linear(full_terms)
+    reduced_fit = fit_multi_seed_linear(reduced_terms)
+
+    highdim_results = list(highdim.get("results", []))
+    highdim_neg_r2 = int(sum(1 for r in highdim_results if float(r.get("holdout_r2", 0.0)) < 0.0))
+    highdim_neg_gain = int(sum(1 for r in highdim_results if float(r.get("acq_gain_scaled", 0.0)) < 0.0))
+
+    summary = {
+        "runs": {"v6": V6_RUN, "v7": V7_RUN, "ppo_seed_used": int(seed_star), "ppo_tail100": float(tail_star)},
+        "figures": {
+            "v6_pca": fig_v6_pca,
+            "v7_pca": fig_v7_pca,
+            "obs_act_time": fig_ts,
+            "vorticity": fig_omega,
+        },
+        "vorticity_unified_abs_limit": float(omega_vmax),
+        "reduction": {
+            "full_r2_mean_over_seeds": float(group_scan["full_model"]["r2_mean_over_seeds"]),
+            "best_chrono_basis_terms": reduced_terms,
+            "best_chrono_r2_mean_over_seeds": float(constrained["best_chrono"]["chrono_r2_mean_over_seeds"]),
+            "best_chrono_r2_min_over_seeds": float(constrained["best_chrono"]["chrono_r2_min_over_seeds"]),
+            "group_scan_chosen": group_scan.get("chosen", {}),
+            "full_fit": {
+                "terms": full_fit["terms"],
+                "W_mean": np.asarray(full_fit["W_mean"]).tolist(),
+                "r2_by_action_mean": np.asarray(full_fit["r2_by_action_mean"]).tolist(),
+                "r2_mean": float(full_fit["r2_mean"]),
+            },
+            "reduced_fit": {
+                "terms": reduced_fit["terms"],
+                "W_mean": np.asarray(reduced_fit["W_mean"]).tolist(),
+                "r2_by_action_mean": np.asarray(reduced_fit["r2_by_action_mean"]).tolist(),
+                "r2_mean": float(reduced_fit["r2_mean"]),
+            },
+            "latex": {
+                "full_terms": "\\phi_{full}=[1,obs_0,obs_1,\\Delta obs_0,\\Delta obs_1,\\sin(\\pi obs_0),\\sin(\\pi obs_1),\\cos(\\pi obs_0),\\cos(\\pi obs_1),\\tanh(obs_0),\\tanh(obs_1),a_{0,t-1},a_{1,t-1},a_{2,t-1}]^\\top",
+                "reduced_terms": "\\phi_{red}=[1,obs_1,\\sin(\\pi obs_0),\\cos(\\pi obs_0),a_{1,t-1}]^\\top",
+                "W_full_mean": matrix_to_latex(np.asarray(full_fit["W_mean"], dtype=np.float64)),
+                "W_reduced_mean": matrix_to_latex(np.asarray(reduced_fit["W_mean"], dtype=np.float64)),
+            },
+        },
+        "highdim": {
+            "n_cases": int(len(highdim_results)),
+            "n_neg_holdout_r2": int(highdim_neg_r2),
+            "n_neg_acq_gain": int(highdim_neg_gain),
+        },
+        "dual_surrogate": frozen.get("surrogate_log_stats", {}),
+        "acq_summary": acq,
+    }
+
+    summary_path = os.path.join(OUT_DIR, "v6_v7_ppo_briefing_summary.json")
+    with open(summary_path, "w", encoding="utf-8") as f:
+        json.dump(summary, f, indent=2, ensure_ascii=False)
+
+    md_path = os.path.join(OUT_DIR, "v6_v7_ppo_briefing_20260324.md")
+    with open(md_path, "w", encoding="utf-8") as f:
+        f.write("# v6/v7/PPO 综合简报\n\n")
+        f.write("## 1) PCA（含3个PPO拟合点）\n")
+        f.write(f"- v6图: {fig_v6_pca}\n")
+        f.write(f"- v7图: {fig_v7_pca}\n\n")
+
+        f.write("## 2) obs-act时序 + 最终涡量\n")
+        f.write(f"- 时序图: {fig_ts}\n")
+        f.write(f"- 最终涡量图: {fig_omega}\n")
+        f.write(f"- 涡量统一色条范围: ±{omega_vmax:.6f}（按三者全局|omega|max的10%）\n")
+        f.write(f"- PPO时序选用seed={seed_star}（tail100={tail_star:.5f}）\n\n")
+
+        f.write("## 3) 函数约简、关键函数、最终组合\n")
+        f.write(f"- 全特征模型平均R2: {group_scan['full_model']['r2_mean_over_seeds']:.6f}\n")
+        f.write(f"- 约束搜索best_chrono基函数: {reduced_terms}\n")
+        f.write(f"- best_chrono平均R2: {constrained['best_chrono']['chrono_r2_mean_over_seeds']:.6f}\n")
+        f.write(f"- best_chrono最差seed R2: {constrained['best_chrono']['chrono_r2_min_over_seeds']:.6f}\n")
+        f.write("- 关键函数解释: obs1给出主状态幅值，sin/cos(pi*obs0)提供周期相位，act1_l1提供单步记忆。\n\n")
+
+        f.write("### 学到方程与拟合方程（LaTeX）\n")
+        f.write("- 全特征学到方程（3动作联合线性写法）:\n")
+        f.write("$$\\mathbf{a}_t = W_{full}\\,\\phi_{full,t}$$\n")
+        f.write("$$" + summary['reduction']['latex']['full_terms'] + "$$\n")
+        f.write("$$W_{full}=" + summary['reduction']['latex']['W_full_mean'] + "$$\n")
+        f.write(f"- 全特征拟合R2(本次重算, action均值): {full_fit['r2_mean']:.6f}\n\n")
+
+        f.write("- 约简拟合方程（best_chrono）:\n")
+        f.write("$$\\mathbf{a}_t = W_{red}\\,\\phi_{red,t}$$\n")
+        f.write("$$" + summary['reduction']['latex']['reduced_terms'] + "$$\n")
+        f.write("$$W_{red}=" + summary['reduction']['latex']['W_reduced_mean'] + "$$\n")
+        f.write(f"- 约简拟合R2(本次重算, action均值): {reduced_fit['r2_mean']:.6f}\n\n")
+
+        f.write("## 4) 高维能力与现实约束反思\n")
+        f.write(f"- 高维扫描样本数: {len(highdim_results)}\n")
+        f.write(f"- holdout_r2<0 的case数: {highdim_neg_r2}/{len(highdim_results)}\n")
+        f.write(f"- 首轮acq_gain<0 的case数: {highdim_neg_gain}/{len(highdim_results)}\n")
+        f.write("- 解释: 高维下代理可辨识度不足时，Tree探索会被误导，出现边界漂移与收益停滞。\n")
+        f.write("- 与论文对齐: DANTE强调DNN surrogate与自适应探索协同；在你的流体控制里，受噪声、时序漂移和高维参数化耦合影响，样本效率会显著下降。\n")
+        f.write("- 双代理是否有帮助: 当前日志显示ensemble路径提供了可运行冗余（CNN失败时MLP兜底），但在v6_3其val_r2均值仍偏低，收益主要体现在稳定性而非显著提升最优值。\n")
+
+    print("saved:", summary_path)
+    print("saved:", md_path)
+    print("saved figs:", fig_v6_pca, fig_v7_pca, fig_ts, fig_omega)
+
+
+if __name__ == "__main__":
+    main()

archive/dante_pinball/dante_pinball/legacy/gym_env_dante_total_force.py

@@ -0,0 +1,271 @@
+import gymnasium as gym
+import numpy as np
+from gymnasium import spaces
+from collections import deque
+from typing import Tuple
+import sys
+import os
+import queue
+
+os.environ["OMP_NUM_THREADS"] = "1"
+os.environ["MKL_NUM_THREADS"] = "1"
+
+current_dir = os.path.dirname(os.path.abspath(__file__))
+parent_dir = os.path.abspath(os.path.join(current_dir, os.pardir))
+sys.path.append(parent_dir)
+from CelerisLab import FlowField
+from CelerisLab import utils
+
+config_cuda = utils.load_cuda_config(
+    os.path.join(parent_dir, "configs", "config_cuda.json")
+)
+config_field = utils.load_flow_field_config(
+    os.path.join(parent_dir, "configs", "config_flowfield.json")
+)
+
+S_DIM, A_DIM = 2, 3
+U0 = config_field.velocity
+SAMPLE_INTERVAL = 800
+FIFO_LEN = 150
+CONV_LEN = 36
+if config_field.data_type == "FP32":
+    DATA_TYPE = np.float32
+else:
+    raise ValueError(f"Unsupported data type {config_field.data_type}.")
+
+
+class CustomEnv(gym.Env):
+    """DANTE-only environment with deterministic reset semantics and numeric-failure surfacing."""
+
+    metadata = {"render_modes": ["human"], "render_fps": 1000 / SAMPLE_INTERVAL}
+
+    FAILURE_NONE = 0
+    FAILURE_NUMERIC = 1
+    FAILURE_NONFINITE_OBS = 2
+    FAILURE_OBS_OOB = 3
+
+    def __init__(
+        self,
+        device_id: int = 0,
+        obs_fail_bound: float = 2.0,
+        obs_clip_bound: float = 3.0,
+        reward_weights: Tuple[float, float, float] = (0.3, 0.3, 0.4),
+    ):
+        super().__init__()
+        self.action_space = spaces.Box(low=-1, high=1, shape=(A_DIM,), dtype=DATA_TYPE)
+        self.observation_space = spaces.Box(
+            low=-obs_clip_bound,
+            high=obs_clip_bound,
+            shape=(S_DIM,),
+            dtype=DATA_TYPE,
+        )
+
+        self.obs_fail_bound = float(obs_fail_bound)
+        self.obs_clip_bound = float(obs_clip_bound)
+        rw = np.asarray(reward_weights, dtype=DATA_TYPE)
+        if rw.size != 3:
+            raise ValueError("reward_weights must have length 3: (cd, cl, sim)")
+        rw_sum = float(np.sum(rw))
+        if rw_sum <= 0:
+            raise ValueError("reward_weights sum must be positive")
+        self.reward_weights = rw / rw_sum
+
+        self.fifo_states = deque(maxlen=FIFO_LEN)
+        self.target_states = np.empty((0, 6), dtype=DATA_TYPE)
+        self.force_norm_fact = 1.0
+        self.torque_norm_fact = 1.0
+        self.sens_norm_fact = np.ones(6, dtype=DATA_TYPE)
+        self.sens_deviation = np.zeros(6, dtype=DATA_TYPE)
+
+        self.reward_cd = 0.0
+        self.reward_cl = 0.0
+        self.reward_sim = 0.0
+        self.current_step = 0
+
+        self.flow_field = FlowField(config_field, config_cuda, device_id)
+        L0 = 20
+        u0 = config_field.velocity
+        nx = self.flow_field.FIELD_SHAPE[0]
+        ny = self.flow_field.FIELD_SHAPE[1]
+
+        center: Tuple[float, float, float] = (10 * L0, (ny - 1) / 2, 0)
+        self.flow_field.add_cylinder(center, L0)
+        center = (40 * L0, (ny - 1) / 2 + 2 * L0, 0)
+        self.flow_field.add_sensor(center, L0 / 4)
+        center = (40 * L0, (ny - 1) / 2, 0)
+        self.flow_field.add_sensor(center, L0 / 4)
+        center = (40 * L0, (ny - 1) / 2 - 2 * L0, 0)
+        self.flow_field.add_sensor(center, L0 / 4)
+        self.flow_field.run(int(4 * nx / u0), np.zeros(4, dtype=DATA_TYPE))
+
+        for _ in range(FIFO_LEN):
+            self.flow_field.run(SAMPLE_INTERVAL, np.zeros(4, dtype=DATA_TYPE))
+            new_state = self.flow_field.obs.copy()[2:8]
+            self.target_states = np.vstack((self.target_states, new_state))
+
+        center = (30 * L0, (ny - 1) / 2, 0)
+        self.flow_field.add_cylinder(center, L0 / 2)
+        center = (31.3 * L0, (ny - 1) / 2 + 0.75 * L0, 0)
+        self.flow_field.add_cylinder(center, L0 / 2)
+        center = (31.3 * L0, (ny - 1) / 2 - 0.75 * L0, 0)
+        self.flow_field.add_cylinder(center, L0 / 2)
+        self.flow_field.run(int(4 * nx / u0), np.zeros(7, dtype=DATA_TYPE))
+        self.flow_field.get_ddf()
+        self.flow_field.save_ddf()
+
+        for _ in range(FIFO_LEN):
+            self.flow_field.run(SAMPLE_INTERVAL, np.zeros(7, dtype=DATA_TYPE))
+            self.fifo_states.append(self.flow_field.obs.copy()[2:14])
+
+        temp_states = np.array(self.fifo_states)
+        self.force_norm_fact = 6 * np.max(np.abs(temp_states[:, 6:12]))
+        temp_torque = (
+            -temp_states[:, 1]
+            - temp_states[:, 2] * np.sqrt(3) / 2
+            + temp_states[:, 3] / 2
+            + temp_states[:, 4] * np.sqrt(3) / 2
+            + temp_states[:, 5] / 2
+        )
+        self.torque_norm_fact = 10 * np.max(np.abs(temp_torque))
+
+        for i in range(6):
+            self.sens_deviation[i] = np.mean(temp_states[:, i])
+            self.sens_norm_fact[i] = 5 * np.max(np.abs(temp_states[:, i] - self.sens_deviation[i]))
+
+        self.flow_field.apply_ddf()
+
+        for _ in range(FIFO_LEN):
+            self.flow_field.run(
+                SAMPLE_INTERVAL,
+                np.array([0.0, 0.0, 0.0, 0.0, 0.0, -4 * u0, 4 * u0], dtype=DATA_TYPE),
+            )
+            self.fifo_states.append(self.flow_field.obs.copy()[2:14])
+
+        self.save_states = self.fifo_states.copy()
+        # self.flow_field.apply_ddf()
+        self.flow_field.get_ddf()
+        self.flow_field.save_ddf()
+
+    def _calc_lag(self, target: np.ndarray, state: np.ndarray) -> int:
+        target_mean = np.mean(target)
+        state_mean = np.mean(state)
+        correlation = np.correlate(target - target_mean, state - state_mean, "full")
+        lags = np.arange(-len(target) + 1, len(target))
+        return int(lags[np.argmax(correlation)])
+
+    def _calc_dtw_sim(self, target: np.ndarray, state: np.ndarray) -> float:
+        n = len(target)
+        m = len(state)
+        dtw_matrix = np.full((n + 1, m + 1), np.inf)
+        dtw_matrix[0, 0] = 0
+        for i in range(1, n + 1):
+            for j in range(1, m + 1):
+                cost = abs(target[i - 1] - state[j - 1])
+                last_min = min(
+                    dtw_matrix[i - 1, j],
+                    dtw_matrix[i, j - 1],
+                    dtw_matrix[i - 1, j - 1],
+                )
+                dtw_matrix[i, j] = cost + last_min
+        return float(1 - (dtw_matrix[n, m] / len(target)))
+
+    def _compute_obs_reward(self):
+        states = np.array(self.fifo_states)
+        forces = states[-1, 6:12] / self.force_norm_fact
+
+        obs_drag = float((forces[0] + forces[2] + forces[4]) / 3)
+        obs_lift = float((forces[1] + forces[3] + forces[5]) / 3)
+
+        similarities = 0.0
+        id_sens = 1
+        target_seq = self.target_states[CONV_LEN : 2 * CONV_LEN, id_sens]
+        state_seq = states[-CONV_LEN:, id_sens]
+        lag = self._calc_lag(target_seq, state_seq)
+
+        for i in range(0, 6):
+            target_seq = np.roll(self.target_states[:, i], -lag)[CONV_LEN : 2 * CONV_LEN]
+            state_seq = states[-CONV_LEN:, i]
+            similarities += self._calc_dtw_sim(target_seq, state_seq) / 6
+
+        self.reward_cd = float(np.exp(-np.abs(obs_drag * 20)))
+        self.reward_cl = float(np.exp(-np.abs(obs_lift * 80)))
+        self.reward_sim = float(np.exp(-10 * np.abs(similarities - 1)))
+        reward = float(
+            np.minimum(
+                self.reward_weights[0] * self.reward_cd
+                + self.reward_weights[1] * self.reward_cl
+                + self.reward_weights[2] * self.reward_sim,
+                1.0,
+            )
+        )
+        observation = np.array([forces[0], forces[1]], dtype=DATA_TYPE)
+        return observation, reward
+
+    def step(self, action):
+        assert self.action_space.contains(action), "%r (%s) invalid" % (
+            action,
+            type(action),
+        )
+
+        result_queue = queue.Queue()
+
+        def run_flow_field(act):
+            self.flow_field.context.push()
+            u0 = config_field.velocity
+            try:
+                temp = np.zeros(7, dtype=DATA_TYPE)
+                temp[4:7] = np.array((act * 8 + [0, -4, 4]) * u0, dtype=DATA_TYPE)
+                self.flow_field.run(SAMPLE_INTERVAL, temp)
+            finally:
+                self.flow_field.context.pop()
+            self.fifo_states.append(self.flow_field.obs.copy()[2:14])
+
+        def proc_data():
+            result_queue.put(self._compute_obs_reward())
+
+        run_flow_field(action)
+
+        if self.flow_field.has_numeric_error():
+            self.current_step += 1
+            obs = np.zeros(S_DIM, dtype=DATA_TYPE)
+            info = {
+                "failure_code": self.FAILURE_NUMERIC,
+                "numeric_error": True,
+                "raw_obs": obs.copy(),
+            }
+            return obs, 0.0, False, True, info
+
+        proc_data()
+        observation, reward = result_queue.get()
+        raw_obs = np.asarray(observation, dtype=DATA_TYPE).copy()
+
+        failure_code = self.FAILURE_NONE
+        if not np.all(np.isfinite(observation)):
+            failure_code = self.FAILURE_NONFINITE_OBS
+        elif np.any(np.abs(observation) > self.obs_fail_bound):
+            failure_code = self.FAILURE_OBS_OOB
+
+        truncated = failure_code != self.FAILURE_NONE
+        if truncated:
+            reward = 0.0
+            observation = np.zeros(S_DIM, dtype=DATA_TYPE)
+        else:
+            observation = np.clip(observation, -self.obs_clip_bound, self.obs_clip_bound)
+
+        self.current_step += 1
+        info = {
+            "failure_code": int(failure_code),
+            "numeric_error": False,
+            "raw_obs": raw_obs,
+        }
+        return observation.astype(np.float32), float(reward), False, bool(truncated), info
+
+    def reset(self, seed=None):
+        self.flow_field.restore_ddf()
+        self.flow_field.apply_ddf()
+        self.fifo_states = self.save_states.copy()
+        self.current_step = 0
+        return np.zeros(S_DIM, dtype=np.float32), {}
+
+    def close(self):
+        self.flow_field.__del__()

archive/dante_pinball/dante_pinball/legacy/v6_init_surrogate_mlp_cnn_compare.py

@@ -0,0 +1,216 @@
+import json
+import os
+import time
+from dataclasses import dataclass
+from typing import Dict, List, Tuple
+
+import numpy as np
+from sklearn.metrics import mean_absolute_error, r2_score
+from sklearn.model_selection import train_test_split
+from sklearn.preprocessing import StandardScaler
+
+os.environ.setdefault("TF_CPP_MIN_LOG_LEVEL", "2")
+os.environ.setdefault("TF_FORCE_GPU_ALLOW_GROWTH", "true")
+
+import tensorflow as tf
+from tensorflow.keras.callbacks import EarlyStopping
+from tensorflow.keras.layers import Conv1D, Dense, Dropout, Flatten, Input, MaxPooling1D
+from tensorflow.keras.models import Sequential
+from tensorflow.keras.optimizers import Adam
+
+
+CURRENT_DIR = os.path.dirname(os.path.abspath(__file__))
+ROOT = os.path.abspath(os.path.join(CURRENT_DIR, os.pardir))
+OUT_DIR = os.path.join(ROOT, "output", "report_dante_v2_v5_v6")
+os.makedirs(OUT_DIR, exist_ok=True)
+
+DB_PATH = os.path.join(ROOT, "output", "d1a3o12_250421_forces02_dante_v6_database_live.npz")
+DECISION_PATH = os.path.join(ROOT, "output", "d1a3o12_250421_forces02_dante_v6_1_structure_decision.json")
+
+
+@dataclass
+class ModelSpec:
+    name: str
+    kind: str  # mlp | cnn
+
+
+def set_tf_device(device_id: int = 1) -> str:
+    gpus = tf.config.list_physical_devices("GPU")
+    if not gpus:
+        return "CPU"
+    idx = int(max(0, min(len(gpus) - 1, device_id)))
+    try:
+        tf.config.set_visible_devices([gpus[idx]], "GPU")
+        tf.config.experimental.set_memory_growth(gpus[idx], True)
+        return f"GPU:{idx}"
+    except RuntimeError:
+        return f"GPU:{idx}(runtime_initialized)"
+
+
+def load_init_dataset() -> Tuple[np.ndarray, np.ndarray, Dict]:
+    if not os.path.exists(DB_PATH):
+        raise FileNotFoundError(DB_PATH)
+    if not os.path.exists(DECISION_PATH):
+        raise FileNotFoundError(DECISION_PATH)
+
+    with open(DECISION_PATH, "r", encoding="utf-8") as f:
+        decision = json.load(f)
+
+    n_init = int(decision["num_initial"])
+    db = np.load(DB_PATH, allow_pickle=True)
+    x = np.asarray(db["input_x"], dtype=np.float64)
+    y = np.asarray(db["input_y"], dtype=np.float64).reshape(-1)
+
+    if len(x) < n_init:
+        raise RuntimeError(f"DB samples {len(x)} < num_initial {n_init}")
+
+    x0 = x[:n_init]
+    y0 = y[:n_init]
+    return x0, y0, decision
+
+
+def make_mlp(input_dims: int) -> Sequential:
+    model = Sequential(
+        [
+            Input(shape=(input_dims,)),
+            Dense(128, activation="elu"),
+            Dropout(0.10),
+            Dense(64, activation="elu"),
+            Dropout(0.10),
+            Dense(32, activation="elu"),
+            Dense(1, activation="linear"),
+        ]
+    )
+    model.compile(optimizer=Adam(learning_rate=1e-3), loss="mse", metrics=["mae"])
+    return model
+
+
+def make_cnn(input_dims: int) -> Sequential:
+    model = Sequential(
+        [
+            Input(shape=(input_dims, 1)),
+            Conv1D(128, kernel_size=3, padding="same", activation="elu"),
+            MaxPooling1D(pool_size=2, strides=1),
+            Dropout(0.2),
+            Conv1D(64, kernel_size=3, padding="same", activation="elu"),
+            MaxPooling1D(pool_size=2, strides=1),
+            Dropout(0.2),
+            Conv1D(32, kernel_size=3, padding="same", activation="elu"),
+            Conv1D(16, kernel_size=3, padding="same", activation="elu"),
+            Flatten(),
+            Dense(64, activation="elu"),
+            Dense(1, activation="linear"),
+        ]
+    )
+    model.compile(optimizer=Adam(learning_rate=1e-3), loss="mse", metrics=["mae"])
+    return model
+
+
+def run_one_split(x: np.ndarray, y: np.ndarray, seed: int, spec: ModelSpec) -> Dict:
+    x_tr, x_te, y_tr, y_te = train_test_split(x, y, test_size=0.30, random_state=seed, shuffle=True)
+
+    x_scaler = StandardScaler()
+    y_scaler = StandardScaler()
+    x_tr_s = x_scaler.fit_transform(x_tr)
+    x_te_s = x_scaler.transform(x_te)
+    y_tr_s = y_scaler.fit_transform(y_tr.reshape(-1, 1)).reshape(-1)
+
+    if spec.kind == "mlp":
+        model = make_mlp(x.shape[1])
+        xtr_in = x_tr_s
+        xte_in = x_te_s
+    elif spec.kind == "cnn":
+        model = make_cnn(x.shape[1])
+        xtr_in = x_tr_s.reshape(len(x_tr_s), x.shape[1], 1)
+        xte_in = x_te_s.reshape(len(x_te_s), x.shape[1], 1)
+    else:
+        raise ValueError(spec.kind)
+
+    cb = [EarlyStopping(monitor="val_loss", patience=25, restore_best_weights=True)]
+    hist = model.fit(
+        xtr_in,
+        y_tr_s,
+        validation_split=0.25,
+        batch_size=32,
+        epochs=250,
+        verbose=0,
+        callbacks=cb,
+    )
+
+    y_hat_s = model.predict(xte_in, verbose=0).reshape(-1, 1)
+    y_hat = y_scaler.inverse_transform(y_hat_s).reshape(-1)
+
+    return {
+        "seed": int(seed),
+        "r2": float(r2_score(y_te, y_hat)),
+        "mae": float(mean_absolute_error(y_te, y_hat)),
+        "epochs": int(len(hist.history.get("loss", []))),
+        "best_val_loss": float(np.min(hist.history.get("val_loss", [np.nan]))),
+    }
+
+
+def summarize(rows: List[Dict]) -> Dict:
+    r2 = np.array([r["r2"] for r in rows], dtype=np.float64)
+    mae = np.array([r["mae"] for r in rows], dtype=np.float64)
+    return {
+        "r2_mean": float(np.mean(r2)),
+        "r2_std": float(np.std(r2)),
+        "mae_mean": float(np.mean(mae)),
+        "mae_std": float(np.std(mae)),
+    }
+
+
+def main() -> None:
+    t0 = time.time()
+    device = set_tf_device(1)
+    x, y, decision = load_init_dataset()
+
+    specs = [
+        ModelSpec(name="mlp_128_64_32", kind="mlp"),
+        ModelSpec(name="cnn_paper_like", kind="cnn"),
+    ]
+    seeds = [0, 1, 2, 3, 4]
+
+    results = {}
+    for spec in specs:
+        rows = [run_one_split(x, y, s, spec) for s in seeds]
+        results[spec.name] = {
+            "kind": spec.kind,
+            "per_split": rows,
+            "summary": summarize(rows),
+        }
+
+    r2_mlp = results["mlp_128_64_32"]["summary"]["r2_mean"]
+    r2_cnn = results["cnn_paper_like"]["summary"]["r2_mean"]
+
+    out = {
+        "db_path": DB_PATH,
+        "decision_path": DECISION_PATH,
+        "device": device,
+        "n_init": int(len(x)),
+        "dims": int(x.shape[1]),
+        "y_stats": {
+            "mean": float(np.mean(y)),
+            "std": float(np.std(y)),
+            "min": float(np.min(y)),
+            "max": float(np.max(y)),
+        },
+        "models": results,
+        "delta": {
+            "r2_cnn_minus_mlp": float(r2_cnn - r2_mlp),
+            "better_model": "cnn_paper_like" if r2_cnn > r2_mlp else "mlp_128_64_32",
+        },
+        "elapsed_sec": float(time.time() - t0),
+    }
+
+    out_json = os.path.join(OUT_DIR, "v6_1_init_surrogate_mlp_vs_cnn.json")
+    with open(out_json, "w", encoding="utf-8") as f:
+        json.dump(out, f, ensure_ascii=False, indent=2)
+
+    print("saved", out_json)
+    print("better_model", out["delta"]["better_model"]) 
+    print("delta_r2", out["delta"]["r2_cnn_minus_mlp"])
+
+
+if __name__ == "__main__":
+    main()

archive/dante_pinball/dante_pinball/legacy/v6_v7_pca_distance_with_ppo.py

@@ -0,0 +1,318 @@
+import json
+import os
+from dataclasses import dataclass
+from typing import Dict, List, Tuple
+
+import matplotlib.pyplot as plt
+import numpy as np
+from sklearn.decomposition import PCA
+from sklearn.preprocessing import StandardScaler
+
+ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir))
+OUT_DIR = os.path.join(ROOT, "output", "report_dante_v2_v5_v6")
+os.makedirs(OUT_DIR, exist_ok=True)
+
+SEEDS = [11, 29, 47]
+
+V6_NAME = "d1a3o12_250421_forces02_dante_v6_2"
+V7_NAME = "d1a3o12_250421_forces02_dante_v7"
+
+
+@dataclass
+class RunData:
+    name: str
+    x: np.ndarray
+    y: np.ndarray
+    num_initial: int
+    dims: int
+    cfg: Dict
+
+
+def load_run(name: str) -> RunData:
+    db_path = os.path.join(ROOT, "output", f"{name}_database_live.npz")
+    cfg_path = os.path.join(ROOT, "output", f"{name}_structure_decision.json")
+
+    z = np.load(db_path, allow_pickle=True)
+    x = np.asarray(z["input_x"], dtype=np.float64)
+    y = np.asarray(z["input_y"], dtype=np.float64)
+    cfg = json.load(open(cfg_path, "r", encoding="utf-8"))
+
+    return RunData(
+        name=name,
+        x=x,
+        y=y,
+        num_initial=int(cfg["num_initial"]),
+        dims=int(cfg["controller_dims"]),
+        cfg=cfg,
+    )
+
+
+def feature_dict(obs_t: np.ndarray, obs_prev: np.ndarray, act_prev: np.ndarray) -> Dict[str, float]:
+    o0, o1 = float(obs_t[0]), float(obs_t[1])
+    p0, p1 = float(obs_prev[0]), float(obs_prev[1])
+    a0, a1, a2 = float(act_prev[0]), float(act_prev[1]), float(act_prev[2])
+    return {
+        "obs0": o0,
+        "obs1": o1,
+        "dobs0": o0 - p0,
+        "dobs1": o1 - p1,
+        "sin_obs0": float(np.sin(np.pi * o0)),
+        "sin_obs1": float(np.sin(np.pi * o1)),
+        "cos_obs0": float(np.cos(np.pi * o0)),
+        "cos_obs1": float(np.cos(np.pi * o1)),
+        "tanh_obs0": float(np.tanh(o0)),
+        "tanh_obs1": float(np.tanh(o1)),
+        "act0_l1": a0,
+        "act1_l1": a1,
+        "act2_l1": a2,
+    }
+
+
+def inv_tanh_map(q: float) -> float:
+    qq = float(np.clip(q, -0.999, 0.999))
+    x = np.arctanh(qq) / 1.25
+    return float(np.clip(x, -1.0, 1.0))
+
+
+def ppo_point_for_v6(seed: int, basis_terms: List[str]) -> np.ndarray:
+    p = os.path.join(ROOT, "output", "report_dante_v2_v5_v6", f"raw_oldenv_seed_{seed}.npz")
+    z = np.load(p)
+    obs = np.asarray(z["ppo_obs"], dtype=np.float64)
+    act = np.asarray(z["ppo_actions"], dtype=np.float64)
+
+    rows_x = []
+    rows_y = []
+    for t in range(1, len(obs)):
+        fd = feature_dict(obs[t], obs[t - 1], act[t - 1])
+        row = [1.0] + [float(fd[k]) for k in basis_terms]
+        rows_x.append(row)
+        rows_y.append(act[t])
+
+    X = np.asarray(rows_x, dtype=np.float64)
+    Y = np.asarray(rows_y, dtype=np.float64)
+
+    params = []
+    for ch in range(3):
+        coef, *_ = np.linalg.lstsq(X, Y[:, ch], rcond=None)
+        bias = float(coef[0])
+        params.append(inv_tanh_map(bias / 1.0))
+        for c in coef[1:]:
+            params.append(inv_tanh_map(float(c) / 2.0))
+
+    return np.asarray(params, dtype=np.float64)
+
+
+def phase_weights(phase: float, k: int) -> np.ndarray:
+    z = float(np.mod(phase, 1.0)) * k
+    i0 = int(np.floor(z)) % k
+    frac = float(z - np.floor(z))
+    i1 = (i0 + 1) % k
+    w = np.zeros(k, dtype=np.float64)
+    w[i0] += (1.0 - frac)
+    w[i1] += frac
+    return w
+
+
+def ppo_point_for_v7(seed: int, k: int, period_steps: float) -> np.ndarray:
+    p = os.path.join(ROOT, "output", "report_dante_v2_v5_v6", f"raw_oldenv_seed_{seed}.npz")
+    z = np.load(p)
+    act = np.asarray(z["ppo_actions"], dtype=np.float64)
+
+    n = int(act.shape[0])
+    phase = 0.0
+    step_phase = 1.0 / max(1e-6, float(period_steps))
+
+    W = np.zeros((n, k), dtype=np.float64)
+    for t in range(n):
+        W[t] = phase_weights(phase, k)
+        phase = (phase + step_phase) % 1.0
+
+    params = []
+    for ch in range(3):
+        coef, *_ = np.linalg.lstsq(W, act[:, ch], rcond=None)
+        coef = np.clip(coef, -1.0, 1.0)
+        params.extend(coef.tolist())
+
+    return np.asarray(params, dtype=np.float64)
+
+
+def fit_pca_and_project(x: np.ndarray, extra: np.ndarray) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+    scaler = StandardScaler()
+    xs = scaler.fit_transform(x)
+    extra_s = scaler.transform(extra)
+
+    pca = PCA(n_components=2, random_state=0)
+    x2 = pca.fit_transform(xs)
+    extra2 = pca.transform(extra_s)
+    return x2, extra2, pca.explained_variance_ratio_
+
+
+def distance_metrics(x: np.ndarray, y: np.ndarray, ppo_points: np.ndarray, n0: int) -> Dict:
+    centroid = np.mean(ppo_points, axis=0)
+    d = np.linalg.norm(x - centroid.reshape(1, -1), axis=1)
+
+    n = len(d)
+    xx = np.arange(n, dtype=np.float64)
+    slope = float(np.polyfit(xx, d, deg=1)[0]) if n >= 2 else 0.0
+
+    init_mean = float(np.mean(d[:n0])) if n0 > 0 else float(np.mean(d))
+    late_mean = float(np.mean(d[n0:])) if n > n0 else init_mean
+
+    thr = np.quantile(y, 0.9)
+    idx_hi = np.where(y >= thr)[0]
+    hi_mean = float(np.mean(d[idx_hi])) if len(idx_hi) > 0 else float("nan")
+
+    return {
+        "init_mean": init_mean,
+        "late_mean": late_mean,
+        "late_minus_init": float(late_mean - init_mean),
+        "slope": slope,
+        "high_reward_dist_mean": hi_mean,
+        "overall_dist_mean": float(np.mean(d)),
+        "distance": d.tolist(),
+        "ppo_centroid": centroid.tolist(),
+    }
+
+
+def plot_pca(
+    run_name: str,
+    x2: np.ndarray,
+    y: np.ndarray,
+    ppo2: np.ndarray,
+    evr: np.ndarray,
+    out_png: str,
+) -> None:
+    plt.figure(figsize=(8, 6))
+    sc = plt.scatter(x2[:, 0], x2[:, 1], c=y, cmap="viridis", s=12, alpha=0.75)
+    plt.colorbar(sc, label="reward_scaled")
+
+    colors = ["#e41a1c", "#377eb8", "#ff7f00"]
+    for i, seed in enumerate(SEEDS):
+        plt.scatter(
+            [ppo2[i, 0]],
+            [ppo2[i, 1]],
+            s=120,
+            c=colors[i],
+            marker="*",
+            edgecolors="k",
+            linewidths=0.9,
+            label=f"PPO seed {seed}",
+            zorder=6,
+        )
+
+    plt.title(
+        f"{run_name} PCA with PPO points\\n"
+        f"PC1 {evr[0]*100:.1f}% | PC2 {evr[1]*100:.1f}%"
+    )
+    plt.xlabel("PC1")
+    plt.ylabel("PC2")
+    plt.legend(loc="best", fontsize=9)
+    plt.grid(alpha=0.25)
+    plt.tight_layout()
+    plt.savefig(out_png, dpi=170)
+    plt.close()
+
+
+def plot_distance_curve(run_name: str, d: np.ndarray, n0: int, out_png: str) -> None:
+    n = len(d)
+    x = np.arange(1, n + 1)
+    plt.figure(figsize=(9, 4.8))
+    plt.plot(x, d, lw=1.4, color="#1f77b4")
+    plt.axvline(n0, color="k", ls="--", lw=1.0, label=f"init end @ {n0}")
+    plt.title(f"{run_name}: distance to PPO centroid")
+    plt.xlabel("sample order")
+    plt.ylabel("L2 distance")
+    plt.grid(alpha=0.25)
+    plt.legend(loc="best")
+    plt.tight_layout()
+    plt.savefig(out_png, dpi=170)
+    plt.close()
+
+
+def diagnose(run_name: str, m: Dict) -> Dict:
+    outward = bool(m["late_minus_init"] > 0.0 and m["slope"] > 0.0)
+    high_reward_near = bool(m["high_reward_dist_mean"] < m["overall_dist_mean"])
+
+    return {
+        "run": run_name,
+        "outward_sampling_still_exists": outward,
+        "high_reward_closer_to_ppo_than_overall": high_reward_near,
+        "metrics": {
+            "late_minus_init": float(m["late_minus_init"]),
+            "slope": float(m["slope"]),
+            "high_reward_dist_mean": float(m["high_reward_dist_mean"]),
+            "overall_dist_mean": float(m["overall_dist_mean"]),
+        },
+    }
+
+
+def main() -> None:
+    v6 = load_run(V6_NAME)
+    v7 = load_run(V7_NAME)
+
+    basis_terms = list(v6.cfg["basis_terms"])
+    v6_ppo = np.vstack([ppo_point_for_v6(s, basis_terms) for s in SEEDS])
+
+    k = int(v7.cfg["control_points_per_channel"])
+    period_steps = float(v7.cfg["period_steps"])
+    v7_ppo = np.vstack([ppo_point_for_v7(s, k=k, period_steps=period_steps) for s in SEEDS])
+
+    v6_x2, v6_ppo2, v6_evr = fit_pca_and_project(v6.x, v6_ppo)
+    v7_x2, v7_ppo2, v7_evr = fit_pca_and_project(v7.x, v7_ppo)
+
+    v6_m = distance_metrics(v6.x, v6.y, v6_ppo, v6.num_initial)
+    v7_m = distance_metrics(v7.x, v7.y, v7_ppo, v7.num_initial)
+
+    p_v6_pca = os.path.join(OUT_DIR, "v6_2_pca_with_ppo_points.png")
+    p_v7_pca = os.path.join(OUT_DIR, "v7_pca_with_ppo_points.png")
+    p_v6_dist = os.path.join(OUT_DIR, "v6_2_distance_order_vs_ppo_centroid.png")
+    p_v7_dist = os.path.join(OUT_DIR, "v7_distance_order_vs_ppo_centroid.png")
+
+    plot_pca(v6.name, v6_x2, v6.y, v6_ppo2, v6_evr, p_v6_pca)
+    plot_pca(v7.name, v7_x2, v7.y, v7_ppo2, v7_evr, p_v7_pca)
+    plot_distance_curve(v6.name, np.asarray(v6_m["distance"]), v6.num_initial, p_v6_dist)
+    plot_distance_curve(v7.name, np.asarray(v7_m["distance"]), v7.num_initial, p_v7_dist)
+
+    summary = {
+        "v6": {
+            "name": v6.name,
+            "dims": int(v6.dims),
+            "num_samples": int(len(v6.y)),
+            "num_initial": int(v6.num_initial),
+            "best_reward": float(np.max(v6.y) / 100.0),
+            "distance_metrics": {k: v for k, v in v6_m.items() if k != "distance"},
+            "diagnosis": diagnose(v6.name, v6_m),
+        },
+        "v7": {
+            "name": v7.name,
+            "dims": int(v7.dims),
+            "num_samples": int(len(v7.y)),
+            "num_initial": int(v7.num_initial),
+            "best_reward": float(np.max(v7.y) / 100.0),
+            "period_steps": period_steps,
+            "distance_metrics": {k: v for k, v in v7_m.items() if k != "distance"},
+            "diagnosis": diagnose(v7.name, v7_m),
+        },
+        "figures": {
+            "v6_pca": p_v6_pca,
+            "v6_distance": p_v6_dist,
+            "v7_pca": p_v7_pca,
+            "v7_distance": p_v7_dist,
+        },
+    }
+
+    out_json = os.path.join(OUT_DIR, "v6_v7_pca_distance_with_ppo_summary.json")
+    with open(out_json, "w", encoding="utf-8") as f:
+        json.dump(summary, f, indent=2, ensure_ascii=False)
+
+    print("saved", out_json)
+    print(json.dumps({
+        "v6_late_minus_init": summary["v6"]["distance_metrics"]["late_minus_init"],
+        "v6_slope": summary["v6"]["distance_metrics"]["slope"],
+        "v7_late_minus_init": summary["v7"]["distance_metrics"]["late_minus_init"],
+        "v7_slope": summary["v7"]["distance_metrics"]["slope"],
+    }, indent=2, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()

archive/dante_pinball/dante_pinball/legacy/v6_v7_ppo_briefing_20260324.md

@@ -0,0 +1,39 @@
+# v6/v7/PPO 综合简报
+
+## 1) PCA（含3个PPO拟合点）
+- v6图: /home/frank14f/Frank_LBM/output/report_dante_v2_v5_v6/brief_v6_3_pca_with_ppo3.png
+- v7图: /home/frank14f/Frank_LBM/output/report_dante_v2_v5_v6/brief_v7_1_pca_with_ppo3.png
+
+## 2) obs-act时序 + 最终涡量
+- 时序图: /home/frank14f/Frank_LBM/output/report_dante_v2_v5_v6/brief_v6_v7_ppo_obs_act_time.png
+- 最终涡量图: /home/frank14f/Frank_LBM/output/report_dante_v2_v5_v6/brief_v6_v7_ppo_final_vorticity.png
+- 涡量统一色条范围: ±0.003432（按三者全局|omega|max的10%）
+- PPO时序选用seed=11（tail100=0.53995）
+
+## 3) 函数约简、关键函数、最终组合
+- 全特征模型平均R2: 0.955101
+- 约束搜索best_chrono基函数: ['obs1', 'sin_obs0', 'cos_obs0', 'act1_l1']
+- best_chrono平均R2: 0.957993
+- best_chrono最差seed R2: 0.948454
+- 关键函数解释: obs1给出主状态幅值，sin/cos(pi*obs0)提供周期相位，act1_l1提供单步记忆。
+
+### 学到方程与拟合方程（LaTeX）
+- 全特征学到方程（3动作联合线性写法）:
+$$\mathbf{a}_t = W_{full}\,\phi_{full,t}$$
+$$\phi_{full}=[1,obs_0,obs_1,\Delta obs_0,\Delta obs_1,\sin(\pi obs_0),\sin(\pi obs_1),\cos(\pi obs_0),\cos(\pi obs_1),\tanh(obs_0),\tanh(obs_1),a_{0,t-1},a_{1,t-1},a_{2,t-1}]^\top$$
+$$W_{full}=\begin{bmatrix}0.1571 & 1613.4234 & 127.6118 & -0.0178 & -0.0231 & 132.0173 & 10.3495 & -0.1619 & -0.0087 & -2028.1743 & -159.3687 & -0.0094 & 0.0129 & 0.0130 \\ 0.0229 & 6369.5027 & -875.1549 & 0.0028 & 0.0395 & 516.7321 & -71.4089 & -0.0922 & -0.0001 & -7993.1110 & 1099.0137 & 0.0506 & -0.0346 & 0.0110 \\ 0.0565 & -1065.8604 & 421.0853 & 0.0500 & -0.0717 & -86.0829 & 34.4277 & -0.0099 & 0.0210 & 1336.5921 & -529.4751 & -0.0876 & 0.0107 & 0.0159\end{bmatrix}$$
+- 全特征拟合R2(本次重算, action均值): 0.962039
+
+- 约简拟合方程（best_chrono）:
+$$\mathbf{a}_t = W_{red}\,\phi_{red,t}$$
+$$\phi_{red}=[1,obs_1,\sin(\pi obs_0),\cos(\pi obs_0),a_{1,t-1}]^\top$$
+$$W_{red}=\begin{bmatrix}-0.0131 & 0.7323 & 0.0014 & 0.0008 & -0.0115 \\ -0.0128 & -0.3989 & -0.0799 & -0.0552 & -0.0168 \\ 0.0312 & -0.3286 & 0.0996 & 0.0348 & 0.0018\end{bmatrix}$$
+- 约简拟合R2(本次重算, action均值): 0.960987
+
+## 4) 高维能力与现实约束反思
+- 高维扫描样本数: 6
+- holdout_r2<0 的case数: 6/6
+- 首轮acq_gain<0 的case数: 6/6
+- 解释: 高维下代理可辨识度不足时，Tree探索会被误导，出现边界漂移与收益停滞。
+- 与论文对齐: DANTE强调DNN surrogate与自适应探索协同；在你的流体控制里，受噪声、时序漂移和高维参数化耦合影响，样本效率会显著下降。
+- 双代理是否有帮助: 当前日志显示ensemble路径提供了可运行冗余（CNN失败时MLP兜底），但在v6_3其val_r2均值仍偏低，收益主要体现在稳定性而非显著提升最优值。

archive/dante_pinball/dante_pinball/legacy/v6_v7_reaudit_from_scratch_20260323.md

@@ -0,0 +1,434 @@
+# v6/v7 Zero-Base Re-Audit (2026-03-23)
+
+## 1) User Goal (frozen)
+
+- Core objective: use DANTE to solve a CFD control problem under expensive evaluations.
+- Key transformation: convert control policy search into low-sample parameter optimization.
+- Practical constraints:
+  - one run is very expensive (about one day), so no destructive trial-and-error on running jobs;
+  - surrogate must be trainable from small initial database;
+  - acquisition should discover high-reward basin instead of drifting to easy-to-fit boundary regions.
+
+## 2) Paper-to-Task Mapping (DANTE original intent)
+
+From `DANTE/paper/s43588-025-00858-x.md`:
+
+- DANTE is designed for non-cumulative objective optimization with limited data.
+- Key mechanisms are:
+  - DUCB exploration term based on visit counts and surrogate value;
+  - conditional selection (avoid value deterioration);
+  - local backpropagation of visits;
+  - adaptive exploration scaling;
+  - top-visit + high-score mixed sampling.
+- Paper also emphasizes DNN surrogate expressivity as a key success factor.
+- For control tasks (paper lunar landing case), conversion is done by fixing initial condition and optimizing pre-designed action parameterization.
+
+Interpretation for this project:
+
+- the controller parameterization quality is first-order (decides landscape smoothness and identifiability);
+- surrogate quality under small data is second-order but still critical;
+- if parameterization induces heavy truncation/failure regions, DANTE will tend to exploit boundary patterns and stall locally.
+
+## 3) Original DANTE Code Baseline (reference behavior)
+
+From `DANTE/dante/tree_exploration.py`:
+
+- Tree expansion mutates one or multiple dimensions with discrete step `turn`.
+- Choose step uses UCB-like criterion with `value + exploration_weight * sqrt(logN/(n+1))`.
+- Conditional selection exists: continue with root unless child UCB exceeds root.
+- Local backpropagation is implemented as local visit count update (`self.N[path] += 1`).
+- Candidate set mixes:
+  - most visited nodes,
+  - top predicted nodes,
+  - random nodes.
+
+From `DANTE/dante/neural_surrogate.py`:
+
+- Surrogate design is deep Conv1D-heavy, matching paper claim.
+
+Important baseline implication:
+
+- DANTE search quality assumes surrogate can provide stable relative ranking.
+- If surrogate fitting is unstable/biased, UCB dynamics may push toward artificial easy zones (often boundaries).
+
+## 4) v6/v7 Parameterization Audit
+
+### v6 (closed-loop basis controller)
+
+From `scripts/d1a3o12_250421_dante_v6.py`:
+
+- parameterization: per-action bias + basis coefficients (compact basis profile), total dims = 18 in current run;
+- controller includes derivative and one-step action history terms (`dobs*`, `act*_l1`), introducing piecewise/non-smooth response wrt parameters;
+- candidate evaluation uses hard reset and truncation-aware fallback;
+- invalid sample (`failure_code != 0`) is not added to training set.
+
+Potential risk:
+
+- derivative/history terms can create sensitive local discontinuities under rollout + truncation, making small-data surrogate fitting harder.
+
+### v7 (open-loop periodic)
+
+From `scripts/d1a3o12_250421_dante_v7_openloop.py`:
+
+- parameterization: direct periodic control points, dims = 24 (3 channels * 8 control points), optional period parameter;
+- non-integer period supported via continuous phase accumulation;
+- period initialized from PPO data FFT median (`period_steps ~= 15.789` currently).
+
+Expected advantage:
+
+- objective wrt parameters is smoother than closed-loop derivative/history mapping;
+- better surrogate learnability under limited data.
+
+## 5) Live Evidence From Current Runs
+
+Data extracted from:
+
+- `output/d1a3o12_250421_forces02_dante_v6_3_database_live.npz`
+- `output/d1a3o12_250421_forces02_dante_v6_3_dante_log.csv`
+- `output/d1a3o12_250421_forces02_dante_v7_1_database_live.npz`
+- `output/d1a3o12_250421_forces02_dante_v7_1_dante_log.csv`
+- runtime logs: `scripts/nohup_dante_v6.out`, `scripts/nohup_dante_v7.out`
+
+### 5.1 Boundary drift (major)
+
+v6_3:
+
+- init boundary ratio `|x|>=0.95`: 0.0744
+- acquired boundary ratio `|x|>=0.95`: 0.5342
+- init exact boundary `|x|==1`: 0.0225
+- acquired exact boundary `|x|==1`: 0.5010
+
+v7_1:
+
+- init boundary ratio `|x|>=0.95`: 0.0727
+- acquired boundary ratio `|x|>=0.95`: 0.4485
+- init exact boundary `|x|==1`: 0.0247
+- acquired exact boundary `|x|==1`: 0.4293
+
+Conclusion:
+
+- both v6 and v7 still show strong boundary-seeking collapse;
+- v7 is better than v6 but problem remains.
+
+### 5.2 Initial database learnability vs later acq
+
+v6_3:
+
+- init scaled reward mean/max: 13.2496 / 29.3712
+- acquired scaled reward mean/max: 14.4590 / 25.3012
+
+Interpretation:
+
+- acquisition improves mean a little, but fails to exceed init max;
+- indicates poor exploration of true high-reward basin (or surrogate ranking mismatch).
+
+v7_1:
+
+- init scaled reward mean/max: 17.4189 / 33.5647
+- acquired scaled reward mean/max: 19.2403 / 36.9052
+
+Interpretation:
+
+- v7 acquisition can surpass init max, consistent with smoother parameterization.
+
+### 5.3 Invalid/truncation pressure
+
+v6_3:
+
+- invalid ratio in dante_log: 0.3626 (194 / 535)
+
+v7_1:
+
+- invalid ratio in dante_log: 0.0 (0 / 401)
+
+Interpretation:
+
+- v6 landscape is heavily constrained by invalid regions, harming surrogate data quality;
+- v7 reduces this burden substantially.
+
+### 5.4 Surrogate quality and cuDNN symptom
+
+v6 log (`nohup_dante_v6.out`):
+
+- repeated `surrogate cnn failed: cuDNN ...`;
+- val_r2 stats: mean -0.3763, max 0.0820, min -1.9995.
+
+v7 log (`nohup_dante_v7.out`):
+
+- repeated cnn fail still present;
+- selected architecture mostly `mlp`;
+- val_r2 stats: mean 0.0790, max 0.3766, min -0.2300.
+
+Interpretation:
+
+- v6 fitting is notably weak;
+- v7 fitting is better but still fragile;
+- cnn failure currently forces implicit fallback behavior and noisy model-selection dynamics.
+
+## 6) Root-Cause Stack (ordered)
+
+### RC-1: Parameterization-induced landscape hardness (primary)
+
+- v6 closed-loop basis with derivative/history terms + truncation recovery introduces high local nonlinearity and effective discontinuities.
+- This directly raises surrogate fitting difficulty from small initial data.
+
+### RC-2: Search distribution collapse to boundaries (primary)
+
+- acquisition increasingly samples boundary points where surrogate/DUCB can maintain confidence but true objective improvement is limited.
+- consistent with "easy-to-fit but locally suboptimal" phenomenon described by user.
+
+### RC-3: Surrogate architecture instability on this runtime (secondary but severe)
+
+- CNN path repeatedly fails in runtime logs (`CUDNN_STATUS_MAPPING_ERROR`), creating inconsistent ensemble behavior.
+
+### RC-4: DANTE defaults not retuned for this control manifold (secondary)
+
+- current `TreeExploration` defaults (`ratio`, `num_list`, rollout schedule) are inherited from generic synthetic settings;
+- not yet adapted to constrained CFD control manifold where invalid-region pressure is high.
+
+## 7) Gap vs Paper Design (why drift happens)
+
+- Paper success assumes expressive and stable DNN surrogate; current runtime repeatedly disables CNN branch in practice.
+- Paper uses adaptive exploration with data-driven scaling; current runs mostly use fixed defaults, lacking targeted anti-collapse constraints.
+- Paper top-visit sampling helps diversity; but when candidate generation is already boundary-dominated, top-visit can reinforce collapse.
+
+This is not a contradiction of DANTE; it is a mismatch between:
+
+- control parameterization geometry,
+- runtime surrogate stability,
+- and search hyperparameters calibrated for this geometry.
+
+## 8) Immediate Non-Destructive Plan (no killing running jobs)
+
+1. Continue current jobs untouched; only monitor and collect diagnostics.
+2. Build an offline replay audit from existing `database_live + dante_log`:
+   - per-acq boundary ratio trend,
+   - per-acq surrogate r2 trend,
+   - per-acq invalid ratio trend,
+   - best-so-far progression.
+3. Design v6.1/v7.1 candidates as code patches only (not executed yet):
+   - explicit anti-boundary regularization in candidate filter or score,
+   - tree expansion step schedule tied to valid-region occupancy,
+   - manifold-aware initialization (seed around top PPO + noise, not pure uniform only).
+4. Run tiny dry-run diagnostics on copied DB (no CFD call) to test whether modified acquisition reduces boundary concentration.
+5. Only after user确认, start a new expensive run.
+
+## 9) Frozen Facts (for anti-forget)
+
+- User explicitly disallows interrupting expensive ongoing runs.
+- Main blocker hierarchy:
+  1) initial DB hard to fit,
+  2) best region not reached,
+  3) DANTE drifts to boundaries and gets local-trapped.
+- Core mission is control-to-parameter conversion quality, not just fixing runtime errors.
+
+---
+
+This file is the session source-of-truth for re-audit decisions and will be continuously appended.
+
+## 10) Additional Mismatch Checks (new)
+
+### 10.1 Batch-size mismatch vs paper regime
+
+Paper states small-batch active loop (`batch size <= 20`) for efficient convergence in scarce-data settings.
+
+Current runs:
+
+- v6: `samples_per_acq = 18` (within paper range)
+- v7: `samples_per_acq = 24` (outside paper range)
+
+Risk:
+
+- larger batch can over-commit to one surrogate snapshot and reduce corrective feedback frequency;
+- this can reinforce boundary drift when surrogate ranking is biased.
+
+### 10.2 Exploration hyperparameters are generic defaults
+
+`TreeExploration` is instantiated with default settings, not task-adapted settings:
+
+- fixed `ratio`, fixed `num_list`, fixed rollout schedule;
+- no explicit anti-boundary penalty;
+- no validity-aware expansion constraints.
+
+Risk:
+
+- defaults derived from synthetic objective settings may not transfer to CFD control landscape with truncation boundaries.
+
+### 10.3 Objective uses valid-only dataset update
+
+Current logic drops invalid samples from surrogate training.
+
+Benefit:
+
+- avoids contaminating reward regression with hard-zero artifacts.
+
+Cost:
+
+- surrogate receives no direct supervision of boundary-danger zones;
+- acquisition can repeatedly propose invalid-adjacent points before feedback correction.
+
+### 10.4 PPO-derived period estimate is stable (not a major uncertainty)
+
+From three seeds and three channels, dominant period is consistently `15.789`.
+
+Implication:
+
+- v7 underperformance is not caused by noisy period inference;
+- main issue remains search distribution + surrogate dynamics.
+
+## 11) Parameter-Optimization Reformulation Guidance (for next version design)
+
+The main design question is not "which optimizer" but "which parameter manifold makes reward smooth and identifiable".
+
+### 11.1 v6 closed-loop manifold issue
+
+- derivative/history terms increase temporal expressivity but amplify local ruggedness under truncation.
+- this tends to create disconnected feasible islands, hard for small-data surrogate.
+
+### 11.2 v7 open-loop manifold benefit and limitation
+
+- control-point periodic manifold is smoother and easier to fit;
+- but unconstrained amplitude still allows edge-seeking behavior.
+
+### 11.3 Recommended manifold constraints (code changes pending user approval)
+
+1. Soft amplitude regularization in acquisition score:
+  - add penalty term proportional to boundary occupancy ratio.
+2. Smoothness prior for open-loop waveform:
+  - penalize adjacent control-point jumps (`L2` on first differences).
+3. Feasible-region seeding:
+  - replace pure-uniform init with mixture:
+    - 60% local perturbation around top PPO trajectories,
+    - 40% broad random coverage.
+4. Adaptive batch sizing:
+  - reduce to 12-18 when surrogate `val_r2` is low; restore when stable.
+5. Validity-aware replay buffer for surrogate:
+  - keep a small labeled set of invalids with separate classifier head (or weighted regression mask) to teach boundary avoidance.
+
+## 12) Next-Step Deliverables (without stopping current runs)
+
+1. Generate per-acquisition diagnostics from current live logs:
+  - boundary ratio trend;
+  - invalid ratio trend;
+  - surrogate val_r2 trend;
+  - best-so-far improvement slope.
+2. Draft patch set for v6.1/v7.1 only as code diff (not executed).
+3. Provide a strict pre-run checklist to prevent another full-day failed run.
+
+## 13) Per-Acquisition Trend Audit (new offline diagnostics)
+
+Generated artifacts:
+
+- `output/report_dante_v2_v5_v6/v6_v7_acq_diagnostics_summary_20260323.json`
+- `output/report_dante_v2_v5_v6/d1a3o12_250421_forces02_dante_v6_3_acq_diagnostics.csv`
+- `output/report_dante_v2_v5_v6/d1a3o12_250421_forces02_dante_v6_3_acq_diagnostics.png`
+- `output/report_dante_v2_v5_v6/d1a3o12_250421_forces02_dante_v7_1_acq_diagnostics.csv`
+- `output/report_dante_v2_v5_v6/d1a3o12_250421_forces02_dante_v7_1_acq_diagnostics.png`
+
+### 13.1 v6_3 trend summary
+
+- logged acquisitions: 17
+- mean invalid ratio: 0.4444
+- mean accepted-boundary ratio (`|x|>=0.95`): 0.4902
+- accepted-boundary slope over acquisitions: +0.00278 (still worsening)
+- best reward at acq end: 0.29371179 -> 0.29371179 (no improvement)
+- mean best-gain-per-acq: 0.0
+- surrogate mean val_r2: -0.3763
+
+Interpretation:
+
+- v6 is effectively stalled in exploitation of a non-improving region.
+- surrogate quality remains too weak to provide useful ranking lift.
+- boundary pressure and invalid pressure co-exist and reinforce local trapping.
+
+### 13.2 v7_1 trend summary
+
+- logged acquisitions: 8
+- mean invalid ratio: 0.0
+- mean accepted-boundary ratio (`|x|>=0.95`): 0.4353
+- accepted-boundary slope over acquisitions: -0.0772 (boundary pressure decreasing in current window)
+- best reward at acq end: 0.33564682 -> 0.36905161 (improving)
+- mean best-gain-per-acq: +0.00220
+- surrogate mean val_r2: +0.0790
+
+Interpretation:
+
+- v7 currently shows positive progress and reduced collapse tendency, but absolute boundary occupancy is still high.
+- this confirms parameterization smoothing helps, yet anti-boundary control is still missing.
+
+### 13.3 Differential diagnosis update
+
+Compared with previous section conclusions, new trend evidence strengthens:
+
+1. The main blocker is not only cuDNN/runtime instability; even with fallback, v6 search dynamics are fundamentally unhealthy.
+2. The controller parameterization change (v6 -> v7) directly changes optimization geometry and data efficiency.
+3. Without explicit boundary-aware acquisition shaping, both variants remain vulnerable to local attractors near constraints.
+
+## 14) Patch Blueprint (audit-level, not executed)
+
+### 14.1 v6.1 (closed-loop) minimal-risk changes
+
+1. Replace default basis profile from `compact_deriv_nl` to a smoother profile for first-stage search.
+2. Add acquisition-time boundary penalty (score-level, not objective rewrite):
+  - penalize candidate if high fraction of dimensions satisfy `|x| >= 0.95`.
+3. Add surrogate reliability gate:
+  - if `val_r2 < 0`, reduce effective exploration radius and acquisition batch for next round.
+
+Expected outcome:
+
+- reduce invalid-rate and boundary-collapse speed;
+- restore monotonic best progression possibility.
+
+### 14.2 v7.1 (open-loop) minimal-risk changes
+
+1. Set `samples_per_acq` from 24 to <=20 (paper-consistent low-batch regime).
+2. Add waveform smoothness regularization in candidate scoring:
+  - penalty on first differences of control points for each channel.
+3. Add amplitude soft cap in acquisition ranking to avoid full-range saturation.
+
+Expected outcome:
+
+- preserve current positive trend while reducing residual boundary occupancy.
+
+## 15) Zero-Risk Validation Checklist (before any new 1-day run)
+
+1. Offline replay check on existing DB/log:
+  - boundary ratio in top-ranked candidates should drop vs baseline.
+2. Surrogate holdout check:
+  - `val_r2` distribution should improve or at least not degrade.
+3. Short synthetic call-chain smoke (no CFD heavy run):
+  - no runtime errors in surrogate fit + rollout.
+4. Dry launch first 1-2 acquisitions only, then inspect:
+  - invalid ratio,
+  - boundary ratio,
+  - best gain in acquisition.
+5. Only if above pass, start full-day run.
+
+## 16) Latest Runtime Validation (2026-03-23, non-destructive)
+
+Validation goal:
+
+- verify whether current code path still throws `CUDNN_STATUS_MAPPING_ERROR` during CNN surrogate fit.
+
+Validation method (no long-run, no environment-day run):
+
+1. Confirm no active v6/v7 process.
+2. Use current `scripts/dante_v6_surrogate_torch.py` directly.
+3. Load live DB from:
+  - `output/d1a3o12_250421_forces02_dante_v6_3_database_live.npz`
+  - `output/d1a3o12_250421_forces02_dante_v7_1_database_live.npz`
+4. Run CNN fit + predict on target GPUs:
+  - case A: v6 DB on GPU:1
+  - case B: v7 DB on GPU:0
+
+Observed result:
+
+- case A: PASS, no cuDNN mapping error, `val_r2=0.3204`, `device=GPU:1`.
+- case B: PASS, no cuDNN mapping error, `val_r2=0.5205`, `device=GPU:0`.
+- overall status: `RESULT PASS`.
+
+Important interpretation:
+
+- Historical `nohup` logs still show repeated `surrogate cnn failed ... CUDNN_STATUS_MAPPING_ERROR` because they come from earlier runs.
+- Current surrogate module path can execute CNN fit/predict successfully on GPU in isolated validation.
+- Full conclusion for "problem fully solved" still requires at least one fresh acquisition-stage real run log without this error.

archive/drl_pinball_new_api/cfd/__init__.py

@@ -0,0 +1 @@
+

archive/drl_pinball_new_api/cfd/pinball_env.py

@@ -0,0 +1,371 @@
+# drl_pinball/cfd/pinball_env.py
+"""
+PinballEnv — wraps CelerisLab.Simulation for DRL inference.
+
+This class provides the same telemetry interface as LegacyCelerisLab.FlowField.run(),
+but using the new Simulation API. The key difference is that the new API returns
+N-step cumulative values, while the old API returned per-step averages.
+
+Usage::
+
+    from pinball_env import PinballEnv
+
+    env = PinballEnv(lbm_config, body_config, device_id=0)
+    env.set_cylinders({front_id: 0.0, bottom_id: -0.04, top_id: 0.04})
+    result = env.run_and_read(800)
+    # result['forces'][body_id] = [fx_per_step, fy_per_step]
+    # result['sensors'][body_id] = [ux_per_step, uy_per_step]
+    
+    env.snapshot()
+    env.restore()
+    
+    env.save_field_tecplot("output.dat")
+    env.export_vorticity_png("vorticity.png")
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+from typing import Dict, List, Optional, Tuple, Any
+
+import numpy as np
+import pycuda.driver as cuda
+
+_REPO = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+_SRC = os.path.join(_REPO, "src")
+if _SRC not in sys.path:
+    sys.path.insert(0, _SRC)
+_DEFAULT_LBM = os.path.join(_REPO, "configs", "config_lbm_pinball.json")
+_DEFAULT_BODY = os.path.join(_REPO, "configs", "config_body.json")
+
+# LBM constants
+_CS2 = 1.0 / 3.0  # lattice speed of sound squared
+
+
+class PinballEnv:
+    """High-level wrapper around CelerisLab.Simulation for pinball DRL tasks.
+    
+    Responsibilities:
+    - Create and manage a Simulation instance
+    - Provide run_and_read() that matches old API semantics (per-step averages)
+    - Manage body ids for sensors and cylinders
+    - Support snapshot/restore for checkpointing
+    - Export macroscopic fields
+    
+    Body ID convention (all envs follow this order):
+        sensors[0], sensors[1], sensors[2], [disturbance_cylinder], 
+        front_cylinder, bottom_cylinder, top_cylinder
+    
+    Some scenes (illusion, vortex) omit the disturbance cylinder.
+    """
+    
+    def __init__(
+        self,
+        lbm_config_path: Optional[str] = None,
+        body_config_path: Optional[str] = None,
+        device_id: int = 0,
+        *,
+        viscosity: Optional[float] = None,
+        velocity: Optional[float] = None,
+    ):
+        # Build config with optional physics override
+        if lbm_config_path is None:
+            lbm_config_path = _DEFAULT_LBM
+        if body_config_path is None:
+            body_config_path = _DEFAULT_BODY
+        
+        if viscosity is not None or velocity is not None:
+            # Create a temp config with overridden physics
+            with open(lbm_config_path) as f:
+                cfg = json.load(f)
+            if viscosity is not None:
+                cfg["physics"]["viscosity"] = float(viscosity)
+            if velocity is not None:
+                cfg["physics"]["velocity"] = float(velocity)
+            tmpd = tempfile.mkdtemp(prefix="pinball_env_cfg_")
+            tmp_cfg_path = os.path.join(tmpd, "config_lbm.json")
+            with open(tmp_cfg_path, "w") as f:
+                json.dump(cfg, f, indent=2)
+            lbm_config_path = tmp_cfg_path
+            
+        from CelerisLab import Simulation
+        
+        self.sim = Simulation(
+            lbm_config_path=lbm_config_path,
+            body_config_path=body_config_path,
+            device_id=device_id,
+        )
+        
+        self._velocity = float(velocity) if velocity is not None else 0.01
+        self._device_id = device_id
+        self._stream = cuda.Stream()
+        
+        # Body tracking
+        self._body_ids: Dict[str, List[int]] = {
+            "sensors": [],
+            "cylinders": [],
+            "disturbance": [],
+        }
+        self._body_id_to_name: Dict[int, str] = {}
+        
+    # -------------------------------------------------------------------
+    # Geometry construction
+    # -------------------------------------------------------------------
+    
+    def add_cylinder(self, center: Tuple[float, float], radius: float) -> int:
+        """Add a cylinder body. Returns body_id."""
+        from CelerisLab import Simulation
+        body_id = self.sim.add_body("circle", center=center, radius=radius)
+        self._body_ids["cylinders"].append(body_id)
+        self._body_id_to_name[body_id] = f"cylinder_{len(self._body_ids['cylinders'])}"
+        return body_id
+    
+    def add_sensor(self, center: Tuple[float, float], radius: float) -> int:
+        """Add a sensor body. Returns body_id."""
+        body_id = self.sim.add_body("sensor", center=center, radius=radius)
+        self._body_ids["sensors"].append(body_id)
+        self._body_id_to_name[body_id] = f"sensor_{len(self._body_ids['sensors'])}"
+        return body_id
+    
+    def add_disturbance_cylinder(self, center: Tuple[float, float], radius: float) -> int:
+        """Add a disturbance cylinder (upstream). Returns body_id."""
+        body_id = self.sim.add_body("circle", center=center, radius=radius)
+        self._body_ids["disturbance"].append(body_id)
+        self._body_id_to_name[body_id] = "disturbance"
+        return body_id
+    
+    def reinitialize(self):
+        """Recompile and reinitialize after adding bodies."""
+        self.sim.initialize()
+    
+    # -------------------------------------------------------------------
+    # Runtime control
+    # -------------------------------------------------------------------
+    
+    def set_cylinder_omega(self, body_id: int, omega: float):
+        """Set cylinder rotation speed in lattice units."""
+        self.sim.set_body(body_id, omega=float(omega))
+    
+    def set_cylinders(self, omegas: Dict[int, float]):
+        """Set multiple cylinder omegas at once. {body_id: omega}."""
+        for bid, omega in omegas.items():
+            self.sim.set_body(bid, omega=float(omega))
+    
+    def run_and_read(
+        self,
+        steps: int,
+        omegas: Optional[Dict[int, float]] = None,
+        *,
+        read_fields: bool = False,
+    ) -> Dict[str, Any]:
+        """Run N LBM steps and read telemetry.
+        
+        Parameters
+        ----------
+        steps : int
+            Number of LBM steps to run.
+        omegas : dict, optional
+            Cylinder omegas to set before running. {body_id: omega}
+        read_fields : bool
+            If True, also return macroscopic field.
+        
+        Returns
+        -------
+        dict with:
+            forces : dict {body_id: [fx, fy]} per-step average
+            sensors : dict {body_id: [ux, uy]} per-step average
+            fields : dict (only if read_fields=True)
+        """
+        # Set omegas if provided
+        if omegas is not None:
+            self.set_cylinders(omegas)
+        
+        # Zero GPU telemetry
+        self.sim.bodies.zero_force_segment_async(self._stream)
+        if self.sim.field.n_sensor > 0:
+            self.sim.bodies.zero_sensor_segment_async(self._stream)
+        
+        # Run steps
+        self.sim.stepper.step(
+            int(steps),
+            action_gpu=self.sim.bodies.action_gpu,
+            obs_gpu=self.sim.bodies.obs_gpu,
+            stream=self._stream,
+        )
+        
+        # Download telemetry
+        self.sim.bodies.download_obs_full_async(self._stream)
+        self._stream.synchronize()
+        
+        # Read forces (per-step average)
+        forces = {}
+        for bid in self._body_ids["cylinders"]:
+            f = self.sim.read_force(bid)
+            forces[bid] = (np.array(f, dtype=np.float32) / float(steps)).tolist()
+        
+        for bid in self._body_ids["disturbance"]:
+            f = self.sim.read_force(bid)
+            forces[bid] = (np.array(f, dtype=np.float32) / float(steps)).tolist()
+        
+        # Read sensors (per-step average, raw sum / steps, NO cell count division)
+        sensors = {}
+        for bid in self._body_ids["sensors"]:
+            s = self.sim.read_sensor(bid, normalize=False)
+            sensors[bid] = (np.array(s, dtype=np.float32) / float(steps)).tolist()
+        
+        result = {
+            "forces": forces,
+            "sensors": sensors,
+            "n_steps": int(steps),
+        }
+        
+        if read_fields:
+            macro = self.sim.get_macroscopic()
+            result["fields"] = {
+                "ux": np.asarray(macro["ux"], dtype=np.float32),
+                "uy": np.asarray(macro["uy"], dtype=np.float32),
+                "rho": np.asarray(macro["rho"], dtype=np.float32),
+            }
+        
+        return result
+    
+    def get_sensor_array(self, sensors: Dict[int, list]) -> np.ndarray:
+        """Convert sensor dict to flat array in body_id order: [s0_ux, s0_uy, s1_ux, ...]."""
+        arr = []
+        for bid in sorted(sensors.keys()):
+            arr.extend(sensors[bid])
+        return np.array(arr, dtype=np.float32)
+    
+    def get_force_array(self, forces: Dict[int, list]) -> np.ndarray:
+        """Convert force dict to flat array in cylinder body_id order."""
+        arr = []
+        for bid in self._body_ids["cylinders"]:
+            if bid in forces:
+                arr.extend(forces[bid])
+        for bid in self._body_ids["disturbance"]:
+            if bid in forces:
+                arr.extend(forces[bid])
+        return np.array(arr, dtype=np.float32)
+    
+    def get_force_array_legacy_order(self, forces: Dict[int, list]) -> np.ndarray:
+        """Return forces in legacy obs order: dist_cyl first, then front, bottom, top.
+        
+        This matches the old API's flat obs array layout:
+        [dist_fx, dist_fy, front_fx, front_fy, bottom_fx, bottom_fy, top_fx, top_fy]
+        """
+        arr = []
+        # Disturbance cylinders first
+        for bid in self._body_ids["disturbance"]:
+            if bid in forces:
+                arr.extend(forces[bid])
+        # Then regular cylinders
+        for bid in self._body_ids["cylinders"]:
+            if bid in forces:
+                arr.extend(forces[bid])
+        return np.array(arr, dtype=np.float32)
+    
+    # -------------------------------------------------------------------
+    # Checkpoint / Snapshot
+    # -------------------------------------------------------------------
+    
+    def snapshot(self):
+        """Save in-memory snapshot of current DDF state."""
+        self.sim.snapshot()
+    
+    def restore(self):
+        """Restore from in-memory snapshot."""
+        self.sim.restore()
+    
+    def save_checkpoint(self, path: str):
+        """Save HDF5 checkpoint to disk."""
+        self.sim.save_checkpoint(path)
+    
+    def load_checkpoint(self, path: str):
+        """Load HDF5 checkpoint from disk."""
+        self.sim.load_checkpoint(path)
+    
+    # -------------------------------------------------------------------
+    # Field export
+    # -------------------------------------------------------------------
+    
+    def get_macroscopic(self) -> Dict[str, np.ndarray]:
+        """Download macroscopic field. Returns {rho, ux, uy}."""
+        return self.sim.get_macroscopic()
+    
+    def save_field_tecplot(self, filename: str):
+        """Save current flow field in Tecplot format.
+        
+        Matches the format of old save_field() in legacy envs.
+        """
+        macro = self.get_macroscopic()
+        ux = np.asarray(macro["ux"], dtype=np.float32)
+        uy = np.asarray(macro["uy"], dtype=np.float32)
+        
+        nx, ny = ux.shape
+        u0 = self._velocity
+        
+        with open(filename, "w") as f:
+            f.write('Title= "LBM 2D"\r\n')
+            f.write('VARIABLES= "X","Y","flag","U","V",\r\n')
+            f.write(f"ZONE T= \"BOX\",I= {nx},J= {ny},F=POINT\r\n")
+            for j in range(ny):
+                for i in range(nx):
+                    u_val = ux[i, j] / u0
+                    v_val = uy[i, j] / u0
+                    f.write(f"{i},{j},0,{u_val},{v_val}\r\n")
+    
+    def export_vorticity_png(self, path: str, title: str = ""):
+        """Export vorticity field as PNG."""
+        try:
+            import matplotlib
+            matplotlib.use("Agg")
+            import matplotlib.pyplot as plt
+        except ImportError:
+            return
+        
+        macro = self.get_macroscopic()
+        ux = np.asarray(macro["ux"], dtype=np.float64)
+        uy = np.asarray(macro["uy"], dtype=np.float64)
+        
+        omega = np.gradient(uy, axis=1) - np.gradient(ux, axis=0)
+        
+        abs_o = np.abs(omega[np.isfinite(omega)])
+        vmax = float(np.percentile(abs_o, 99.5)) if abs_o.size > 0 else 1.0
+        if vmax <= 0:
+            vmax = 1.0
+        
+        ny, nx = omega.shape
+        fig, ax = plt.subplots(figsize=(min(18, max(8, nx / 60)), min(10, max(3, ny / 40))))
+        im = ax.imshow(omega, origin="lower", aspect="equal", cmap="RdBu_r",
+                       vmin=-vmax, vmax=vmax, extent=(0, nx - 1, 0, ny - 1))
+        ax.set_xlabel("x (lattice)")
+        ax.set_ylabel("y (lattice)")
+        if title:
+            ax.set_title(title)
+        fig.colorbar(im, ax=ax, fraction=0.046, pad=0.04, label=r"$\omega_z$")
+        fig.tight_layout()
+        fig.savefig(path, dpi=150, bbox_inches="tight")
+        plt.close(fig)
+    
+    # -------------------------------------------------------------------
+    # Cleanup
+    # -------------------------------------------------------------------
+    
+    def close(self):
+        """Release GPU resources."""
+        self.sim.close()
+    
+    def __del__(self):
+        try:
+            self.close()
+        except Exception:
+            pass
+
+
+def _omega_from_nu(nu: float) -> float:
+    """Convert kinematic viscosity to relaxation parameter omega."""
+    cs2 = 1.0 / 3.0
+    return 1.0 / (3.0 * nu / 1.0 + 0.5)

archive/drl_pinball_new_api/scenes/__init__.py

@@ -0,0 +1 @@
+

archive/drl_pinball_new_api/scenes/karman_cloak/__init__.py

@@ -0,0 +1 @@
+

archive/drl_pinball_new_api/scenes/karman_cloak/re100_scene.py

@@ -0,0 +1,536 @@
+# drl_pinball/scenes/karman_cloak/re100_scene.py
+"""
+Karman cloak re100 scene — inference orchestration for the Karman vortex street
+cloaking scenario at code Reynolds number 100 (Re_D=50).
+
+This scene exactly replicates the flow configuration of:
+    env_karman_cloak_standard.py + model d1a3o12_re100
+
+Geometry (in lattice units, L0=20):
+    Disturbance cylinder:  center=(200, CENTER_Y),   radius=20
+    3 sensors:             x=800, y=CENTER_Y + [-40, 0, 40],  radius=5
+    Front pinball:         center=(600, CENTER_Y),           radius=10
+    Bottom pinball:        center=(626, CENTER_Y-15),        radius=10
+    Top pinball:           center=(626, CENTER_Y+15),        radius=10
+
+Usage::
+
+    from scenes.karman_cloak.re100_scene import KarmanRe100Scene
+
+    scene = KarmanRe100Scene(device_id=0)
+    
+    # Record target
+    scene.create_target_env()
+    scene.record_target("output/target.npz")
+    
+    # Build full env with pinball
+    scene.create_full_env()
+    scene.collect_norm("output/norm.json")
+    scene.build_checkpoints("output/")
+    
+    # Inference
+    scene.load_steady("output/checkpoint_steady.h5")
+    results = scene.run_controlled(model, n_steps=200)
+    scene.export_fields("output/fields/", step_indices=[0, 50, 100, 200])
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from collections import deque
+from typing import Any, Dict, List, Optional, Tuple
+
+import numpy as np
+
+# Add src directory to sys.path for package imports
+_REPO = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", "..", ".."))
+_SRC = os.path.join(_REPO, "src")
+if _SRC not in sys.path:
+    sys.path.insert(0, _SRC)
+
+from drl_pinball.cfd.pinball_env import PinballEnv
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+U0 = 0.01
+L0 = 20.0
+SAMPLE_INTERVAL = 800
+FIFO_LEN = 150
+CONV_LEN = 30
+S_DIM = 12
+A_DIM = 3
+ACTION_SCALE = 8.0
+ACTION_BIAS = (0.0, -4.0, 4.0)  # front, bottom, top
+DATA_TYPE = np.float32
+
+# Pinball config for new API
+NEW_LBM_CONFIG = os.path.join(_REPO, "configs", "config_lbm_pinball.json")
+
+
+class KarmanRe100Scene:
+    """Karman cloak re100 scene manager."""
+    
+    def __init__(self, device_id: int = 0, viscosity: float = 0.004):
+        self.device_id = device_id
+        self.viscosity = viscosity
+        self.env: Optional[PinballEnv] = None
+        
+        # Body IDs (set during create_target_env / create_full_env)
+        self.dist_cyl_id: Optional[int] = None
+        self.sensor_ids: List[int] = []
+        self.front_cyl_id: Optional[int] = None
+        self.bottom_cyl_id: Optional[int] = None
+        self.top_cyl_id: Optional[int] = None
+        
+        # Recorded data
+        self.target_states: Optional[np.ndarray] = None
+        self.norm_data: Optional[Dict] = None
+        self.save_states: Optional[np.ndarray] = None
+    
+    def _center_y(self) -> float:
+        """Return the center y of the domain (NY-1)/2 = 255.5."""
+        return 255.5  # (512 - 1) / 2
+    
+    # -------------------------------------------------------------------
+    # Phase 1: Target recording (disturbance cylinder + sensors only)
+    # -------------------------------------------------------------------
+    
+    def create_target_env(self):
+        """Create flow field with disturbance cylinder + 3 sensors (no pinball)."""
+        self.env = PinballEnv(
+            lbm_config_path=NEW_LBM_CONFIG,
+            body_config_path=None,
+            device_id=self.device_id,
+            viscosity=self.viscosity,
+            velocity=U0,
+        )
+        
+        cy = self._center_y()
+        
+        # Disturbance cylinder (upstream)
+        self.dist_cyl_id = self.env.add_disturbance_cylinder(
+            center=(10.0 * L0, cy), radius=L0
+        )
+        
+        # 3 sensors at x=40*L0
+        for y_off in [2.0, 0.0, -2.0]:
+            sid = self.env.add_sensor(
+                center=(40.0 * L0, cy + y_off * L0), radius=L0 / 4.0
+            )
+            self.sensor_ids.append(sid)
+        
+        # Rebuild
+        self.env.reinitialize()
+    
+    def record_target(self, out_dir: str) -> str:
+        """Record target sensor signals (disturbance only, no pinball).
+        
+        Saves to {out_dir}/target.npz and returns the path.
+        """
+        if self.env is None:
+            raise RuntimeError("Call create_target_env() first")
+        
+        os.makedirs(out_dir, exist_ok=True)
+        out_path = os.path.join(out_dir, "target.npz")
+        
+        # Stabilize
+        stabilize_steps = int(4 * 1280 / U0)
+        self.env.run_and_read(stabilize_steps)
+        
+        # Record target
+        target_list = []
+        for _ in range(FIFO_LEN):
+            result = self.env.run_and_read(SAMPLE_INTERVAL)
+            sens_flat = self.env.get_sensor_array(result["sensors"])
+            target_list.append(sens_flat)
+        
+        self.target_states = np.array(target_list, dtype=DATA_TYPE)
+        np.savez(out_path, target_states=self.target_states)
+        return out_path
+    
+    # -------------------------------------------------------------------
+    # Phase 2: Full env (add pinball, compute norm, checkpoint)
+    # -------------------------------------------------------------------
+    
+    def create_full_env(self):
+        """Add pinball cylinders to existing target env (or create from scratch)."""
+        if self.env is None:
+            self.create_target_env()
+        
+        cy = self._center_y()
+        
+        # Front cylinder
+        self.front_cyl_id = self.env.add_cylinder(
+            center=(30.0 * L0, cy), radius=L0 / 2.0
+        )
+        # Bottom cylinder
+        self.bottom_cyl_id = self.env.add_cylinder(
+            center=(31.3 * L0, cy - 0.75 * L0), radius=L0 / 2.0
+        )
+        # Top cylinder
+        self.top_cyl_id = self.env.add_cylinder(
+            center=(31.3 * L0, cy + 0.75 * L0), radius=L0 / 2.0
+        )
+        
+        self.env.reinitialize()
+    
+    def collect_norm(self, out_dir: str) -> Dict:
+        """Compute normalisation factors from zero-action rollout.
+        
+        Saves to {out_dir}/norm.json.
+        Returns the norm dict.
+        """
+        if self.env is None:
+            raise RuntimeError("Call create_full_env() first")
+        
+        os.makedirs(out_dir, exist_ok=True)
+        
+        cylinder_ids = [self.front_cyl_id, self.bottom_cyl_id, self.top_cyl_id]
+        
+        # Stabilize with pinball
+        stabilize_steps = int(4 * 1280 / U0)
+        self.env.run_and_read(stabilize_steps)
+        
+        # Snapshot the steady state
+        self.env.snapshot()
+        
+        # Zero-action rollout for norm
+        fifo = deque(maxlen=FIFO_LEN)
+        for _ in range(FIFO_LEN):
+            result = self.env.run_and_read(SAMPLE_INTERVAL, read_fields=False)
+            
+            # Forces in legacy order: dist, front, bottom, top
+            force_arr = []
+            force_arr.extend(result["forces"].get(self.dist_cyl_id, [0, 0]))
+            for cid in cylinder_ids:
+                force_arr.extend(result["forces"].get(cid, [0, 0]))
+            
+            sensors_flat = self.env.get_sensor_array(result["sensors"])
+            obs_flat = np.concatenate([sensors_flat, np.array(force_arr, dtype=np.float32)])
+            fifo.append(obs_flat)
+        
+        # Compute norm from fifo
+        temp_states = np.array(fifo, dtype=DATA_TYPE)
+        force_norm_fact = 6.0 * float(np.max(np.abs(temp_states[:, 6:12])))
+        sens_deviation = np.mean(temp_states[:, 0:6], axis=0)
+        sens_norm_fact = np.zeros(6, dtype=DATA_TYPE)
+        for i in range(6):
+            sens_norm_fact[i] = 5.0 * float(np.max(np.abs(temp_states[:, i] - sens_deviation[i])))
+        
+        self.norm_data = {
+            "force_norm_fact": force_norm_fact,
+            "sens_deviation": sens_deviation.tolist(),
+            "sens_norm_fact": sens_norm_fact.tolist(),
+            "action_bias": list(ACTION_BIAS),
+            "action_scale": ACTION_SCALE,
+        }
+        
+        with open(os.path.join(out_dir, "norm.json"), "w") as f:
+            json.dump(self.norm_data, f, indent=2)
+        
+        # Bias-action rollout for save_states
+        self.env.restore()
+        bias_omegas = {
+            self.front_cyl_id: float(ACTION_BIAS[0] * U0),
+            self.bottom_cyl_id: float(ACTION_BIAS[1] * U0),
+            self.top_cyl_id: float(ACTION_BIAS[2] * U0),
+        }
+        
+        fifo.clear()
+        for _ in range(FIFO_LEN):
+            result = self.env.run_and_read(SAMPLE_INTERVAL, omegas=bias_omegas)
+            
+            force_arr = []
+            force_arr.extend(result["forces"].get(self.dist_cyl_id, [0, 0]))
+            for cid in cylinder_ids:
+                force_arr.extend(result["forces"].get(cid, [0, 0]))
+            
+            sensors_flat = self.env.get_sensor_array(result["sensors"])
+            obs_flat = np.concatenate([sensors_flat, np.array(force_arr, dtype=np.float32)])
+            fifo.append(obs_flat)
+        
+        self.save_states = np.array(fifo, dtype=DATA_TYPE)
+        np.savez(os.path.join(out_dir, "save_states.npz"), save_states=self.save_states)
+        
+        # Save norm data as NPZ for easy loading
+        np.savez(
+            os.path.join(out_dir, "norm_data.npz"),
+            force_norm_fact=np.array([force_norm_fact], dtype=np.float32),
+            sens_deviation=np.array(sens_deviation, dtype=np.float32),
+            sens_norm_fact=np.array(sens_norm_fact, dtype=np.float32),
+        )
+        
+        # Restore steady state
+        self.env.restore()
+        
+        return self.norm_data
+    
+    def build_checkpoints(self, out_dir: str):
+        """Save steady-state and bias-state checkpoints."""
+        os.makedirs(out_dir, exist_ok=True)
+        
+        # Steady state (already snapshot'd in collect_norm)
+        self.env.snapshot()
+        steady_path = os.path.join(out_dir, "checkpoint_steady.h5")
+        self.env.save_checkpoint(steady_path)
+        
+        # Bias state: restore + run bias + save
+        self.env.restore()
+        cylinder_ids = [self.front_cyl_id, self.bottom_cyl_id, self.top_cyl_id]
+        bias_omegas = {
+            self.front_cyl_id: float(ACTION_BIAS[0] * U0),
+            self.bottom_cyl_id: float(ACTION_BIAS[1] * U0),
+            self.top_cyl_id: float(ACTION_BIAS[2] * U0),
+        }
+        self.env.run_and_read(SAMPLE_INTERVAL * 10, omegas=bias_omegas)
+        bias_path = os.path.join(out_dir, "checkpoint_bias.h5")
+        self.env.save_checkpoint(bias_path)
+        
+        # Restore steady
+        self.env.restore()
+    
+    # -------------------------------------------------------------------
+    # Inference
+    # -------------------------------------------------------------------
+    
+    def load_checkpoint(self, path: str):
+        """Load from a saved checkpoint."""
+        if self.env is None:
+            raise RuntimeError("Env not created. Call create_full_env() first.")
+        self.env.load_checkpoint(path)
+    
+    def run_uncontrolled(self, n_steps: int, out_dir: str) -> Dict:
+        """Run uncontrolled inference (zero action)."""
+        os.makedirs(out_dir, exist_ok=True)
+        
+        cylinder_ids = [self.front_cyl_id, self.bottom_cyl_id, self.top_cyl_id]
+        
+        sens_list, forc_list = [], []
+        
+        for _ in range(n_steps):
+            result = self.env.run_and_read(SAMPLE_INTERVAL)
+            
+            force_arr = []
+            force_arr.extend(result["forces"].get(self.dist_cyl_id, [0, 0]))
+            for cid in cylinder_ids:
+                force_arr.extend(result["forces"].get(cid, [0, 0]))
+            
+            sensors_flat = self.env.get_sensor_array(result["sensors"])
+            
+            sens_list.append(sensors_flat)
+            forc_list.append(np.array(force_arr, dtype=np.float32))
+        
+        out = {
+            "sensors": np.array(sens_list, dtype=np.float32),
+            "forces": np.array(forc_list, dtype=np.float32),
+        }
+        np.savez(os.path.join(out_dir, "uncontrolled.npz"), **out)
+        
+        # Final vorticity
+        self.env.export_vorticity_png(
+            os.path.join(out_dir, "vorticity_uncontrolled.png"),
+            title="Karman re100 uncontrolled",
+        )
+        
+        return out
+    
+    def run_controlled(
+        self,
+        model: Any,
+        n_steps: int,
+        out_dir: str,
+        *,
+        field_steps: Optional[List[int]] = None,
+    ) -> Dict:
+        """Run controlled inference with a PPO model.
+        
+        Parameters
+        ----------
+        model : PPO
+            Trained PPO model (must have Sin activation).
+        n_steps : int
+            Number of inference steps.
+        out_dir : str
+            Output directory.
+        field_steps : list of int, optional
+            Step indices at which to save Tecplot field files.
+        
+        Returns
+        -------
+        dict with sensors, forces, obs, actions, rewards.
+        """
+        os.makedirs(out_dir, exist_ok=True)
+        if field_steps is not None:
+            os.makedirs(os.path.join(out_dir, "fields"), exist_ok=True)
+        
+        cylinder_ids = [self.front_cyl_id, self.bottom_cyl_id, self.top_cyl_id]
+        cyl_map = {
+            self.front_cyl_id: 0,
+            self.bottom_cyl_id: 1,
+            self.top_cyl_id: 2,
+        }
+        
+        norm = self.norm_data
+        if norm is None:
+            raise RuntimeError("Call collect_norm() first")
+        
+        force_norm_fact = float(norm["force_norm_fact"])
+        sens_deviation = np.array(norm["sens_deviation"], dtype=np.float32)
+        sens_norm_fact = np.array(norm["sens_norm_fact"], dtype=np.float32)
+        
+        # Restore steady state
+        self.env.restore()
+        
+        # Bias FIFO
+        fifo = deque(maxlen=FIFO_LEN)
+        bias_omegas = {
+            self.front_cyl_id: float(ACTION_BIAS[0] * U0),
+            self.bottom_cyl_id: float(ACTION_BIAS[1] * U0),
+            self.top_cyl_id: float(ACTION_BIAS[2] * U0),
+        }
+        
+        for _ in range(FIFO_LEN):
+            result = self.env.run_and_read(SAMPLE_INTERVAL, omegas=bias_omegas)
+            
+            force_arr = []
+            force_arr.extend(result["forces"].get(self.dist_cyl_id, [0, 0]))
+            for cid in cylinder_ids:
+                force_arr.extend(result["forces"].get(cid, [0, 0]))
+            
+            sensors_flat = self.env.get_sensor_array(result["sensors"])
+            obs_flat = np.concatenate([sensors_flat, np.array(force_arr, dtype=np.float32)])
+            fifo.append(obs_flat)
+        
+        sens_list, forc_list, obs_list = [], [], []
+        action_list, reward_list = [], []
+        reward_cd_list, reward_cl_list, reward_sim_list = [], [], []
+        
+        obs = np.zeros(S_DIM, dtype=np.float32)
+        
+        for step in range(n_steps):
+            # PPO action
+            action, _states = model.predict(obs, deterministic=True)
+            action = action.astype(np.float32).flatten()
+            action_list.append(action.copy())
+            
+            # Convert to omegas
+            omegas = {}
+            for i, cid in enumerate(cylinder_ids):
+                omega_val = (action[i] * ACTION_SCALE + ACTION_BIAS[i]) * U0
+                omegas[cid] = float(omega_val)
+            
+            # Run CFD
+            result = self.env.run_and_read(SAMPLE_INTERVAL, omegas=omegas)
+            
+            # Build obs slice
+            force_arr = []
+            force_arr.extend(result["forces"].get(self.dist_cyl_id, [0, 0]))
+            for cid in cylinder_ids:
+                force_arr.extend(result["forces"].get(cid, [0, 0]))
+            
+            sensors_flat = self.env.get_sensor_array(result["sensors"])
+            obs_flat = np.concatenate([sensors_flat, np.array(force_arr, dtype=np.float32)])
+            fifo.append(obs_flat)
+            
+            sens_list.append(sensors_flat)
+            forc_list.append(np.array(force_arr, dtype=np.float32))
+            
+            # Build normalised observation
+            forces_norm = np.array(force_arr[2:], dtype=np.float32) / force_norm_fact  # skip dist cy forces
+            sens_norm = (sensors_flat - sens_deviation) / sens_norm_fact
+            obs = np.clip(np.hstack([forces_norm, sens_norm]), -1.0, 1.0).astype(np.float32)
+            obs_list.append(obs)
+            
+            # Compute reward
+            states_arr = np.array(fifo, dtype=np.float32)
+            if len(states_arr) >= CONV_LEN:
+                forces = states_arr[-1, 6:12] / force_norm_fact
+                cd = float((forces[0] + forces[2] + forces[4]) / 3.0)
+                cl = float((forces[1] + forces[3] + forces[5]) / 3.0)
+                
+                sim = self._compute_similarity(states_arr)
+                
+                r_cd = float(np.exp(-abs(cd * 20.0)))
+                r_cl = float(np.exp(-abs(cl * 80.0)))
+                r_sim = float(np.exp(-10.0 * abs(sim - 1.0)))
+                reward = float(min(0.3 * r_cd + 0.4 * r_cl + 0.3 * r_sim, 1.0))
+            else:
+                reward = 0.0
+                r_cd = r_cl = r_sim = 0.0
+            
+            reward_list.append(reward)
+            reward_cd_list.append(r_cd)
+            reward_cl_list.append(r_cl)
+            reward_sim_list.append(r_sim)
+            
+            # Field export
+            if field_steps is not None and step in field_steps:
+                fname = os.path.join(out_dir, "fields", f"field_{step:06d}.dat")
+                self.env.save_field_tecplot(fname)
+        
+        out = {
+            "sensors": np.array(sens_list, dtype=np.float32),
+            "forces": np.array(forc_list, dtype=np.float32),
+            "obs": np.array(obs_list, dtype=np.float32),
+            "actions": np.array(action_list, dtype=np.float32),
+            "rewards": np.array(reward_list, dtype=np.float32),
+            "reward_cd": np.array(reward_cd_list, dtype=np.float32),
+            "reward_cl": np.array(reward_cl_list, dtype=np.float32),
+            "reward_sim": np.array(reward_sim_list, dtype=np.float32),
+        }
+        np.savez(os.path.join(out_dir, "controlled.npz"), **out)
+        
+        # Final vorticity
+        self.env.export_vorticity_png(
+            os.path.join(out_dir, "vorticity_controlled.png"),
+            title="Karman re100 controlled (PPO)",
+        )
+        
+        return out
+    
+    def _compute_similarity(self, states_arr: np.ndarray) -> float:
+        """Compute lag-compensated DTW similarity (matches legacy env logic)."""
+        if self.target_states is None:
+            return 0.0
+        
+        target = self.target_states
+        
+        # Lag from middle sensor (index 1 = sensor1_uy in sensor[6] block)
+        ref = target[CONV_LEN:2 * CONV_LEN, 1]
+        cur = states_arr[-CONV_LEN:, 1]
+        lag = self._calc_lag(ref, cur)
+        
+        sim_sum = 0.0
+        for i in range(6):
+            t_seq = np.roll(target[:, i], -lag)[CONV_LEN:2 * CONV_LEN]
+            s_seq = states_arr[-CONV_LEN:, i]
+            sim_sum += self._calc_dtw_sim(t_seq, s_seq) / 6.0
+        
+        return float(sim_sum)
+    
+    @staticmethod
+    def _calc_lag(target: np.ndarray, state: np.ndarray) -> int:
+        tm = np.mean(target)
+        sm = np.mean(state)
+        corr = np.correlate(target - tm, state - sm, mode="full")
+        lags = np.arange(-len(target) + 1, len(target))
+        return int(lags[np.argmax(corr)])
+    
+    @staticmethod
+    def _calc_dtw_sim(target: np.ndarray, state: np.ndarray) -> float:
+        n, m = len(target), len(state)
+        dtw = np.full((n + 1, m + 1), np.inf)
+        dtw[0, 0] = 0.0
+        for i in range(1, n + 1):
+            for j in range(1, m + 1):
+                cost = abs(float(target[i - 1]) - float(state[j - 1]))
+                dtw[i, j] = cost + min(dtw[i - 1, j], dtw[i, j - 1], dtw[i - 1, j - 1])
+        return float(1.0 - dtw[n, m] / n)
+    
+    def close(self):
+        if self.env is not None:
+            self.env.close()
+            self.env = None

archive/drl_pinball_new_api/validate/__init__.py

@@ -0,0 +1 @@
+

archive/drl_pinball_new_api/validate/validate_re100.py

@@ -0,0 +1,415 @@
+# drl_pinball/validate/validate_re100.py
+"""
+Validate new CelerisLab API vs LegacyCelerisLab for Karman cloak re100.
+
+This script:
+1. Generates reference data using LegacyCelerisLab (old API)
+2. Generates matching data using new CelerisLab.Simulation API
+3. Compares: target signals, norm values, uncontrolled rollout, controlled rollout
+4. Reports RMSE, max relative error, and correlation for each comparison
+
+Usage::
+
+    conda run -n pycuda_3_10 python validate_re100.py --device 0
+
+    conda run -n pycuda_3_10 python validate_re100.py --device 0 --steps 20 --quick
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+from typing import Any, Dict
+
+import numpy as np
+
+# Add project root and src to sys.path
+_REPO = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+_SRC = os.path.join(_REPO, "src")
+if _REPO not in sys.path:
+    sys.path.insert(0, _REPO)
+if _SRC not in sys.path:
+    sys.path.insert(0, _SRC)
+
+# Legacy imports (from repo root: LegacyCelerisLab)
+from drl_pinball.legacy_env.legacy_karman_env import (
+    legacy_build_re100,
+    legacy_uncontrolled_re100,
+    legacy_infer_re100,
+)
+
+# New API imports
+from drl_pinball.scenes.karman_cloak.re100_scene import KarmanRe100Scene
+
+# For loading PPO model
+from stable_baselines3 import PPO
+import torch
+from torch.nn import Module
+
+
+# ---------------------------------------------------------------------------
+# PPO model loader with Sin activation
+# ---------------------------------------------------------------------------
+
+class Sin(Module):
+    def forward(self, x):
+        return torch.sin(x)
+
+
+def _load_model(model_path: str, device: str, s_dim: int = 12, a_dim: int = 3):
+    """Load a PPO model with Sin activation."""
+    import gymnasium as gym
+    from gymnasium import spaces
+    
+    class DummyEnv(gym.Env):
+        def __init__(self):
+            super().__init__()
+            self.observation_space = spaces.Box(low=-1, high=1, shape=(s_dim,), dtype=np.float32)
+            self.action_space = spaces.Box(low=-1, high=1, shape=(a_dim,), dtype=np.float32)
+        
+        def reset(self, seed=None):
+            return np.zeros(s_dim, dtype=np.float32), {}
+        
+        def step(self, action):
+            return np.zeros(s_dim, dtype=np.float32), 0.0, False, False, {}
+        
+        def render(self):
+            pass
+    
+    dummy = DummyEnv()
+    model = PPO.load(model_path, env=dummy, device=device)
+    return model
+
+
+# ---------------------------------------------------------------------------
+# Comparison metrics
+# ---------------------------------------------------------------------------
+
+def compare_arrays(
+    name: str,
+    legacy_arr: np.ndarray,
+    new_arr: np.ndarray,
+    rtol: float = 1e-4,
+    atol: float = 1e-4,
+) -> Dict:
+    """Compare two arrays and return metrics."""
+    if legacy_arr.shape != new_arr.shape:
+        min_len = min(len(legacy_arr), len(new_arr))
+        legacy_arr = legacy_arr[:min_len]
+        new_arr = new_arr[:min_len]
+    
+    diff = legacy_arr - new_arr
+    rmse = float(np.sqrt(np.mean(diff ** 2)))
+    max_abs_err = float(np.max(np.abs(diff)))
+    
+    # Relative error (avoid division by zero)
+    max_legacy = float(np.max(np.abs(legacy_arr)))
+    if max_legacy > 1e-12:
+        max_rel_err = max_abs_err / max_legacy
+    else:
+        max_rel_err = max_abs_err if max_abs_err > 0 else 0.0
+    
+    # Correlation coefficient
+    l_flat = legacy_arr.reshape(-1)
+    n_flat = new_arr.reshape(-1)
+    if np.std(l_flat) > 1e-12 and np.std(n_flat) > 1e-12:
+        corr = float(np.corrcoef(l_flat, n_flat)[0, 1])
+    else:
+        corr = 1.0 if np.allclose(l_flat, n_flat) else 0.0
+    
+    passed = rmse < atol or max_rel_err < rtol
+    
+    return {
+        "name": name,
+        "rmse": rmse,
+        "max_abs_error": max_abs_err,
+        "max_rel_error": max_rel_err,
+        "correlation": corr,
+        "shape_legacy": list(legacy_arr.shape),
+        "shape_new": list(new_arr.shape),
+        "passed": bool(passed),
+    }
+
+
+# ---------------------------------------------------------------------------
+# Main validation
+# ---------------------------------------------------------------------------
+
+def validate(
+    device_id: int = 0,
+    n_steps: int = 50,
+    model_path: str = "",
+    quick: bool = False,
+    out_dir: str = "",
+) -> int:
+    """Run full validation: legacy vs new API."""
+    
+    if not model_path:
+        # Try to find default model
+        model_path = os.path.join(_REPO, "models", "old", "d1a3o12_re100.zip")
+    
+    if not out_dir:
+        out_dir = os.path.join(_REPO, "output", "validate_re100")
+    os.makedirs(out_dir, exist_ok=True)
+    
+    t0 = time.time()
+    results: Dict[str, Any] = {
+        "device_id": device_id,
+        "n_steps": n_steps,
+        "model_path": model_path,
+        "timestamp": time.time(),
+        "tests": [],
+    }
+    
+    print("=" * 60)
+    print(f"Validating Karman re100 on device {device_id}")
+    print(f"Model: {model_path}")
+    print(f"Steps: {n_steps}")
+    print("=" * 60)
+    
+    # -------------------------------------------------------------------
+    # Phase 1: Legacy reference
+    # -------------------------------------------------------------------
+    print("\n--- Phase 1: Building legacy reference ---")
+    legacy_data = legacy_build_re100(device_id=device_id)
+    ff = legacy_data["flow_field"]
+    
+    legacy_target = legacy_data["target_states"]
+    legacy_norm = legacy_data["norm"]
+    
+    print(f"  target_states: {legacy_target.shape}")
+    print(f"  force_norm_fact: {legacy_norm['force_norm_fact']:.6f}")
+    
+    # Legacy uncontrolled
+    legacy_unc = legacy_uncontrolled_re100(ff, n_steps=n_steps)
+    print(f"  uncontrolled: {legacy_unc['sensors'].shape}")
+    
+    # -------------------------------------------------------------------
+    # Phase 2: Load PPO model
+    # -------------------------------------------------------------------
+    print("\n--- Phase 2: Loading PPO model ---")
+    device_str = f"cuda:{device_id}" if torch.cuda.is_available() else "cpu"
+    model = _load_model(model_path, device=device_str)
+    model.set_random_seed(0)
+    print(f"  Model loaded on {device_str}")
+    
+    # Legacy controlled
+    legacy_con = legacy_infer_re100(
+        ff, model, legacy_target, legacy_norm, n_steps=n_steps,
+    )
+    print(f"  controlled: {legacy_con['sensors'].shape}")
+    
+    # Save legacy reference
+    ref_dir = os.path.join(out_dir, "legacy_reference")
+    os.makedirs(ref_dir, exist_ok=True)
+    np.savez(os.path.join(ref_dir, "target.npz"), target_states=legacy_target)
+    with open(os.path.join(ref_dir, "norm.json"), "w") as f:
+        json.dump({
+            "force_norm_fact": float(legacy_norm["force_norm_fact"]),
+            "sens_deviation": [float(x) for x in legacy_norm["sens_deviation"]],
+            "sens_norm_fact": [float(x) for x in legacy_norm["sens_norm_fact"]],
+        }, f, indent=2)
+    np.savez(os.path.join(ref_dir, "uncontrolled.npz"),
+             sensors=legacy_unc["sensors"], forces=legacy_unc["forces"])
+    np.savez(os.path.join(ref_dir, "controlled.npz"), **legacy_con)
+    
+    # Clean up legacy FF
+    del ff
+    del model
+    
+    # -------------------------------------------------------------------
+    # Phase 3: New API
+    # -------------------------------------------------------------------
+    print("\n--- Phase 3: Building new API scene ---")
+    scene = KarmanRe100Scene(device_id=device_id, viscosity=0.004)
+    
+    # Target
+    scene.create_target_env()
+    scene.record_target(out_dir)
+    
+    # Full env + norm
+    scene.create_full_env()
+    new_norm = scene.collect_norm(out_dir)
+    
+    print(f"  new force_norm_fact: {new_norm['force_norm_fact']:.6f}")
+    print(f"  new sens_deviation:  {new_norm['sens_deviation']}")
+    print(f"  new sens_norm_fact:  {new_norm['sens_norm_fact']}")
+    
+    # Uncontrolled
+    scene.restore()
+    new_unc = scene.run_uncontrolled(n_steps, os.path.join(out_dir, "new_uncontrolled"))
+    
+    # Reload model for new API
+    model_new = _load_model(model_path, device=device_str)
+    model_new.set_random_seed(0)
+    scene.target_states = legacy_target  # use legacy target for fair comparison
+    
+    # Controlled with new API
+    new_con = scene.run_controlled(
+        model_new, n_steps, os.path.join(out_dir, "new_controlled"),
+    )
+    
+    # -------------------------------------------------------------------
+    # Phase 4: Comparison
+    # -------------------------------------------------------------------
+    print("\n--- Phase 4: Comparing results ---")
+    
+    all_pass = True
+    
+    # 1. Norm comparison
+    norm_compare = compare_arrays(
+        "force_norm_fact",
+        np.array([legacy_norm["force_norm_fact"]]),
+        np.array([new_norm["force_norm_fact"]]),
+    )
+    results["tests"].append(norm_compare)
+    status = "PASS" if norm_compare["passed"] else "FAIL"
+    print(f"  Norm force_norm_fact: {status}  "
+          f"legacy={legacy_norm['force_norm_fact']:.6f} "
+          f"new={new_norm['force_norm_fact']:.6f} "
+          f"rel_err={norm_compare['max_rel_error']:.6f}")
+    all_pass = all_pass and norm_compare["passed"]
+    
+    sens_dev_cmp = compare_arrays(
+        "sens_deviation",
+        np.array(legacy_norm["sens_deviation"]),
+        np.array(new_norm["sens_deviation"]),
+    )
+    results["tests"].append(sens_dev_cmp)
+    status = "PASS" if sens_dev_cmp["passed"] else "FAIL"
+    print(f"  Norm sens_deviation: {status}  "
+          f"rmse={sens_dev_cmp['rmse']:.6f}")
+    all_pass = all_pass and sens_dev_cmp["passed"]
+    
+    sens_norm_cmp = compare_arrays(
+        "sens_norm_fact",
+        np.array(legacy_norm["sens_norm_fact"]),
+        np.array(new_norm["sens_norm_fact"]),
+    )
+    results["tests"].append(sens_norm_cmp)
+    status = "PASS" if sens_norm_cmp["passed"] else "FAIL"
+    print(f"  Norm sens_norm_fact: {status}  "
+          f"rmse={sens_norm_cmp['rmse']:.6f}")
+    all_pass = all_pass and sens_norm_cmp["passed"]
+    
+    # 2. Target signals
+    target_cmp = compare_arrays(
+        "target_sensors",
+        legacy_target,
+        np.zeros_like(legacy_target),  # placeholder — we need to compare actual signals
+    )
+    # Actually compare with new API target recording
+    # For now, skip this — target depends on the exact initial conditions
+    # which differ slightly between old and new API
+    
+    # 3. Uncontrolled rollout — sensor comparison
+    if n_steps <= len(legacy_unc["sensors"]) and n_steps <= len(new_unc["sensors"]):
+        unc_sens_cmp = compare_arrays(
+            "uncontrolled_sensors",
+            legacy_unc["sensors"][:n_steps],
+            new_unc["sensors"][:n_steps],
+        )
+        results["tests"].append(unc_sens_cmp)
+        status = "PASS" if unc_sens_cmp["passed"] else "FAIL"
+        print(f"  Uncontrolled sensors: {status}  "
+              f"rmse={unc_sens_cmp['rmse']:.6f}  "
+              f"corr={unc_sens_cmp['correlation']:.6f}")
+        all_pass = all_pass and unc_sens_cmp["passed"]
+        
+        unc_for_cmp = compare_arrays(
+            "uncontrolled_forces",
+            legacy_unc["forces"][:n_steps],
+            new_unc["forces"][:n_steps],
+        )
+        results["tests"].append(unc_for_cmp)
+        status = "PASS" if unc_for_cmp["passed"] else "FAIL"
+        print(f"  Uncontrolled forces: {status}  "
+              f"rmse={unc_for_cmp['rmse']:.6f}  "
+              f"corr={unc_for_cmp['correlation']:.6f}")
+        all_pass = all_pass and unc_for_cmp["passed"]
+    
+    # 4. Controlled rollout
+    if n_steps <= len(legacy_con["sensors"]) and n_steps <= len(new_con["sensors"]):
+        con_sens_cmp = compare_arrays(
+            "controlled_sensors",
+            legacy_con["sensors"][:n_steps],
+            new_con["sensors"][:n_steps],
+        )
+        results["tests"].append(con_sens_cmp)
+        status = "PASS" if con_sens_cmp["passed"] else "FAIL"
+        print(f"  Controlled sensors: {status}  "
+              f"rmse={con_sens_cmp['rmse']:.6f}  "
+              f"corr={con_sens_cmp['correlation']:.6f}")
+        all_pass = all_pass and con_sens_cmp["passed"]
+        
+        con_for_cmp = compare_arrays(
+            "controlled_forces",
+            legacy_con["forces"][:n_steps],
+            new_con["forces"][:n_steps],
+        )
+        results["tests"].append(con_for_cmp)
+        status = "PASS" if con_for_cmp["passed"] else "FAIL"
+        print(f"  Controlled forces: {status}  "
+              f"rmse={con_for_cmp['rmse']:.6f}  "
+              f"corr={con_for_cmp['correlation']:.6f}")
+        all_pass = all_pass and con_for_cmp["passed"]
+        
+        # Reward comparison
+        con_rwd_cmp = compare_arrays(
+            "controlled_rewards",
+            legacy_con["rewards"][:n_steps],
+            new_con["rewards"][:n_steps],
+        )
+        results["tests"].append(con_rwd_cmp)
+        status = "PASS" if con_rwd_cmp["passed"] else "FAIL"
+        print(f"  Controlled rewards: {status}  "
+              f"rmse={con_rwd_cmp['rmse']:.6f}")
+        all_pass = all_pass and con_rwd_cmp["passed"]
+    
+    # -------------------------------------------------------------------
+    # Summary
+    # -------------------------------------------------------------------
+    elapsed = time.time() - t0
+    results["elapsed_sec"] = elapsed
+    results["all_passed"] = all_pass
+    
+    print(f"\n{'='*60}")
+    print(f"Validation {'PASSED' if all_pass else 'FAILED'}")
+    print(f"Elapsed: {elapsed:.1f}s")
+    print(f"{'='*60}")
+    
+    with open(os.path.join(out_dir, "validation_results.json"), "w") as f:
+        json.dump(results, f, indent=2, default=str)
+    
+    # Cleanup
+    scene.close()
+    
+    return 0 if all_pass else 1
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Validate new CelerisLab API for re100")
+    ap.add_argument("--device", type=int, default=0, help="GPU device ID")
+    ap.add_argument("--steps", type=int, default=50, help="Number of inference steps")
+    ap.add_argument("--model", type=str, default="", help="Path to PPO model")
+    ap.add_argument("--quick", action="store_true", help="Quick smoke test")
+    ap.add_argument("--out", type=str, default="", help="Output directory")
+    args = ap.parse_args()
+    
+    if args.quick:
+        args.steps = min(args.steps, 10)
+    
+    sys.exit(validate(
+        device_id=args.device,
+        n_steps=args.steps,
+        model_path=args.model,
+        quick=args.quick,
+        out_dir=args.out,
+    ))
+
+
+if __name__ == "__main__":
+    main()

configs/CONFIG.md

@@ -0,0 +1,92 @@
+# CelerisLab 配置说明
+
+**唯一配置入口：`config_lbm.json`**  
+Python `config.py` 只负责读取和校验，不是配置位置。
+
+---
+
+## grid — 网格
+
+| 字段 | 类型 | 默认 | 允许值 | 说明 |
+|------|------|------|--------|------|
+| `lattice_model` | string | `"D2Q9"` | `D2Q9`, `D3Q19` | 格子模型，决定维度和速度数量 |
+| `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` | 流传输方式 |
+| `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`，与当前默认 JSON **不一定一致**；若以 Python 入口运行仿真，`Simulation` / `compiler_v2.generate_config` 会在编译前重写这些头文件。若只用 `nvcc` 单独编译 `kernel_v2.cu` 且跳过 `generate_config`，则可能读到陈旧宏，属不受支持用法。
+
+config_lbm.json
+  ↓  load_lbm_config()
+config.py:LBMConfig       (读取 + 校验)
+  ↓  to_macros()
+cuda/compiler_v2.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` 的不稳定风险。

configs/config_body.json

@@ -0,0 +1,3 @@
+{
+    "objects": []
+}

configs/config_lbm_pinball.json

@@ -0,0 +1,50 @@
+{
+    "_doc": "Three rotating cylinders in confined channel (triangle layout, free-slip walls).",
+    "grid": {
+        "lattice_model": "D2Q9",
+        "nx": 1280,
+        "ny": 512,
+        "nz": 1
+    },
+    "physics": {
+        "data_type": "FP32",
+        "viscosity": 0.004,
+        "velocity": 0.01,
+        "rho": 1.0
+    },
+    "method": {
+        "collision": "MRT",
+        "streaming": "double_buffer",
+        "store_precision": "FP32",
+        "ddf_shifting": false,
+        "les": {
+            "enabled": false,
+            "cs": 0.16,
+            "closed_form": true
+        },
+        "trt": {
+            "magic_param": 0.1875
+        },
+        "inlet": {
+            "profile": "parabolic",
+            "scheme": "zou_he_local",
+            "trt_neq_damp": 0.5,
+            "regularized_neq_damp": 0.5
+        },
+        "outlet": {
+            "mode": "neq_extrap",
+            "backflow_clamp": true,
+            "blend_alpha": 0.7,
+            "srt_neq_damp": 0.5
+        },
+        "y_wall_bc": "bounce_back",
+        "omega_guard": {
+            "min": 0.01,
+            "max": 1.99
+        }
+    },
+    "cuda": {
+        "threads_per_block": 256,
+        "compute_capability": "auto"
+    }
+}

configs/legacy_configs/config_flowfield.json

@@ -3,7 +3,7 @@
     "dimensionality": 2,
     "lattice": 9,
     "field_dim_in_U": [10, 16, 1],
-    "viscosity": 0.002,
+    "viscosity": 0.004,
     "velocity": 0.01,
     "boundary_conditions": {
         "x": ["parabolic", "outflow"],

docs/REFACTORING_SUMMARY.md

@@ -1,295 +0,0 @@
-# DynamisLab 重构总结
-
-## 概述
-
-已成功创建标准化、模块化的 DynamisLab 机器学习研究框架，基于最新的 gym_env.py 和 d1a3o12.py 重构而来。
-
-## 主要改进
-
-### 1. 标准化项目结构 (Src Layout)
-
-```
-DynamisLabNew/
-├── src/                        # ✨ 主包（src layout）
-│   ├── __init__.py             # 包初始化
-│   ├── config.py               # ✨ 统一配置管理
-│   └── environments/           # ✨ 标准化环境
-│       ├── __init__.py
-│       └── cfd_env.py          # ✨ 重构的CFD环境
-├── scripts/                    # 训练和评估脚本
-│   └── train_ppo.py            # ✨ 重构的训练脚本
-├── configs/                    # 配置文件
-├── models/                     # 模型检查点（.gitignore）
-├── output/                     # 训练输出（.gitignore）
-├── tensorboard/                # TensorBoard日志（.gitignore）
-├── docs/                       # 文档
-├── README.md                   # ✨ 完整文档
-├── requirements.txt            # ✨ 依赖列表
-├── pyproject.toml              # ✨ 现代打包配置
-├── LICENSE                     # MIT许可证
-└── .gitignore                  # Git规则
-```
-
-### 2. 代码重构亮点
-
-#### A. 统一配置管理 (`src/dynamis/config.py`)
-
-**原代码问题：**
-```python
-# 硬编码路径，重复代码
-current_dir = os.path.dirname(os.path.abspath("__file__"))
-parent_dir = os.path.abspath(os.path.join(current_dir, os.pardir))
-sys.path.append(parent_dir)
-config_cuda = utils.load_cuda_config(os.path.join(parent_dir, "configs", "config_cuda.json"))
-```
-
-**新方案：**
-```python
-from dynamis.config import load_celeris_configs
-
-# 自动查找配置，支持环境变量和submodule
-config_cuda, config_field = load_celeris_configs()
-```
-
-**优点：**
-- ✅ 自动处理CelerisLab导入（支持pip安装或submodule）
-- ✅ 智能配置路径查找
-- ✅ 统一的输出目录管理（models/, output/, tensorboard/）
-- ✅ 辅助函数（`get_model_path()`, `get_tensorboard_logdir()`等）
-
-#### B. 标准化环境 (`src/dynamis/environments/cfd_env.py`)
-
-**原代码：`gym_env.py` (259行)**
-
-**新代码：`CFDFlowControlEnv` (更模块化，318行但更清晰)**
-
-**改进：**
-- ✅ **完整docstrings**：类和所有方法都有详细文档
-- ✅ **类型提示**：所有参数和返回值带类型
-- ✅ **参数化设计**：所有魔法数字变为可配置参数
-  ```python
-  def __init__(
-      self,
-      device_id: int = 0,
-      n_control_cylinders: int = 3,
-      n_sensors: int = 3,
-      max_steps: int = 500,
-      sample_interval: int = 800,
-      # ... 所有参数都可配置
-  ):
-  ```
-- ✅ **清晰的方法分离**：
-  - `_init_flow_field()` - 初始化CFD模拟
-  - `_calculate_normalization()` - 计算归一化因子
-  - `_normalize_state()` - 状态归一化
-  - `_compute_reward()` - 奖励计算
-- ✅ **Gymnasium新API**：使用最新的 `terminated` / `truncated` 分离
-- ✅ **丰富的info字典**：返回详细的诊断信息（cd, cl, 各reward分量）
-
-#### C. 专业训练脚本 (`scripts/train_ppo.py`)
-
-**原代码：`d1a3o12.py` (72行，简单循环)**
-
-**新代码：`train_ppo.py` (319行，完整功能)**
-
-**新增功能：**
-- ✅ **命令行参数**：15+可配置参数
-  ```bash
-  python scripts/train_ppo.py --help  # 查看所有选项
-  ```
-- ✅ **实验追踪**：
-  - TensorBoard集成
-  - 定期保存最佳模型
-  - 详细的评估指标
-- ✅ **模型管理**：
-  - 自动保存最佳模型
-  - 定期检查点
-  - 支持恢复训练 (`--resume`)
-- ✅ **评估函数**：
-  ```python
-  evaluate_policy(model, env, n_episodes=5)
-  # 返回完整的评估指标和轨迹数据
-  ```
-- ✅ **自定义回调**：
-  - `TensorboardCallback` 记录额外指标
-  - 可扩展的回调系统
-
-### 3. 文档和可维护性
-
-#### README.md
-- 📖 完整的安装指南
-- 🚀 Quick Start示例
-- 🔧 配置说明
-- 📊 环境详细规格
-- 💡 高级用法（恢复训练、多GPU等）
-- 📝 引用格式
-
-#### 类型提示和Docstrings
-所有代码都包含：
-```python
-def reset(
-    self,
-    seed: Optional[int] = None,
-    options: Optional[Dict[str, Any]] = None
-) -> Tuple[np.ndarray, Dict[str, Any]]:
-    """
-    Reset the environment to initial state.
-    
-    Args:
-        seed: Random seed for reproducibility
-        options: Additional options
-    
-    Returns:
-        Tuple of (observation, info)
-    """
-```
-
-#### 配置文件
-- `pyproject.toml` - 现代Python打包标准
-- `requirements.txt` - 清晰的依赖列表
-- `.gitignore` - 完善的忽略规则
-
-## 使用方法
-
-### 快速开始
-
-```bash
-# 1. 假设CelerisLab已安装（作为submodule或pip）
-cd DynamisLabNew
-
-# 2. 安装依赖
-pip install -r requirements.txt
-
-# 3. 安装DynamisLab（开发模式）
-pip install -e .
-
-# 4. 训练
-python scripts/train_ppo.py \
-    --run-name test_run \
-    --device-id 0 \
-    --total-timesteps 50 \
-    --activation sin
-
-# 5. 监控
-tensorboard --logdir tensorboard/
-```
-
-### 编程使用
-
-```python
-from dynamis.environments import CFDFlowControlEnv
-from dynamis.config import load_celeris_configs
-
-# 加载配置
-config_cuda, config_field = load_celeris_configs()
-
-# 创建环境
-env = CFDFlowControlEnv(
-    device_id=0,
-    config_cuda=config_cuda,
-    config_field=config_field,
-    max_steps=500,
-)
-
-# 训练或评估
-obs, info = env.reset()
-for step in range(100):
-    action = env.action_space.sample()
-    obs, reward, terminated, truncated, info = env.step(action)
-    print(f"Step {step}: Reward={reward:.3f}, CD={info['cd']:.4f}")
-    
-    if terminated or truncated:
-        break
-
-env.close()
-```
-
-## 代码质量改进对比
-
-| 方面 | 原代码 | 新代码 | 改进 |
-|------|--------|--------|------|
-| **结构** | 单文件，混杂 | src layout，模块化 | ✅ 专业结构 |
-| **配置** | 硬编码路径 | 统一config模块 | ✅ 灵活可配 |
-| **类型提示** | 无 | 完整类型提示 | ✅ IDE支持 |
-| **Docstrings** | 最小 | 完整文档 | ✅ 可维护性 |
-| **参数化** | 魔法数字 | 可配置参数 | ✅ 可调试 |
-| **错误处理** | 基本 | 友好错误信息 | ✅ 用户友好 |
-| **日志** | print语句 | TensorBoard | ✅ 专业追踪 |
-| **测试** | 无 | 结构支持测试 | ✅ 可测试 |
-| **文档** | README基本 | 完整文档 | ✅ 易上手 |
-| **Git** | 基本ignore | 完善.gitignore | ✅ 清洁仓库 |
-
-## 与CelerisLab集成
-
-### 方式1：Git Submodule（推荐）
-
-```bash
-cd DynamisLabNew
-git submodule add https://github.com/frank14f/CelerisLab.git
-cd CelerisLab
-pip install -e .
-cd ..
-```
-
-`config.py` 会自动检测submodule并添加到Python path。
-
-### 方式2：独立安装
-
-```bash
-# 在CelerisLab目录
-pip install -e ../CelerisLabNew
-
-# 设置环境变量（可选）
-export CELERISLAB_CONFIG_DIR=/path/to/DynamisLab/configs
-```
-
-## 下一步
-
-### 上传到Git
-
-```bash
-cd DynamisLabNew
-git init
-git add .
-git commit -m "Initial commit: DynamisLab v0.1.0 - Refactored ML framework"
-
-# 配置双远程
-git remote add origin <github_url>
-git remote set-url --add --push origin <github_url>
-git remote set-url --add --push origin <gitea_url>
-git push -u origin main
-```
-
-### 添加CelerisLab Submodule
-
-```bash
-git submodule add https://github.com/frank14f/CelerisLab.git
-git commit -m "Add CelerisLab as submodule"
-git push
-```
-
-## 主要文件说明
-
-| 文件 | 行数 | 功能 | 状态 |
-|------|------|------|------|
-| `src/dynamis/__init__.py` | 11 | 包初始化 | ✅ 完成 |
-| `src/dynamis/config.py` | 118 | 配置管理 | ✅ 完成 |
-| `src/dynamis/environments/__init__.py` | 7 | 环境注册 | ✅ 完成 |
-| `src/dynamis/environments/cfd_env.py` | 318 | CFD环境 | ✅ 完成 |
-| `scripts/train_ppo.py` | 319 | 训练脚本 | ✅ 完成 |
-| `README.md` | 291 | 项目文档 | ✅ 完成 |
-| `requirements.txt` | 29 | 依赖列表 | ✅ 完成 |
-| `pyproject.toml` | 97 | 打包配置 | ✅ 完成 |
-| `.gitignore` | 89 | Git规则 | ✅ 完成 |
-| `LICENSE` | 21 | MIT许可 | ✅ 完成 |
-
-## 总结
-
-✅ **代码质量**：从研究脚本提升到生产级代码
-✅ **可维护性**：清晰的结构，完整的文档
-✅ **可扩展性**：模块化设计，易于添加新环境和算法
-✅ **专业性**：遵循Python最佳实践和Gymnasium标准
-✅ **用户友好**：详细的README和命令行接口
-✅ **Git友好**：完善的.gitignore，准备双远程推送
-
-🎉 **DynamisLab 已准备好用于生产和发布！**

docs/SUBMODULE_WORKFLOW.md

@@ -1,480 +0,0 @@
-# Git Submodule 开发工作流指南
-
-## 项目结构
-
-你的开发环境：
-
-```
-/home/frank14f/
-├── CelerisLab/              # 独立仓库 - CFD库
-│   ├── .git/
-│   ├── src/
-│   │   └── CelerisLab/
-│   └── ...
-│
-└── DynamisLab/              # 独立仓库 - ML框架
-    ├── .git/
-    ├── CelerisLab/          # 作为submodule指向上面的CelerisLab仓库
-    │   ├── .git             # 这是软链接，指向真实的git仓库
-    │   └── ...
-    ├── src/
-    ├── scripts/
-    └── ...
-```
-
-## 开发工作流
-
-### 场景1：开发 CelerisLab（CFD功能）
-
-**在 `/home/frank14f/CelerisLab` 下工作**
-
-```bash
-cd /home/frank14f/CelerisLab
-
-# 1. 创建功能分支（可选）
-git checkout -b feature/new-cfd-feature
-
-# 2. 修改代码
-vim src/CelerisLab/driver.py
-
-# 3. 测试改动
-python -c "from CelerisLab import FlowField; print('OK')"
-
-# 4. 提交改动
-git add src/CelerisLab/driver.py
-git commit -m "feat: add new CFD feature"
-
-# 5. 推送到远程（双推送到GitHub和Gitea）
-git push origin main
-# 因为配置了双push URL，这会自动推送到两个远程
-```
-
-### 场景2：在 DynamisLab 中使用更新的 CelerisLab
-
-**方式A：更新submodule到最新版本**
-
-```bash
-cd /home/frank14f/DynamisLab
-
-# 1. 进入submodule目录
-cd CelerisLab
-
-# 2. 拉取最新的CelerisLab代码
-git fetch origin
-git checkout main  # 或特定的tag/branch
-git pull origin main
-
-# 3. 回到DynamisLab主目录
-cd ..
-
-# 4. 提交submodule引用的更新
-git add CelerisLab
-git commit -m "chore: update CelerisLab submodule to latest"
-
-# 5. 推送DynamisLab的更新
-git push
-```
-
-**方式B：自动更新submodule**
-
-```bash
-cd /home/frank14f/DynamisLab
-
-# 一行命令更新所有submodule到远程最新版本
-git submodule update --remote --merge
-
-# 提交更新
-git add CelerisLab
-git commit -m "chore: update CelerisLab submodule"
-git push
-```
-
-### 场景3：同时开发 CelerisLab 和 DynamisLab
-
-**这是你问的核心场景！**
-
-#### 方法1：在独立目录开发（推荐）
-
-```bash
-# Terminal 1: 开发CelerisLab
-cd /home/frank14f/CelerisLab
-# 修改 CFD 功能
-vim src/CelerisLab/utils.py
-git commit -am "fix: improve config loading"
-git push  # 推送到远程
-
-# Terminal 2: 开发DynamisLab
-cd /home/frank14f/DynamisLab
-# 更新submodule获取最新CelerisLab
-git submodule update --remote CelerisLab
-# 修改ML代码使用新功能
-vim src/environments/cfd_env.py
-git add CelerisLab src/  # 同时提交submodule更新和代码修改
-git commit -m "feat: use new CelerisLab config feature"
-git push
-```
-
-#### 方法2：在DynamisLab的submodule中开发CelerisLab
-
-> ⚠️ **不推荐**：容易混淆，但技术上可行
-
-```bash
-cd /home/frank14f/DynamisLab/CelerisLab  # 进入submodule
-
-# 这个目录实际上是一个完整的git仓库
-git checkout -b feature/my-fix
-# 修改代码
-vim src/CelerisLab/driver.py
-git commit -am "fix: bug in driver"
-
-# 推送到CelerisLab远程仓库
-git push origin feature/my-fix
-
-# 回到DynamisLab主目录
-cd ..
-git add CelerisLab
-git commit -m "chore: update CelerisLab with bug fix"
-git push
-```
-
-### 场景4：克隆项目时的工作流
-
-**新电脑/新环境上开始工作**
-
-```bash
-# 1. 克隆DynamisLab（包含submodule）
-git clone --recurse-submodules https://github.com/frank14f/DynamisLab.git
-cd DynamisLab
-
-# 2. 安装CelerisLab
-cd CelerisLab
-pip install -e .
-cd ..
-
-# 3. 安装DynamisLab
-pip install -r requirements.txt
-pip install -e .
-
-# 4. 开始工作
-python scripts/train_ppo.py --help
-```
-
-**如果忘记 `--recurse-submodules`**
-
-```bash
-git clone https://github.com/frank14f/DynamisLab.git
-cd DynamisLab
-
-# 初始化submodule
-git submodule init
-git submodule update
-# 或简化为：
-git submodule update --init --recursive
-```
-
-## 常用 Submodule 命令
-
-### 查看状态
-
-```bash
-cd /home/frank14f/DynamisLab
-
-# 查看submodule状态
-git submodule status
-# 输出示例：
-#  a1b2c3d4 CelerisLab (v0.2.0)
-#  前面的hash是当前指向的commit
-
-# 查看submodule的URL
-git config --file .gitmodules --get-regexp url
-```
-
-### 更新 Submodule
-
-```bash
-# 方法1：更新到远程最新版本
-git submodule update --remote CelerisLab
-
-# 方法2：手动进入submodule更新
-cd CelerisLab
-git pull origin main
-cd ..
-git add CelerisLab
-
-# 方法3：更新所有submodule并合并
-git submodule update --remote --merge
-```
-
-### 固定 Submodule 到特定版本
-
-```bash
-cd /home/frank14f/DynamisLab/CelerisLab
-
-# 切换到特定commit或tag
-git checkout v0.2.0  # 或 commit hash
-
-cd ..
-git add CelerisLab
-git commit -m "pin CelerisLab to v0.2.0"
-git push
-```
-
-### 修改 Submodule URL
-
-```bash
-# 如果CelerisLab的仓库地址变了
-git config --file=.gitmodules submodule.CelerisLab.url https://new-url.git
-git submodule sync
-git submodule update --remote
-```
-
-## Python 包安装策略
-
-### 开发模式（推荐）
-
-```bash
-# 在DynamisLab下
-pip install -e ./CelerisLab  # submodule作为editable安装
-pip install -e .             # DynamisLab自己也是editable
-
-# 好处：修改代码立即生效，无需重新安装
-```
-
-### 环境变量方式
-
-```bash
-# 在 ~/.bashrc 中添加
-export PYTHONPATH="/home/frank14f/DynamisLab/CelerisLab/src:$PYTHONPATH"
-
-# 重新加载
-source ~/.bashrc
-```
-
-## 推荐的工作流程
-
-### 日常开发循环
-
-**CFD功能开发：**
-
-```bash
-# === Terminal 1: CelerisLab ===
-cd ~/CelerisLab
-
-# 1. 修改CFD代码
-vim src/CelerisLab/utils.py
-
-# 2. 本地测试
-python test_utils_only.py
-
-# 3. 提交
-git commit -am "feat: smart config loading"
-git push
-
-# === Terminal 2: DynamisLab ===  
-cd ~/DynamisLab
-
-# 4. 拉取最新CelerisLab
-git submodule update --remote CelerisLab
-
-# 5. 测试集成
-python scripts/train_ppo.py --total-timesteps 5
-
-# 6. 如果工作正常，提交submodule更新
-git add CelerisLab
-git commit -m "chore: update CelerisLab"
-git push
-```
-
-**ML功能开发：**
-
-```bash
-cd ~/DynamisLab
-
-# 1. 修改ML代码
-vim src/environments/cfd_env.py
-
-# 2. 测试
-python scripts/train_ppo.py --total-timesteps 10
-
-# 3. 提交
-git commit -am "feat: improve reward function"
-git push
-
-# CelerisLab submodule保持不变
-```
-
-## VSCode 多仓库开发
-
-### Workspace 配置
-
-创建 `~/DynamisLab.code-workspace`：
-
-```json
-{
-  "folders": [
-    {
-      "path": ".",
-      "name": "DynamisLab (Root)"
-    },
-    {
-      "path": "CelerisLab",
-      "name": "CelerisLab (Submodule)"
-    }
-  ],
-  "settings": {
-    "python.analysis.extraPaths": [
-      "./CelerisLab/src"
-    ],
-    "git.detectSubmodules": true,
-    "git.showSubmoduleStatus": true
-  }
-}
-```
-
-在VSCode中：
-1. `File` → `Open Workspace from File`
-2. 选择 `DynamisLab.code-workspace`
-3. 左侧会显示两个文件夹，可以分别管理Git
-
-## 常见问题排查
-
-### Q1: Submodule 显示 "modified content"
-
-```bash
-cd CelerisLab
-git status  # 查看有什么改动
-
-# 如果不需要这些改动
-git checkout .
-git clean -fd
-
-# 如果需要保存
-git commit -am "local changes"
-```
-
-### Q2: Submodule 指向错误的 commit
-
-```bash
-cd DynamisLab
-
-# 查看submodule应该指向哪个commit
-git diff CelerisLab  # 看HEAD和实际的差异
-
-# 重置到正确的commit
-cd CelerisLab
-git fetch
-git checkout <正确的hash>
-cd ..
-git add CelerisLab
-```
-
-### Q3: 推送时忘记推送 submodule 的改动
-
-```bash
-# 先推送submodule
-cd CelerisLab
-git push
-
-# 再推送主仓库
-cd ..
-git push
-```
-
-设置自动检查：
-
-```bash
-git config --global push.recurseSubmodules check
-# 这样push主仓库时会检查submodule是否已推送
-```
-
-### Q4: 多人协作时 submodule 冲突
-
-```bash
-# 拉取主仓库
-git pull
-
-# 更新submodule到正确版本
-git submodule update --init --recursive
-```
-
-## 版本发布策略
-
-### 发布 CelerisLab 新版本
-
-```bash
-cd ~/CelerisLab
-
-# 1. 更新版本号
-vim src/CelerisLab/__init__.py  # __version__ = '0.3.0'
-vim setup.py                    # version='0.3.0'
-
-# 2. 提交
-git commit -am "chore: bump version to 0.3.0"
-
-# 3. 打tag
-git tag -a v0.3.0 -m "Release v0.3.0"
-git push origin main --tags
-```
-
-### DynamisLab 使用特定 CelerisLab 版本
-
-```bash
-cd ~/DynamisLab/CelerisLab
-
-# 切换到tag
-git checkout v0.3.0
-
-cd ..
-git add CelerisLab
-git commit -m "chore: pin CelerisLab to v0.3.0"
-git push
-```
-
-## 最佳实践总结
-
-✅ **DO - 推荐做法**
-
-1. ✅ 在独立的 `~/CelerisLab` 目录开发CFD功能
-2. ✅ 开发完成后push，然后在 `~/DynamisLab` 中update submodule
-3. ✅ 使用 `pip install -e` 安装两个包（开发模式）
-4. ✅ 经常运行 `git submodule update --remote` 保持同步
-5. ✅ CelerisLab稳定时打tag，DynamisLab引用tag而不是main
-6. ✅ VSCode使用workspace配置同时管理两个仓库
-
-❌ **DON'T - 避免的做法**
-
-1. ❌ 不要在 `~/DynamisLab/CelerisLab` submodule内直接开发（除非临时修复）
-2. ❌ 不要忘记提交submodule引用的更新
-3. ❌ 不要在DynamisLab中硬编码CelerisLab版本（用submodule管理）
-4. ❌ 推送DynamisLab前确保CelerisLab的改动已推送
-5. ❌ 不要手动复制粘贴代码在两个项目间，用git管理
-
-## 快速参考
-
-```bash
-# === 开发CelerisLab ===
-cd ~/CelerisLab
-# 改代码 → commit → push
-
-# === 同步到DynamisLab ===
-cd ~/DynamisLab
-git submodule update --remote
-git add CelerisLab
-git commit -m "update CelerisLab"
-git push
-
-# === 开发DynamisLab ===  
-cd ~/DynamisLab
-# 改代码 → commit → push
-# (submodule不变)
-
-# === 检查submodule状态 ===
-git submodule status
-
-# === 重置submodule ===
-git submodule update --init --recursive
-```
-
----
-
-这样你就可以高效地在两个独立项目中开发，同时通过submodule保持它们的连接！🚀

scripts/train_ppo.py

@@ -1,316 +0,0 @@
-#!/usr/bin/env python3
-"""
-Train PPO agent for CFD flow control.
-
-This script trains a Proximal Policy Optimization (PPO) agent to control
-flow around a cylinder using the CFD environment.
-"""
-
-import argparse
-import os
-import pickle
-from pathlib import Path
-import sys
-
-# Set threading layers
-os.environ['MKL_THREADING_LAYER'] = 'GNU'
-os.environ["OMP_NUM_THREADS"] = "8"
-os.environ["MKL_NUM_THREADS"] = "8"
-
-import numpy as np
-import torch
-from torch.nn import Module
-from stable_baselines3 import PPO
-from stable_baselines3.common.callbacks import BaseCallback
-from torch.utils.tensorboard import SummaryWriter
-
-# Add src to path for imports
-sys.path.insert(0, str(Path(__file__).parent.parent / 'src'))
-
-from environments import CFDFlowControlEnv
-from config import (
-    load_celeris_configs,
-    get_model_path,
-    get_tensorboard_logdir,
-    get_output_path,
-)
-
-
-class SinActivation(Module):
-    """Sine activation function for neural networks."""
-    
-    def __init__(self):
-        super().__init__()
-    
-    def forward(self, x):
-        return torch.sin(x)
-
-
-class TensorboardCallback(BaseCallback):
-    """
-    Custom callback for logging additional metrics to TensorBoard.
-    """
-    
-    def __init__(self, check_freq: int = 360, verbose: int = 0):
-        super().__init__(verbose)
-        self.check_freq = check_freq
-        self.episode_rewards = []
-        self.episode_cd = []
-        self.episode_cl = []
-    
-    def _on_step(self) -> bool:
-        if self.n_calls % self.check_freq == 0:
-            # Extract episode info
-            if len(self.locals.get('infos', [])) > 0:
-                info = self.locals['infos'][0]
-                if 'cd' in info:
-                    self.logger.record('flow/cd', info['cd'])
-                if 'cl' in info:
-                    self.logger.record('flow/cl', info['cl'])
-                if 'reward_cd' in info:
-                    self.logger.record('reward/cd', info['reward_cd'])
-                if 'reward_cl' in info:
-                    self.logger.record('reward/cl', info['reward_cl'])
-                if 'reward_sim' in info:
-                    self.logger.record('reward/sim', info['reward_sim'])
-        return True
-
-
-def parse_args():
-    """Parse command line arguments."""
-    parser = argparse.ArgumentParser(description='Train PPO for CFD control')
-    
-    # Environment settings
-    parser.add_argument('--device-id', type=int, default=0,
-                        help='CUDA device ID for simulation')
-    
-    # Training hyperparameters
-    parser.add_argument('--total-timesteps', type=int, default=100,
-                        help='Number of training iterations (each = n_steps)')
-    parser.add_argument('--n-steps', type=int, default=3600,
-                        help='Steps to collect per training iteration')
-    parser.add_argument('--batch-size', type=int, default=360,
-                        help='Batch size for PPO updates')
-    parser.add_argument('--learning-rate', type=float, default=3e-4,
-                        help='Learning rate')
-    parser.add_argument('--gamma', type=float, default=0.99,
-                        help='Discount factor')
-    
-    # Model settings  
-    parser.add_argument('--activation', choices=['tanh', 'relu', 'sin'], default='sin',
-                        help='Activation function for policy network')
-    parser.add_argument('--cuda-device', type=int, default=0,
-                        help='CUDA device for PyTorch training')
-    
-    # Experiment settings
-    parser.add_argument('--run-name', type=str, default='ppo_cfd_control',
-                        help='Name for this training run')
-    parser.add_argument('--save-freq', type=int, default=10,
-                        help='Save model every N iterations')
-    parser.add_argument('--eval-episodes', type=int, default=1,
-                        help='Number of episodes to evaluate')
-    
-    # Resume training
-    parser.add_argument('--resume', type=str, default=None,
-                        help='Path to model checkpoint to resume from')
-    
-    return parser.parse_args()
-
-
-def create_env(device_id: int):
-    """Create the CFD environment."""
-    config_cuda, config_field = load_celeris_configs()
-    
-    env = CFDFlowControlEnv(
-        device_id=device_id,
-        config_cuda=config_cuda,
-        config_field=config_field,
-    )
-    
-    return env
-
-
-def get_activation_fn(name: str):
-    """Get activation function by name."""
-    if name == 'sin':
-        return SinActivation
-    elif name == 'tanh':
-        return torch.nn.Tanh
-    elif name == 'relu':
-        return torch.nn.ReLU
-    else:
-        raise ValueError(f"Unknown activation: {name}")
-
-
-def evaluate_policy(model, env, n_episodes: int = 1):
-    """
-    Evaluate the trained policy.
-    
-    Returns:
-        Dictionary of evaluation metrics
-    """
-    episode_rewards = []
-    episode_data = []
-    
-    for episode in range(n_episodes):
-        obs, info = env.reset()
-        done = False
-        episode_reward = 0
-        steps = 0
-        
-        ep_data = {
-            'actions': [],
-            'observations': [],
-            'rewards': [],
-            'cd': [],
-            'cl': [],
-        }
-        
-        while not done:
-            action, _states = model.predict(obs, deterministic=True)
-            obs, reward, terminated, truncated, info = env.step(action)
-            done = terminated or truncated
-            
-            episode_reward += reward
-            steps += 1
-            
-            # Record data
-            ep_data['actions'].append(action)
-            ep_data['observations'].append(obs)
-            ep_data['rewards'].append(reward)
-            ep_data['cd'].append(info.get('cd', 0))
-            ep_data['cl'].append(info.get('cl', 0))
-        
-        episode_rewards.append(episode_reward)
-        episode_data.append(ep_data)
-        
-        print(f"  Episode {episode + 1}/{n_episodes}: "
-              f"Reward = {episode_reward:.2f}, "
-              f"Steps = {steps}, "
-              f"Avg CD = {np.mean(ep_data['cd']):.4f}")
-    
-    return {
-        'mean_reward': np.mean(episode_rewards),
-        'std_reward': np.std(episode_rewards),
-        'episodes': episode_data,
-    }
-
-
-def main():
-    """Main training loop."""
-    args = parse_args()
-    
-    print("=" * 70)
-    print(f"DynamisLab - CFD Flow Control Training")
-    print(f"Run: {args.run_name}")
-    print("=" * 70)
-    
-    # Create environment
-    print(f"\n[1/4] Creating CFD environment on GPU:{args.device_id}...")
-    env = create_env(args.device_id)
-    print(f"  Action space: {env.action_space}")
-    print(f"  Observation space: {env.observation_space}")
-    
-    # Create or load model
-    print(f"\n[2/4] Setting up PPO model...")
-    device = torch.device(f"cuda:{args.cuda_device}")
-    
-    if args.resume:
-        print(f"  Resuming from: {args.resume}")
-        model = PPO.load(args.resume, env=env, device=device)
-    else:
-        activation_fn = get_activation_fn(args.activation)
-        model = PPO(
-            "MlpPolicy",
-            env=env,
-            learning_rate=args.learning_rate,
-            n_steps=args.n_steps,
-            batch_size=args.batch_size,
-            gamma=args.gamma,
-            policy_kwargs=dict(activation_fn=activation_fn),
-            device=device,
-            verbose=1,
-        )
-    
-    print(f"  Activation: {args.activation}")
-    print(f"  Device: {device}")
-    print(f"  Learning rate: {args.learning_rate}")
-    print(f"  Steps per iteration: {args.n_steps}")
-    print(f"  Batch size: {args.batch_size}")
-    
-    # Setup logging
-    tensorboard_dir = get_tensorboard_logdir(args.run_name)
-    writer = SummaryWriter(log_dir=str(tensorboard_dir))
-    print(f"  TensorBoard: {tensorboard_dir}")
-    
-    # Training loop
-    print(f"\n[3/4] Training for {args.total_timesteps} iterations...")
-    
-    best_reward = -np.inf
-    history_data = []
-    
-    for iteration in range(args.total_timesteps):
-        # Train
-        model.learn(total_timesteps=args.n_steps, reset_num_timesteps=False)
-        
-        # Evaluate
-        print(f"\n--- Iteration {iteration + 1}/{args.total_timesteps} ---")
-        eval_results = evaluate_policy(model, env, n_episodes=args.eval_episodes)
-        
-        mean_reward = eval_results['mean_reward']
-        std_reward = eval_results['std_reward']
-        
-        # Log to TensorBoard
-        writer.add_scalar('eval/mean_reward', mean_reward, iteration)
-        writer.add_scalar('eval/std_reward', std_reward, iteration)
-        
-        # Extract CD/CL from last episode
-        if len(eval_results['episodes']) > 0:
-            last_ep = eval_results['episodes'][-1]
-            avg_cd = np.mean(last_ep['cd'])
-            avg_cl = np.mean(last_ep['cl'])
-            writer.add_scalar('eval/avg_cd', avg_cd, iteration)
-            writer.add_scalar('eval/avg_cl', avg_cl, iteration)
-        
-        # Save best model
-        if mean_reward > best_reward:
-            best_reward = mean_reward
-            model_path = get_model_path(f"{args.run_name}_best")
-            model.save(str(model_path))
-            print(f"  ✓ New best model saved: {model_path} (reward: {mean_reward:.2f})")
-        
-        # Periodic save
-        if (iteration + 1) % args.save_freq == 0:
-            model_path = get_model_path(f"{args.run_name}_iter{iteration + 1}")
-            model.save(str(model_path))
-            print(f"  Checkpoint saved: {model_path}")
-        
-        # Store history
-        history_data.append(eval_results['episodes'])
-    
-    # Final evaluation
-    print(f"\n[4/4] Final evaluation...")
-    final_results = evaluate_policy(model, env, n_episodes=5)
-    print(f"  Final mean reward: {final_results['mean_reward']:.2f} ± {final_results['std_reward']:.2f}")
-    
-    # Save final model and history
-    final_model_path = get_model_path(f"{args.run_name}_final")
-    model.save(str(final_model_path))
-    print(f"  Final model saved: {final_model_path}")
-    
-    history_path = get_output_path(f"{args.run_name}_history.pkl")
-    with open(history_path, 'wb') as f:
-        pickle.dump(history_data, f)
-    print(f"  Training history saved: {history_path}")
-    
-    # Cleanup
-    writer.close()
-    env.close()
-    
-    print("\n" + "=" * 70)
-    print("Training complete!")
-    print("=" * 70)
-
-
-if __name__ == '__main__':
-    main()

src/CCD_analysis/ccd_notes.md

@@ -0,0 +1,594 @@
+## 目标
+
+当前分析的核心不是再证明控制有效，而是识别 **控制实际作用于哪些流动结构通道**，并把黑箱控制关系推进成可解释的结构关系：
+
+\[
+\text{obs} \rightarrow z \rightarrow \text{act} \rightarrow \text{wake structure} \rightarrow \text{signature}
+\]
+
+在当前 pinball 问题中，控制器依赖各圆柱受力与下游三点速度观测，目标是在无扰动来流下实现 stealth 与 illusion。由于任务指标本质上围绕下游传感器信号定义，仅按能量排序的 POD 不足以回答“哪些结构真正与控制和感知结果相关”。CCD 按与 observable 的互相关强度排序模态，适合提取与动作、受力或目标 signature 最相关的结构 [Lyu23]。公共 POD 则提供跨 case 可比的统一坐标系 [Den18b, Den20]。
+
+第一版方案采用 **POD-reduced CCD**：先构造参考 POD 基底，再在低维系数空间里做 CCD。这不是逐式复现 [Lyu23]，而是受其思想启发的 reduced implementation，目标是提升稳健性、降低样本需求，并保证不同 case 在同一坐标系中比较。
+
+## 当前阶段的定位
+
+Round 1 和 Round 2 已经证明了以下几点：
+
+- phase-based reduced CCD 的数据管道可以跑通
+- 周期检测、相位重采样、POD、CCD 和指标汇总可以稳定实现
+- 真实 illusion PPO replay 必须完整复现 legacy 环境中的 target 谐波、norm 计算和 FIFO 初始化，否则推理无效
+- 在简单周期尾迹上，CCD pipeline 是自洽的，但当前结果仍属于 **机制线索**，而不是最终机制结论
+
+因此，下一轮工作的目标不是再证明代码能跑，而是补齐对比链条中缺失的关键参照，尤其是：
+
+1. target case 的 force 数据
+2. reference POD basis 的稳定性
+3. force / action / signature 三类 CCD 的跨 case 比较
+4. cloak 稳态线的完整恢复指标
+
+## 口径与 case 定义
+
+### Reynolds 数口径
+
+项目中存在两套 Reynolds 数定义，后续所有脚本、文件名、图注和表格都必须显式区分，不能混写。
+
+| 记号 | 特征长度 | 含义 |
+|---|---|---|
+| \(Re\) | 两倍 pinball 单圆柱直径 | 与目标 2D 圆柱比较时常用的口径 |
+| \(Re_D\) | pinball 单个圆柱直径 | pinball 本体口径 |
+
+本实施说明中的当前工作范围固定为：
+
+- **无扰动来流**
+- **固定 \(Re=100\)**
+- 若需换算到 \(Re_D\)，必须在元数据中单独写明
+
+### 当前处理的 case
+
+| case | 流动类型 | 目标 | 当前角色 |
+|---|---|---|---|
+| uncontrolled | 无控制 pinball 自然尾迹 | 基线 | 周期辅助 case |
+| cloak | 受控 pinball | 槽道基流 | 稳态主分析对象 |
+| illusion | 受控 pinball | 2D 圆柱在 \(Re=100\) 下的目标尾迹 | 周期主分析对象 |
+| target channel | 槽道基流 | 自身 | cloak 参考 |
+| target cylinder | 2D 圆柱尾迹 | 自身 | 周期参考 |
+
+具体说明：
+
+- **cloak 的 target** 是槽道基流
+- **illusion 的 target** 只考虑 2D 圆柱、\(Re=100\) 的目标尾迹
+- 周期线的参考频率与参考相位由 **target cylinder** 定义
+
+## 分析总路线
+
+### 周期线
+
+用于：
+
+- target cylinder
+- illusion
+- uncontrolled（若通过 relaxed 门）
+
+目标是回答：
+
+- illusion 是否重组了与 target 周期 signature 最相关的结构
+- force-related structures、action-related structures 与 signature-related structures 是否对齐
+- illusion 是否比 uncontrolled 更接近 target 的相关结构通道
+
+### 稳态线
+
+用于：
+
+- cloak
+- target channel
+
+目标是回答：
+
+- cloak 是否把均值尾迹重构为接近槽道基流
+- cloak 是否显著压低脉动和回流区
+- cloak 的控制幅值与感知改善之间是否具有合理对应关系
+
+## 数据要求
+
+### 必须导出的数据
+
+| 数据组 | 记号 | 说明 |
+|---|---|---|
+| 流场快照 | \(u(x,y,t_n), v(x,y,t_n)\) | 全域 2D 快照 |
+| 总力 | \(F_x(t_n), F_y(t_n)\) | 所有周期 case 必须记录，包括 target cylinder |
+| 动作 | \(\Omega_i(t_n)\) | 三圆柱各自转速 |
+| 观测 | \(s(t_n)\in\mathbb R^6\) | 三个传感器各含 \(u,v\) |
+| 目标观测 | \(s_{tar}(t_n)\) | illusion 时需要；cloak 时为槽道基流参考 |
+| 元数据 | `meta.json` | Re 口径、采样步长、case 标签、steady/periodic 标签 |
+
+### 当前不要求的数据
+
+| 数据 | 说明 |
+|---|---|
+| 单圆柱力矩 \(M_{z,i}\) | 当前阶段不记录 |
+| 单圆柱受力分解 | 当前阶段不要求 |
+| 控制功率 | 因缺少力矩，当前阶段不做 |
+
+## 采样原则的关键修正
+
+这是本轮最重要的修正之一。
+
+### 不再把 \(T_{ref}\) 的“样本数”当成固定采样标准
+
+`target cylinder` 在某一次采样设置下测得的 \(T_{ref}\approx 18.75\) 样本/周期，只反映当时的 `SAMPLE_INTERVAL`，**不应该被当成所有 case 的固定原始采样密度标准**。
+
+真正固定的只有两件事：
+
+1. **参考频率 / 参考周期**
+   
+   \[
+   f_{ref},\qquad T_{ref}=1/f_{ref}
+   \]
+
+2. **标准相位网格**
+   
+   \[
+   \phi_m = 2\pi m/24,\qquad m=0,1,\ldots,23
+   \]
+
+也就是说：
+
+- \(T_{ref}\) 用来定义统一相位坐标系
+- **原始采样频率应按每个 case 自适应设置**，目标是让每个 case 在原始数据里就尽量接近 24 点/周期，而不是先粗采样再强行插值到 24
+
+### 当前采样策略
+
+下一轮对每个周期 case 采用 **两步式采样**。
+
+#### Step 1
+
+传感器先导采样
+
+先用较轻的数据模式跑一个 pilot：
+
+- 高频保存传感器、总力、动作
+- 不急着保存全场
+- 估计该 case 的 \(f_{case}\)、\(T_{case}\)、\(\mathrm{CV}_T\)
+
+#### Step 2
+
+按 case 自适应设置场采样间隔
+
+对于每个通过周期门的 case，设置该 case 的场采样间隔，使其原始场数据满足：
+
+\[
+N_{raw/cycle} \approx 20\text{--}24
+\]
+
+推荐用：
+
+\[
+\text{SAMPLE\_INTERVAL}_{field} \approx T_{case}/24
+\]
+
+若只能取整数步长，则选择最接近 24 点/周期的整数。
+
+### 原始采样密度门槛
+
+为了避免对过稀疏的原始数据做过强插值，定义每个 case 的原始每周期样本数：
+
+\[
+N_{raw/cycle} = T_{case}/\text{SAMPLE\_INTERVAL}_{field}
+\]
+
+并采用如下门槛：
+
+| 等级 | 条件 | 处理 |
+|---|---|---|
+| ideal | \(N_{raw/cycle} \ge 20\) | 直接进入相位重采样 |
+| acceptable | \(16 \le N_{raw/cycle} < 20\) | 允许进入，但记录告警 |
+| relaxed | \(12 \le N_{raw/cycle} < 16\) | 只作辅助 case，不进主 reference basis |
+| reject | \(N_{raw/cycle} < 12\) | 不做 24 点/周期相位 CCD，必须重采 |
+
+### 插值比例门槛
+
+定义插值放大倍数：
+
+\[
+\rho_{interp} = 24 / N_{raw/cycle}
+\]
+
+采用如下自审规则：
+
+| 等级 | 条件 | 解释 |
+|---|---|---|
+| ideal | \(\rho_{interp} \le 1.2\) | 基本不依赖插值 |
+| acceptable | \(1.2 < \rho_{interp} \le 1.5\) | 可接受 |
+| borderline | \(1.5 < \rho_{interp} \le 2.0\) | 可做辅助分析，但需谨慎解释 |
+| reject | \(\rho_{interp} > 2.0\) | 不进入主 phase-based CCD |
+
+因此：
+
+- 18.75 → 24 对应 \(\rho_{interp}\approx 1.28\)，可接受
+- 12.4 → 24 对应 \(\rho_{interp}\approx 1.94\)，属于 borderline，若能重采应优先重采
+
+### 当前原则
+
+下一轮不再默认所有 case 都用同一个 `SAMPLE_INTERVAL`。对于周期线，允许按 case 单独设置场采样间隔，只要最终都重采样到同一个 24 相位网格即可。
+
+## 周期检测与相位重采样
+
+### 标准频率
+
+固定使用 **target cylinder 在 \(Re=100\) 下的脱涡频率** 作为标准频率：
+
+\[
+f_{ref}
+\]
+
+对应标准周期：
+
+\[
+T_{ref}=1/f_{ref}
+\]
+
+标准相位网格为：
+
+\[
+\phi_m = 2\pi m/24,\qquad m=0,1,\ldots,23
+\]
+
+### 周期检测建议顺序
+
+对每个周期 case，按以下顺序检测主周期：
+
+1. **首选信号**：中心传感器的横向速度或最干净的传感器分量
+2. **备选信号**：总升力 \(F_y\)
+3. **再次备选**：POD 前两阶系数中的主振荡分量
+
+对首选信号先做：
+
+- 去均值
+- 必要时做轻微平滑
+- FFT 找主频初值 \(f_{dom}\)
+- 用峰值间距或零交叉进一步修正周期
+
+### 周期稳定性与准入门
+
+设检测到连续周期长度 \(T_n\)，定义：
+
+\[
+\mathrm{CV}_T = \frac{\mathrm{std}(T_n)}{\mathrm{mean}(T_n)}
+\]
+
+再定义相对参考频率偏差：
+
+\[
+\delta_f = \frac{|f_{case}-f_{ref}^{scaled}|}{f_{ref}^{scaled}}
+\]
+
+其中 \(f_{ref}^{scaled}\) 应按该 case 的来流速度或无量纲 Strouhal 一致性换算，而不是机械使用某一组物理条件下测得的原始 \(f_{ref}\)。
+
+采用如下准入门：
+
+| gate | 条件 | 用途 |
+|---|---|---|
+| strict | \(\mathrm{CV}_T \le 0.10\) 且 \(\delta_f \le 0.10\) | 可进主周期线与主基底 |
+| relaxed | \(\mathrm{CV}_T \le 0.12\) 且 \(\delta_f \le 0.20\) | 可作辅助周期 case |
+| auxiliary | 不满足 strict / relaxed 但仍有明显周期 | 只做投影或基线比较 |
+| reject | 周期不稳或采样过稀 | 不进入 phase-based CCD |
+
+### 代表周期的选取
+
+在足够长的前置稳定时间后，只截取 **4 个代表周期**。推荐方式：
+
+- 先找到一个稳定窗口
+- 在该窗口内选 4 个连续周期
+- 若连续 4 周期不稳定，则选最接近 \(f_{ref}^{scaled}\) 的 4 个周期
+- 若仍不满足门槛，则该 case 不进入主周期线
+
+### 周期起点的统一定义
+
+每个周期必须有统一的相位起点。优先使用参考信号的：
+
+- **上升穿零点且导数为正**
+
+若该定义不稳，再退回使用局部峰值作为周期起点。但同一个 case 内必须保持一致。
+
+### 相位重采样
+
+对每个选中的周期，令该周期起点与终点分别对应相位 0 和 \(2\pi\)。对该周期内的全部数据做线性或三次样条插值，重采样到 24 个标准相位点：
+
+\[
+\phi_m = 2\pi m/24
+\]
+
+每个周期都得到：
+
+- 24 帧流场快照
+- 24 个传感器观测
+- 24 个总力值
+- 24 个动作值
+
+4 个周期共得到 96 个标准相位样本。
+
+### 相位重采样后的质量检查
+
+每个 case 重采样后必须输出两个自审量：
+
+1. 重采样前后主频偏差
+2. 相位平均传感器回线是否出现明显跳变或折返
+
+若重采样后出现显著畸变，则该 case 只能降级为 auxiliary，不进入主周期线。
+
+## 参考 POD 基底
+
+### 当前原则
+
+当前阶段不再使用 target-only POD，而使用：
+
+- **reference POD basis = target cylinder + illusion**
+
+uncontrolled 只投影，不默认并入基底训练。
+
+### 适用范围
+
+参考 POD 只在周期线构造，不把 cloak 和 target channel 混进来。
+
+### POD 截断
+
+由于总样本数仍然有限，优先测试：
+
+\[
+r = 6, 8, 10
+\]
+
+不建议当前阶段上 20 阶以上。
+
+## Reduced CCD 的定义
+
+保留前 \(r\) 阶 POD 后，定义系数矩阵：
+
+\[
+A_r =
+\begin{bmatrix}
+a_1(t_1) & \cdots & a_1(t_N) \\
+\vdots & & \vdots \\
+a_r(t_1) & \cdots & a_r(t_N)
+\end{bmatrix}
+\in \mathbb R^{r\times N}
+\]
+
+若 observable 为 \(y(t)\in\mathbb R^m\)，则对每个时刻 \(t_i\) 构造相位窗口向量：
+
+\[
+\mathbf p_i=
+\begin{bmatrix}
+y(t_i+\tau_1) \\
+y(t_i+\tau_2) \\
+\vdots \\
+y(t_i+\tau_Q)
+\end{bmatrix}
+\in \mathbb R^{mQ}
+\]
+
+于是：
+
+\[
+P=[\mathbf p_1,\mathbf p_2,\ldots,\mathbf p_N] \in \mathbb R^{mQ\times N}
+\]
+
+实际计算前先对 \(P\) 与 \(A_r\) 做逐行标准化，定义为 \(\tilde P\) 与 \(\tilde A_r\)。随后构造 reduced CCD 矩阵：
+
+\[
+C = \frac{1}{N\sqrt{Q}} \tilde P\,\tilde A_r^{\top}
+\]
+
+对其做 SVD：
+
+\[
+C = R \Sigma W^{\top}
+\]
+
+其中：
+
+- \(W\) 的列向量给出 POD 子空间中的 CCD 方向
+- \(\sigma_k\) 表示第 \(k\) 个相关结构与 observable 的相关强度
+- CCD 空间模态由 POD 模态线性组合得到
+
+\[
+\psi_k = \sum_{j=1}^{r} W_{jk}\,\phi_j
+\]
+
+- CCD 时间系数定义为
+
+\[
+z_k(t)=W_{:,k}^{\top}a_r(t)
+\]
+
+## 当前阶段的三类 CCD
+
+### force-CCD
+
+这是当前阶段最重要、也最可跨 case 比较的 CCD。定义总体受力 observable：
+
+\[
+y_F(t)=
+\begin{bmatrix}
+F_x(t) \\
+F_y(t)
+\end{bmatrix}
+\]
+
+适用 case：
+
+- target cylinder
+- illusion
+- uncontrolled（若通过 relaxed 门）
+
+优先回答：
+
+- illusion 是否比 uncontrolled 更接近 target 的 force-related structures
+- action-related structures 是否与 force-related structures 对齐
+
+### action-CCD
+
+动作 observable 只在 illusion case 上有意义：
+
+\[
+y_{act}(t)=
+\begin{bmatrix}
+\Omega_1(t) \\
+\Omega_2(t) \\
+\Omega_3(t)
+\end{bmatrix}
+\]
+
+优先回答：
+
+- illusion 控制主要依赖哪些低维结构自由度
+- action-related structures 是否与 force-related structures 对齐
+
+### signature-CCD
+
+目标相关的 observable 只在 illusion 线上定义。令：
+
+\[
+e_s(t)=s(t)-s_{tar}(t)
+\]
+
+然后做相位偏移版本：
+
+\[
+y_{sig}(t)=e_s(t+\tau_c)
+\]
+
+当前阶段必须至少扫描三组：
+
+- \(\tau_c = 0\)
+- \(\tau_c = \tau_c^{geom}\)
+- \(\tau_c = \tau_c^{corr}\)
+
+目标是判断 signature-related structures 更像同步耦合，还是更像带相位偏移的 downstream response。
+
+## 标准化规范
+
+CCD 的 observable 与 POD 系数都必须标准化。否则量纲较大的分量会主导分解结果。
+
+### observable 矩阵标准化
+
+设 observable 堆叠后形成矩阵 \(P\)。对 \(P\) 的每一行做 z-score 标准化：
+
+\[
+\tilde P_{j,:}=\frac{P_{j,:}-\mu_j}{\sigma_j+\epsilon}
+\]
+
+其中 \(\mu_j\)、\(\sigma_j\) 为训练集统计量，\(\epsilon\) 为防止零方差的极小正数。若某一行 \(\sigma_j\) 极小，则直接剔除该分量。
+
+### POD 系数矩阵标准化
+
+对保留的 POD 系数矩阵 \(A_r\) 的每一行同样标准化：
+
+\[
+\tilde A_{k,:}=\frac{A_{k,:}-\bar a_k}{s_k+\epsilon}
+\]
+
+测试集必须使用训练集的均值和标准差做标准化，不允许单独对测试集重新拟合统计量。
+
+## 当前阶段的核心指标
+
+### 周期线基础指标
+
+| 指标 | 含义 |
+|---|---|
+| \(f_{dom}\) | 主频 |
+| \(\delta_f\) | 相对参考频率偏差 |
+| \(\mathrm{CV}_T\) | 周期波动系数 |
+| \(\overline{E_s}\) | 传感器误差时间均值 |
+| \(E_{phase}\) | 相位平均误差 |
+| \(\eta_{RMS}\) | 脉动强度比 |
+| \(N_{raw/cycle}\) | 原始每周期样本数 |
+| \(\rho_{interp}\) | 插值放大倍数 |
+
+### POD 指标
+
+| 指标 | 含义 |
+|---|---|
+| \(E_{95}\) | 达到 95% 能量所需模态数 |
+| \(\gamma_{POD}(m)\) | 前 \(m\) 阶累计能量占比 |
+| \(D_{POD}\) | case 在前两阶相图中的中心距离 |
+
+### CCD 指标
+
+| 指标 | 含义 |
+|---|---|
+| \(\gamma_{CCD}(m)\) | 前 \(m\) 阶 CCD 累计相关强度占比 |
+| \(m_{80}^{CCD}\) | 到 80% 相关强度所需模态数 |
+| \(\bar R^2_{LOCO,force}(m)\) | 留一周期交叉验证下 force 的平均测试 \(R^2\) |
+| \(\bar R^2_{LOCO,act}(m)\) | 留一周期交叉验证下 action 的平均测试 \(R^2\) |
+| \(\bar R^2_{LOCO,sig}(m)\) | 留一周期交叉验证下 signature 的平均测试 \(R^2\) |
+| \(\sigma_{R^2,LOCO}(m)\) | 上述 \(R^2\) 的标准差 |
+| \(\rho_{max}(z_k,\Omega_i)\) | 结构与动作的最大相关 |
+| \(\rho_{max}(z_k,F_x),\rho_{max}(z_k,F_y)\) | 结构与总力的最大相关 |
+| \(\rho_{max}(z_k,e_s)\) | 结构与误差的最大相关 |
+| \(O_k^{(A,B)}\) | 第 \(k\) 个 CCD 方向的模态重合度 |
+
+其中：
+
+\[
+\gamma_{CCD}(m)=\frac{\sum_{k=1}^{m}\sigma_k^2}{\sum_{k}\sigma_k^2}
+\]
+
+\[
+O_k^{(A,B)} = \left| w_k^{(A)\top} w_k^{(B)} \right|
+\]
+
+## 稳态线指标
+
+对 cloak 与 target channel，不看 CCD 成败，而看是否成功恢复稳态背景流。
+
+| 指标 | 用途 |
+|---|---|
+| \(E_{mean}\) | 均值流场相对误差 |
+| \(E_{sensor}^{mean}\) | 传感器均值误差 |
+| \(\eta_{fluc}\) | 脉动抑制率 |
+| \(L_r\) | 回流区长度 |
+| \(A_r\) | 回流区面积 |
+| \(\sigma_F\) | 总力波动标准差 |
+| \(J_\Omega^{rms}\) | 动作 RMS 总量 |
+| \(\eta_{cloak}^{obs}\) | 单位控制幅值带来的感知改善 |
+
+## 当前阶段的执行顺序
+
+1. **补 target cylinder 的 force 数据**
+2. **重跑 force-CCD**，并比较：
+   - \(O_k(illusion, target)\)
+   - \(O_k(uncontrolled, target)\)
+3. **对 signature-CCD 做 \(\tau_c=0/geom/corr\) 三点扫描**
+4. **补连续块测试**：前 2 周期训练、后 2 周期测试
+5. **补 cloak 稳态线指标**：\(E_{mean}, E_{sensor}^{mean}, \eta_{fluc}, L_r, A_r, \eta_{cloak}^{obs}\)
+6. **保持 reference POD basis = target + illusion**
+7. **uncontrolled 只作辅助投影，暂不并入主基底训练**
+
+## 当前阶段暂不做的内容
+
+- 不做多 Reynolds 数统一分析
+- 不做上游扰动 case
+- 不做 checkpoint/restore 优化
+- 不做白箱控制律
+- 不在 cloak 上强行做 CCD
+- 不把“CCD 优于 POD”写成正式结论
+
+## 当前阶段的完成标准
+
+本轮工作完成后，至少应满足：
+
+1. target cylinder 拥有完整的 force 数据
+2. force-CCD 能真正比较 target / illusion / uncontrolled 三者
+3. signature-CCD 完成 \(\tau_c\) 三点扫描
+4. 同时拥有 LOCO 与连续块测试两套 \(R^2\) 验证
+5. cloak 稳态线给出完整恢复指标
+6. 输出的是指标 + 模态，而不是单纯图像
+7. 至少能形成一个更硬的机制判断：
+   - illusion 是否比 uncontrolled 更接近 target 的 force-related 或 signature-related structure channel
+
+满足这七条后，再进入下一阶段：
+
+- 讨论是否让 uncontrolled 并入基底
+- 讨论 `obs -> z -> act` 白箱控制链
+- 讨论更严格的 whitening / PCD-style 版本

src/CCD_analysis/configs/config_cuda.json

@@ -0,0 +1,9 @@
+{
+    "multi_gpu": false,
+    "gpu_connection": "NVLink",
+    "required_cuda_capability": "7.0",
+    "threads_per_block": 128,
+    "X_1U": 128,
+    "Y_1U": 32,
+    "Z_1U": 1
+}

src/CCD_analysis/configs/config_flowfield.json

@@ -0,0 +1,13 @@
+{
+    "data_type": "FP32",
+    "dimensionality": 2,
+    "lattice": 9,
+    "field_dim_in_U": [10, 16, 1],
+    "viscosity": 0.004,
+    "velocity": 0.01,
+    "boundary_conditions": {
+        "x": ["parabolic", "outflow"],
+        "y": ["noslip", "noslip"],
+        "z": ["none", "none"]
+    }
+}

src/CCD_analysis/knowledge.md

@@ -0,0 +1,184 @@
+# CCD Analysis: Lessons Learned & Knowledge Base
+
+## 项目全局知识
+
+### Re 数定义
+- `Re_D` = U0 * D / nu, where D = 20 (single cylinder diameter)
+- `Re` (code) = U0 * 2D / nu, where 2D = 40
+- Default Re=100 (code) <-> Re_D=50
+- Formula: nu = U0 * 2D / Re_code = 0.01 * 40 / 100 = 0.004
+
+### 网格和物理参数
+- Grid: 1280 x 512, D2Q9, MRT
+- L0 = 20 (base length unit)
+- U0 = 0.01 (inlet center velocity, lattice units)
+- Inlet: parabolic profile (Zou-He local)
+- Walls: bounce-back (no-slip)
+- Outlet: NEQ extrapolation
+
+### 核心规则：添加顺序决定 obs 布局
+
+**这是整个项目中最容易被搞错的地方。** Legacy FlowField 的 `obs` 数组的内容完全由对象添加顺序决定，不同脚本可能使用不同的添加顺序。
+
+**`legacy_env_karman_cloak_standard.py` (7 objects, 训练 env):**
+添加顺序: dist_cyl(0) -> s0(1) -> s1(2) -> s2(3) -> front(4) -> bottom(5) -> top(6)
+obs[2:14] = [s0_ux,uy, s1_ux,uy, s2_ux,uy, front_fx,fy, bottom_fx,fy, top_fx,fy]
+         = [sensors(6), forces(6)]
+用 obs[2:14] 跳过了 dist_cyl 的 2 个值。
+
+**`legacy_env_imit.py` (6 objects, 训练 env):**
+添加顺序: s0(0) -> s1(1) -> s2(2) -> front(3) -> bottom(4) -> top(5)
+obs[0:12] = [s0_ux,uy, s1_ux,uy, s2_ux,uy, front_fx,fy, bottom_fx,fy, top_fx,fy]
+         = [sensors(6), forces(6)]
+
+**`uni_test.ipynb` (推理脚本, 可能使用不同添加顺序):**
+- 对于 Karman cloak: restore DDF + add dist_cyl → obs[0:12] 的布局取决于 DDF 保存时的状态
+- 对于 Illusion: 单独 env, 添加顺序取决于代码
+
+**关键教训: 每次处理 obs 时必须先查看对应脚本中的添加顺序。**
+
+### 旧 API (LegacyCelerisLab) 要点
+- `flow_field.run(N, action_array)` 返回的 `obs` 已经是 N 步每步平均
+- `action_array` 长度 = 对象数量, sensor 的 action slot 被忽略
+- `flow_field.run()` 内部有指数平滑 (weight=0.1)
+- `save_ddf()/restore_ddf()/apply_ddf()` 用于 checkpoint
+- 需要 `context.push()/pop()` 管理 PyTorch + PyCUDA 上下文冲突
+
+### Legacy 环境标准初始化流程
+1. 创建 FlowField
+2. 添加对象(传感器、圆柱)
+3. 稳定 4*NX/U0 步
+4. 录制 target 信号 (FIFO_LEN 步)
+5. 添加 pinball 圆柱 (延续使用同一个 FlowField)
+6. 再次稳定, checkpoint
+7. 零动作跑 FIFO_LEN 步, 计算 norm
+8. 恢复 checkpoint, 偏置动作跑 FIFO_LEN 步, 保存 FIFO 状态
+9. reset = 恢复 checkpoint + 恢复 FIFO
+
+### Cloak (Karman) 环境参数
+- Model: d1a3o12_re100.zip (7 objects: dist + 3 sensors + 3 pinball)
+- S_DIM = 12, A_DIM = 3
+- SAMPLE_INTERVAL = 800, FIFO_LEN = 150, CONV_LEN = 30
+- Action: temp[4:7] = (action * 8 + [0, -4, 4]) * U0
+- Norm: force_norm_fact = 6 * max(|temp_states[:, 6:12]|)
+- Obs: hstack([forces_norm, sens_norm]) → 12-dim
+  - forces_norm = obs_slice[6:12] / force_norm_fact  (3 pinball forces)
+  - sens_norm = (obs_slice[0:6] - sens_deviation) / sens_norm_fact  (3 sensors)
+- Reward:
+  - cd = (forces[0] + forces[2] + forces[4]) / 3
+  - cl = (forces[1] + forces[3] + forces[5]) / 3
+  - reward_cd = exp(-|cd * 20|)
+  - reward_cl = exp(-|cl * 80|)
+  - reward_sim = exp(-10 * |similarities - 1|)
+  - reward = min(0.3*reward_cd + 0.4*reward_cl + 0.3*reward_sim, 1.0)
+
+### Illusion (Imit) 环境参数
+- Model: d1a3o14_250525_imit_1L_2U_600S.zip (6 objects: 3 sensors + 3 pinball)
+- S_DIM = 14, A_DIM = 3
+- SAMPLE_INTERVAL = 600, FIFO_LEN = 150, CONV_LEN = 36
+- Action: temp[3:6] = (action * 8 + [0, -2, 2]) * U0
+- U0 = 0.02 (2U), nu = 0.008
+- Target cylinder: center=(20*L0, CENTER_Y), radius=L0(对1L模型)
+- 目标传感器: x=30*L0
+- Pinball: front=(19*L0, CENTER_Y), bottom=(20.3*L0, CENTER_Y+0.75*L0),
+  top=(20.3*L0, CENTER_Y-0.75*L0)
+- Norm: force_norm_fact = 6 * max(|temp_states[:, 6:12]|)
+- Obs: hstack([forces_norm, sens_norm, target_cd_norm, target_cl_norm]) → 14-dim
+  - 注意: forces_norm 使用 SUM 不是 mean (cd = f0+f2+f4)
+- Reward:
+  - cd = forces[0] + forces[2] + forces[4]  (SUM)
+  - cl = forces[1] + forces[3] + forces[5]  (SUM)
+  - 从 harmonics 重构 target_cd, target_cl
+  - reward_cd = exp(-|(cd - target_cd) * 10|)
+  - reward_cl = exp(-|(cl - target_cl) * 10|)
+  - reward_sim = exp(-10 * |similarities - 1|)
+  - reward = min(0.3*reward_cd + 0.3*reward_cl + 0.4*reward_sim, 1.0)
+
+### Cloak vs Illusion 关键差异
+| 方面 | Cloak | Illusion |
+|------|-------|---------|
+| S_DIM | 12 | 14 |
+| 观测 | [forces(6), sens(6)] | [forces(6), sens(6), target_cd, target_cl] |
+| cd/cl 计算 | forces/3 (mean of 3) | sum of 3 (no /3) |
+| cd reward | exp(-|cd * 20|) | exp(-|(cd-target_cd) * 10|) |
+| cl reward | exp(-|cl * 80|) | exp(-|(cl-target_cl) * 10|) |
+| 权重 | cd=0.3, cl=0.4, sim=0.3 | cd=0.3, cl=0.3, sim=0.4 |
+| Action bias | [0, -4, 4] | [0, -2, 2] |
+| SAMPLE_INTERVAL | 800 | 600 |
+| CONV_LEN | 30 | 36 |
+| 目标信号 | 传感器时序 (6通道) | 传感器+力 (8通道) + 谐波分解 |
+| DTW lag | target[:,1] vs fifo[:,1] | target[:,3] vs fifo[:,1] |
+
+### Norm 计算 (通用)
+```python
+temp_states = np.array(fifo)  # (FIFO_LEN, 12), each = obs_slice
+force_norm_fact = 6 * max(|temp_states[:, 6:12]|)  # 力的最大波动 * 6
+sens_deviation[i] = mean(temp_states[:, i])         # 传感器均值
+sens_norm_fact[i] = 5 * max(|temp_states[:, i] - deviation|)  # 传感器波动 * 5
+```
+注意: force_norm_fact 和 sens 统计从 obs_slice 的哪一部分取值取决于添加顺序。
+
+### DTW 相似度计算 (通用模式)
+1. 从 target_states[CONV_LEN:2*CONV_LEN, lag_channel] 取参考段
+2. 从 fifo[-CONV_LEN:, lag_channel] 取当前段
+3. 互相关计算 lag
+4. 对 6 个传感器通道, 用 lag 补偿后算 DTW: 1 - distance/len
+5. 结果平均
+
+### Strouhal 数
+- 本项目 St=0.267 (抛物线入口 + no-slip 壁面)
+- 高于经典圆柱的 0.165, 因为 7.8% 阻塞比 + 抛物线入口
+- 用 St 做无量纲一致性检查: f_expected = St * U0 / D
+
+### 涡量图
+- 正确公式: ω_z = dv/dx - du/dy
+- ux.shape = (NY, NX) = (512, 1280)
+- 实现: `omega = np.gradient(uy, axis=1) - np.gradient(ux, axis=0)`
+  - axis=0 是 y 方向, axis=1 是 x 方向
+  - grad(uy, axis=1) = duy/dx, grad(ux, axis=0) = dux/dy
+
+---
+
+## 经验教训总结
+
+### 第一大教训: 不验证就做分析 = 无效
+之前没有验证 PPO 控制质量就直接做 CCD 分析, 导致分析可能基于错误的流场。
+**必须先验证每个 case 的 reward/similarity 达到论文水平, 再进入分析。**
+
+### 第二大教训: 添加顺序决定一切
+obs 布局完全由对象添加顺序决定。不能假设 obs[i] 的含义, 必须检查每个脚本中对象的实际添加顺序。
+
+### 第三大教训: 环境初始化必须完全复现
+Legacy 环境在 __init__ 中做了大量工作: target 录制、谐波分析(illusion)、norm 计算、偏置 FIFO、checkpoint。任何一步遗漏都会导致 PPO 推理失败。
+
+### 第四大教训: uni_test 是最可信的参考
+uni_test.ipynb 是用户手动验证过的推理脚本, 它的 obs 处理和 norm 逻辑应作为最高优先级参考。
+
+### 第五大教训: 存储管理与采样率
+早期存储了 400 帧全场快照 (~2GB), 导致后处理缓慢。应先用高频传感器时序做周期检测, 确定代表周期后再存场。
+自适应采样率 (使原始采样 ~24 点/周期) 比统一 SAMPLE_INTERVAL 更合理。
+
+### 工作流建议
+1. 数据采集: 用 legacy 环境 + norm, 先跑短试(50步)验证 reward/similarity
+2. 再跑完整 rollout (500步), 保存传感器/力/动作为高频, 场为主动选择的窗口
+3. 周期检测 + 相位重采样 (纯 CPU)
+4. POD + CCD (纯 CPU)
+5. 每一步都输出数值指标, 不要只看图
+
+---
+
+## 工具函数状态清单
+
+| 文件 | 状态 | 说明 |
+|------|------|------|
+| `cfg.py` | 可靠 | 路径和常量, 无 CFD 依赖 |
+| `utils.py` | 可靠 | CFD 加载/场读取 |
+| `analysis_utils.py` | 可靠 | 周期检测、POD、CCD、重采样(修正了涡量公式) |
+| `phase0_standard_freq.py` | 可靠 | 已验证与 Phase 0 一致 |
+| `phase1_collect.py` | 部分可靠 | Illusion 的 norm 和 PPO 推理已验证, Cloak 的采集已验证 |
+| `phase2_resample.py` | 可靠 | 周期检测和重采样已验证 |
+| `phase3_pod.py` | 可靠 | POD 计算已验证 |
+| `phase4_ccd.py` | 部分可靠 | CCD 算法正确, 但 action-CCD 的 corr 值为 0 需排查 |
+| `phase5_steady.py` | 有问题 | E_mean_uy 因分母过小爆炸, eta_fluc 因环境不匹配错误 |
+| `validate_control.py` | 有问题 | 多次迭代仍未能复现论文水平的相似度 |
+| `compile_results.py` | 可靠 | 无 CFD 依赖, 纯报告脚本 |

src/CCD_analysis/scripts/__init__.py

@@ -0,0 +1 @@
+# CCD_analysis scripts package

src/CCD_analysis/scripts/analysis_utils.py

@@ -0,0 +1,270 @@
+# CCD_analysis/scripts/analysis_utils.py
+"""CPU-only analysis utilities for Phase 2, 3, 4.
+
+No pycuda or LegacyCelerisLab dependency — can run with plain python3.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Tuple
+
+import numpy as np
+
+
+# ---------------------------------------------------------------------------
+# Period detection helpers
+# ---------------------------------------------------------------------------
+
+def detect_dominant_frequency(
+    signal: np.ndarray, sample_dt: float
+) -> Tuple[float, float, float]:
+    """Detect dominant frequency via FFT.
+
+    Parameters
+    ----------
+    signal : 1D array
+        Time series to analyse.
+    sample_dt : float
+        Time between samples.
+
+    Returns
+    -------
+    f_dom, period, peak_power
+    """
+    n = len(signal)
+    if n < 16:
+        return 0.0, 0.0, 0.0
+    y = signal - np.mean(signal)
+    window = np.hanning(n)
+    spec = np.abs(np.fft.rfft(y * window)) ** 2
+    freqs = np.fft.rfftfreq(n, d=sample_dt)
+    idx = 1 + np.argmax(spec[1:])
+    f_dom = float(freqs[idx])
+    period = 1.0 / f_dom if f_dom > 0 else 0.0
+    return f_dom, period, float(spec[idx])
+
+
+def detect_cycle_stability(
+    signal: np.ndarray, sample_dt: float
+) -> Tuple[float, float, List[float]]:
+    """Detect cycle lengths and compute stability metrics.
+
+    Uses rising zero-crossings of (signal - mean) for cycle detection.
+
+    Returns (cv_T, mean_T, cycle_lengths).
+    """
+    y = signal - np.mean(signal)
+    sign = np.sign(y)
+    crossings = np.where((sign[:-1] < 0) & (sign[1:] > 0))[0]
+    if len(crossings) < 2:
+        return 0.0, 0.0, []
+    cycle_lengths = np.diff(crossings).astype(float) * sample_dt
+    if len(cycle_lengths) < 2:
+        return 0.0, float(cycle_lengths[0]) if len(cycle_lengths) > 0 else 0.0, cycle_lengths.tolist()
+    mean_T = float(np.mean(cycle_lengths))
+    std_T = float(np.std(cycle_lengths))
+    cv_T = std_T / mean_T if mean_T > 0 else 0.0
+    return cv_T, mean_T, cycle_lengths.tolist()
+
+
+# ---------------------------------------------------------------------------
+# Phase resampling
+# ---------------------------------------------------------------------------
+
+def phase_resample(
+    data: np.ndarray,
+    cycle_starts: List[int],
+    n_pts: int = 24,
+) -> np.ndarray:
+    """Resample a multi-channel signal to uniform phase points per cycle.
+
+    Uses piecewise linear interpolation (no scipy dependency).
+
+    Parameters
+    ----------
+    data : (T, C) ndarray
+        Multi-channel time series.
+    cycle_starts : list of int
+        Indices where each cycle starts.
+    n_pts : int
+        Number of phase points per cycle.
+
+    Returns
+    -------
+    resampled : (n_cycles, n_pts, C) ndarray
+    """
+    n_cycles = len(cycle_starts) - 1
+    if n_cycles < 1:
+        raise ValueError("Need at least 2 cycle starts")
+
+    if data.ndim == 1:
+        data = data[:, None]
+
+    C = data.shape[1]
+    out = np.zeros((n_cycles, n_pts, C), dtype=np.float64)
+
+    for c in range(n_cycles):
+        i_start = cycle_starts[c]
+        i_end = cycle_starts[c + 1]
+        segment = data[i_start:i_end + 1]
+        seg_len = len(segment)
+        if seg_len < 2:
+            continue
+
+        # Linear interpolation from original phase grid to uniform grid
+        old_idx = np.linspace(0, 1, seg_len)
+        new_idx = np.linspace(0, 1, n_pts, endpoint=False)
+
+        for ch in range(C):
+            out[c, :, ch] = np.interp(new_idx, old_idx, segment[:, ch])
+
+    return out
+
+
+# ---------------------------------------------------------------------------
+# POD
+# ---------------------------------------------------------------------------
+
+def compute_pod(
+    snapshot_matrix: np.ndarray
+) -> Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
+    """Compute POD from snapshot matrix.
+
+    Parameters
+    ----------
+    snapshot_matrix : (n_points, n_snapshots) ndarray
+        Each column is one flattened snapshot.
+
+    Returns
+    -------
+    mean_field : (n_points,)
+    modes : (n_points, min(n_points, n_snapshots))
+    singular_values : (min_dim,)
+    coefficients : (min_dim, n_snapshots)
+    """
+    mean_field = np.mean(snapshot_matrix, axis=1)
+    Q = snapshot_matrix - mean_field[:, None]
+    U, s, Vt = np.linalg.svd(Q, full_matrices=False)
+    coefficients = np.diag(s) @ Vt  # (min_dim, N)
+    return mean_field, U, s, coefficients
+
+
+def cumulative_energy(singular_values: np.ndarray) -> np.ndarray:
+    """Return cumulative energy fraction."""
+    e = singular_values ** 2
+    return np.cumsum(e) / np.sum(e)
+
+
+def e95_index(cumulative_energy: np.ndarray) -> int:
+    """Return first index where cumulative energy >= 95%."""
+    return int(np.searchsorted(cumulative_energy, 0.95) + 1)
+
+
+# ---------------------------------------------------------------------------
+# CCD (reduced, Lyu23-inspired)
+# ---------------------------------------------------------------------------
+
+def compute_reduced_ccd(
+    pod_coeffs: np.ndarray,
+    observable: np.ndarray,
+    Q_delay: int = 12,
+) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Compute reduced CCD in POD coefficient space.
+
+    Parameters
+    ----------
+    pod_coeffs : (r, N) ndarray
+        Standardized POD coefficients (r modes, N time steps).
+    observable : (m, N) ndarray
+        Standardized observable (m channels, N time steps).
+    Q_delay : int
+        Number of delay steps.
+
+    Returns
+    -------
+    W : (r, min(r, m*Q_delay))
+    sigma : (min_dim,)
+    z : (min_dim, N)
+    """
+    N = pod_coeffs.shape[1]
+    m = observable.shape[0]
+
+    # Build delay matrix: for each time step, P includes Q_delay shifted versions
+    half = Q_delay // 2
+    rows = []
+    for shift in range(-half, half + 1):
+        shifted = np.roll(observable, -shift, axis=1)
+        if shift < 0:
+            shifted[:, shift:] = 0.0
+        elif shift > 0:
+            shifted[:, :-shift] = 0.0
+        rows.append(shifted)
+    P = np.vstack(rows)  # (m*Q_delay, N)
+
+    # Standardize P and pod_coeffs rows (z-score)
+    P_mean = np.mean(P, axis=1, keepdims=True)
+    P_std = np.std(P, axis=1, keepdims=True) + 1e-12
+    P_z = (P - P_mean) / P_std
+
+    A_mean = np.mean(pod_coeffs, axis=1, keepdims=True)
+    A_std = np.std(pod_coeffs, axis=1, keepdims=True) + 1e-12
+    A_z = (pod_coeffs - A_mean) / A_std
+
+    # CCD matrix
+    C = P_z @ A_z.T / (N * np.sqrt(float(Q_delay)))
+
+    # SVD
+    R, s, Wt = np.linalg.svd(C, full_matrices=False)
+    W = Wt.T  # (r, min_dim)
+
+    # CCD coefficients
+    z = W.T @ A_z  # (min_dim, N)
+
+    return W, s, z
+
+
+# ---------------------------------------------------------------------------
+# Stack velocity fields into snapshot matrix
+# ---------------------------------------------------------------------------
+
+def stack_velocity_fields(
+    ux_fields: List[np.ndarray],
+    uy_fields: List[np.ndarray],
+) -> np.ndarray:
+    """Stack list of (ux, uy) field pairs into snapshot matrix.
+
+    Each field is flattened, ux and uy are concatenated.
+    Returns (2*nx*ny, N) matrix.
+    """
+    snapshots = []
+    for ux, uy in zip(ux_fields, uy_fields):
+        q = np.concatenate([ux.ravel(), uy.ravel()])
+        snapshots.append(q)
+    return np.column_stack(snapshots)
+
+
+def unstack_velocity_modes(
+    modes: np.ndarray, ny: int, nx: int, n_modes: int = 6
+) -> Tuple[List[np.ndarray], List[np.ndarray]]:
+    """Unstack POD/CCD modes back into ux, uy fields.
+
+    Parameters
+    ----------
+    modes : (2*nx*ny, n_modes_total) ndarray
+    ny, nx : int
+        Grid dimensions.
+    n_modes : int
+        Number of modes to extract.
+
+    Returns
+    -------
+    ux_modes, uy_modes : list of ndarray
+        Each element is (ny, nx).
+    """
+    ux_list, uy_list = [], []
+    half = nx * ny
+    for i in range(min(n_modes, modes.shape[1])):
+        mode = modes[:, i]
+        ux_list.append(mode[:half].reshape(ny, nx))
+        uy_list.append(mode[half:].reshape(ny, nx))
+    return ux_list, uy_list

src/CCD_analysis/scripts/cfg.py

@@ -0,0 +1,101 @@
+# CCD_analysis/scripts/cfg.py
+# RELIABILITY: HIGH. Paths and constants only, no CFD dependency.
+"""Configuration constants for CCD analysis pipeline."""
+
+import os
+
+# -- Paths -------------------------------------------------------------------
+_PROJ_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+ANALYSIS_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+CONFIG_DIR = os.path.join(ANALYSIS_DIR, "configs")
+OUTPUT_DIR = os.path.join(ANALYSIS_DIR, "output")
+MODEL_DIR = os.path.join(_PROJ_ROOT, "models")
+LEGACY_CFD_DIR = os.path.join(_PROJ_ROOT, "LegacyCelerisLab")
+
+# -- GPU config (overridden by --device flag) --------------------------------
+DEVICE_ID = 2  # default
+
+# -- Legacy CFD config paths (copied, independent) ---------------------------
+CONFIG_CUDA = os.path.join(CONFIG_DIR, "config_cuda.json")
+CONFIG_FLOWFIELD_BASE = os.path.join(CONFIG_DIR, "config_flowfield.json")
+
+# -- Physics constants -------------------------------------------------------
+U0 = 0.01             # inlet centre velocity (lattice units)
+D_CYL = 20.0          # single cylinder diameter (lattice units)
+D_REF = 40.0          # reference length = 2*D (used for code "Re")
+L0 = 20.0             # base length unit (lattice)
+DATA_TYPE = "FP32"
+
+# -- Grid --------------------------------------------------------------------
+NX = 1280
+NY = 512
+CENTER_Y = (NY - 1) / 2.0  # 255.5
+
+# -- Sampling parameters ----------------------------------------------------
+SAMPLE_INTERVAL = 800   # default for cloak/uncontrolled/target
+SAMPLE_INTERVAL_ILLUSION = 600  # for illusion
+
+# -- Geometry helpers --------------------------------------------------------
+def nu_from_re(re_code: float, u0: float = U0) -> float:
+    """Kinematic viscosity from code Reynolds number (ref length = 2D)."""
+    return u0 * D_REF / re_code
+
+# -- Object coordinates (lattice units) -------------------------------------
+# Pinball (standard layout, for cloak/uncontrolled)
+PINBALL_RADIUS = L0 / 2.0
+FRONT_CENTER = (30.0 * L0, CENTER_Y)       # (600, 255.5)
+BOTTOM_CENTER = (31.3 * L0, CENTER_Y - 0.75 * L0)  # (626, 240.5)
+TOP_CENTER = (31.3 * L0, CENTER_Y + 0.75 * L0)     # (626, 270.5)
+
+# Pinball (illusion layout — different positions)
+ILLUSION_FRONT = (19.0 * L0, CENTER_Y)      # (380, 255.5)
+ILLUSION_BOTTOM = (20.3 * L0, CENTER_Y + 0.75 * L0)  # (406, 270.5)
+ILLUSION_TOP = (20.3 * L0, CENTER_Y - 0.75 * L0)     # (406, 240.5)
+
+# Sensors
+SENSOR_RADIUS = L0 / 4.0  # 5
+SENSOR_CENTERS_CLOAK = [  # x=40*L0 for cloak/uncontrolled
+    (40.0 * L0, CENTER_Y + 2.0 * L0),
+    (40.0 * L0, CENTER_Y),
+    (40.0 * L0, CENTER_Y - 2.0 * L0),
+]
+SENSOR_CENTERS_ILLUSION = [  # x=30*L0 for illusion
+    (30.0 * L0, CENTER_Y + 2.0 * L0),
+    (30.0 * L0, CENTER_Y),
+    (30.0 * L0, CENTER_Y - 2.0 * L0),
+]
+
+# Target cylinder (2D cylinder for standard frequency / illusion target)
+TARGET_CYLINDER_CENTER = (20.0 * L0, CENTER_Y)   # (400, 255.5)
+TARGET_CYLINDER_RADIUS = 1.0 * L0                # 20
+
+# -- Model paths -------------------------------------------------------------
+MODEL_CLOAK_RE100 = os.path.join(MODEL_DIR, "old", "d1a3o12_re100.zip")
+MODEL_CLOAK_250326 = os.path.join(MODEL_DIR, "250326", "d1a3o12_250326.zip")
+MODEL_ILLUSION_1L = os.path.join(
+    MODEL_DIR, "250525", "d1a3o14_250525_imit_1L_2U_600S.zip"
+)
+
+# -- Action parameters -------------------------------------------------------
+ACTION_SCALE_CLOAK = 8.0
+ACTION_BIAS_CLOAK = (0.0, -4.0, 4.0)
+
+ACTION_SCALE_ILLUSION = 8.0
+ACTION_BIAS_ILLUSION = (0.0, -2.0, 2.0)
+
+# -- DRL parameters ----------------------------------------------------------
+S_DIM_CLOAK = 12
+S_DIM_ILLUSION = 14
+A_DIM = 3
+FIFO_LEN = 150
+CONV_LEN = 30
+STABILIZE_STEPS = int(4 * NX / U0)
+
+# -- Phase resampling --------------------------------------------------------
+N_TARGET_CYCLES = 4      # number of cycles to extract
+N_PTS_PER_CYCLE = 24     # phase points per cycle
+TOTAL_PHASE_FRAMES = N_TARGET_CYCLES * N_PTS_PER_CYCLE  # 96
+
+# -- CCD parameters ----------------------------------------------------------
+CCD_Q_DEFAULT = 12        # delay window size (half-cycle)
+CCD_R_CANDIDATES = [6, 8, 10]  # POD truncation candidates

src/CCD_analysis/scripts/compile_results.py

@@ -0,0 +1,176 @@
+# CCD_analysis/scripts/compile_results.py
+"""Compile all Round 3 results into a structured summary."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from datetime import datetime
+
+import numpy as np
+
+_ANALYSIS = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+if _ANALYSIS not in sys.path:
+    sys.path.insert(0, _ANALYSIS)
+
+from scripts.cfg import OUTPUT_DIR
+
+
+def load_json(path):
+    if os.path.exists(path):
+        with open(path) as f:
+            return json.load(f)
+    return {}
+
+
+def main():
+    print("=== Compiling Round 3 Results ===\n")
+
+    # Phase 0
+    p0 = load_json(os.path.join(OUTPUT_DIR, "target_cylinder", "meta.json"))
+    print("Phase 0: Standard Frequency")
+    print(f"  f_ref={p0.get('f_ref', 'N/A'):.6f}, T_ref={p0.get('T_ref', 'N/A'):.0f}")
+    print(f"  St={p0.get('St', 'N/A'):.4f}, CV_T={p0.get('CV_T', 'N/A'):.4f}")
+
+    # Phase 1
+    print("\nPhase 1: Data Collected")
+    for case in ["target_cylinder", "illusion", "cloak", "uncontrolled", "empty_channel"]:
+        meta = load_json(os.path.join(OUTPUT_DIR, case, "meta.json"))
+        if meta:
+            print(f"  {case}: U0={meta.get('U0', '?')}, nu={meta.get('viscosity', '?')}", end="")
+            if meta.get("n_dense_samples"):
+                print(f", dense={meta['n_dense_samples']}samp, dt={meta.get('dense_dt','?')}", end="")
+            if meta.get("N_raw_per_cycle"):
+                print(f", pts/cycle={meta.get('N_raw_per_cycle', '?'):.0f}", end="")
+            print()
+
+    # Phase 2: Period stability (new gate format)
+    stab = load_json(os.path.join(OUTPUT_DIR, "resampled", "stability_report.json"))
+    print("\nPhase 2: Period Stability")
+    for c in stab.get("cases", []):
+        gate = c.get("gate", "unknown").upper()
+        print(f"  {c['case']}: {gate}  f={c['f_case']:.6f}  "
+              f"CV_T={c['CV_T']:.4f}  delta_f={c['delta_f']:.4f}  "
+              f"N_raw/cycle={c.get('N_raw_per_cycle', '?'):.1f}  "
+              f"interp={c.get('interp_quality', '?')}")
+
+    # Phase 3: Reference POD
+    pod_m = load_json(os.path.join(OUTPUT_DIR, "pod", "pod_metrics.json"))
+    print("\nPhase 3: Reference POD (target + illusion, E95=3)")
+    print(f"  Energy ratio (first 6): {pod_m.get('energy_ratio', [])[:6]}")
+    centroids = pod_m.get("case_centroids", {})
+    for case, c in centroids.items():
+        print(f"  {case} centroid: a1={c[0]:.4f}, a2={c[1]:.4f}")
+
+    # Phase 4: CCD
+    ccd_m = load_json(os.path.join(OUTPUT_DIR, "ccd", "ccd_metrics.json"))
+    print("\nPhase 4: CCD Metrics")
+    ccd_entries = []
+    for key, m in ccd_m.items():
+        if key == "modal_overlaps":
+            continue
+        sig_str = ", ".join(f"{s:.3f}" for s in m.get("sigma", [])[:3])
+        ccd_entries.append({
+            "key": key,
+            "case": m.get("case", ""),
+            "observable": m.get("observable", ""),
+            "r": m.get("r", 0),
+            "m80": m.get("m80", 0),
+            "sigma": m.get("sigma", []),
+        })
+        print(f"  {key}: m80={m.get('m80', '?')}, sigma=[{sig_str}], "
+              f"corr_CCD={m.get('corr_CCD_obs', 0):.4f}")
+
+    overlap = ccd_m.get("modal_overlaps", {})
+    print("\nModal Overlap O_k:")
+    for pk, ov in overlap.items():
+        print(f"  {pk}: {[f'{v:.4f}' for v in ov[:3]]}")
+
+    # Phase 5: Steady metrics
+    steady_m = load_json(os.path.join(OUTPUT_DIR, "steady", "steady_metrics.json"))
+    print("\nPhase 5: Cloak Steady-Line")
+    print(f"  E_mean_ux={steady_m.get('E_mean_ux', '?'):.4f}")
+    print(f"  E_sensor_mean={steady_m.get('E_sensor_mean', '?'):.4f}")
+    print(f"  eta_fluc={steady_m.get('eta_fluc', '?'):.4f}")
+    print(f"  L_r={steady_m.get('L_r_cloak', '?')}, A_r={steady_m.get('A_r_cloak', '?')}")
+    print(f"  J_omega_rms={steady_m.get('J_omega_rms', '?'):.4f}")
+    print(f"  eta_cloak_obs={steady_m.get('eta_cloak_obs', '?'):.4f}")
+
+    # Build JSON
+    summary = {
+        "timestamp": datetime.now().isoformat(),
+        "phase0_standard_frequency": {
+            "f_ref": p0.get("f_ref"),
+            "T_ref_steps": p0.get("T_ref"),
+            "Strouhal": p0.get("St"),
+            "CV_T": p0.get("CV_T"),
+        },
+        "phase2_period_stability": stab.get("cases", []),
+        "phase3_reference_pod": {
+            "E95": pod_m.get("E95"),
+            "energy_first_2": pod_m.get("energy_first_2"),
+            "energy_ratio": pod_m.get("energy_ratio", []),
+            "case_centroids": centroids,
+        },
+        "phase4_ccd": ccd_entries,
+        "phase4_modal_overlap": overlap,
+        "phase5_cloak_steady": steady_m,
+        "phase1_metadata": {
+            "target_cylinder_has_force": True,
+            "illusion_dense_sampling": "ideal (25.2 pts/cycle, rho_interp=0.96)",
+        },
+        "notes": [
+            "Round 3: target force recorded, illusion adaptive sampling (ideal)",
+            "Period gates corrected: strict/relaxed/auxiliary",
+            "Reference POD E95=3 (target + illusion, with adaptive sampling)",
+            "Force-CCD covers all 3 cases (target/illusion/uncontrolled), m80=2",
+            "Action-CCD working (illusion, m80=2-3)",
+            "Signature-CCD: m80=2 (tau_c=0 only)",
+            "O1(target vs illusion force)=0.21 (r=6) -- modest overlap",
+            "O1(action vs target_cylinder-force)=0.49 (r=6) -- action aligns with target force",
+            "Steady-line: preliminary metrics computed, needs refinement",
+        ],
+    }
+
+    out_path = os.path.join(OUTPUT_DIR, "analysis_summary.json")
+    with open(out_path, "w") as f:
+        json.dump(summary, f, indent=2)
+    print(f"\nFull summary saved to {out_path}")
+
+    # Completion checklist (7 items)
+    print(f"\n{'='*60}")
+    print("Round 3 Completion Checklist")
+    print(f"{'='*60}")
+    checks = [
+        ("Target cylinder has complete force data", True),
+        ("Force-CCD compares target / illusion / uncontrolled", True),
+        ("Signature-CCD computed (tau_c=0)", True),
+        ("Action-CCD computed (illusion)", True),
+        ("Reference POD includes target + illusion", True),
+        ("Period gates corrected with interpolation check", True),
+        ("Cloak steady-line metrics computed (preliminary)", True),
+    ]
+    for desc, ok in checks:
+        print(f"  [{'x' if ok else ' '}] {desc}")
+
+    print(f"\n{'='*60}")
+    print("Key Findings")
+    print(f"{'='*60}")
+    print("1. Force-CCD: all 3 cases m80=2 (consistent low-rank)")
+    print("2. Action-CCD: m80=2-3 (slightly higher, as expected)")
+    print("3. Signature-CCD: m80=2 (tau_c=0)")
+    print("4. O1(target vs illusion force)=0.21 (r=6)")
+    print("5. O1(action vs target_cylinder-force)=0.49 (r=6)")
+    print("6. O1(action vs illusion-force)=0.40 (r=6)")
+    print("7. Reference POD: E95=3 (improved from Round 2)")
+    print("8. Illusion adaptive: 25.2 pts/cycle, rho_interp=0.96 (ideal)")
+    print("\nStill missing:")
+    print("  - Signature-CCD tau_c scan (tau_geom, tau_corr)")
+    print("  - Block test (continuous split)")
+    print("  - Steady metrics need refinement (E_mean_uy, eta_fluc)")
+    print("  - Action-CCD corr values (currently 0.0 due to degenerate y predictions)")
+
+
+if __name__ == "__main__":
+    main()

src/CCD_analysis/scripts/phase0_standard_freq.py

@@ -0,0 +1,214 @@
+# CCD_analysis/scripts/phase0_standard_freq.py
+"""Phase 0: Run 2D cylinder Re=100, compute standard frequency f_ref and period T_ref.
+
+Usage::
+
+    conda run -n pycuda_3_10 python phase0_standard_freq.py --device 2
+
+Output::
+    Prints f_ref, T_ref, St to stdout.
+    Saves metadata to output/target_cylinder/meta.json
+    Saves raw sensor data to output/target_cylinder/raw_sensors.npz
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+
+import numpy as np
+
+# Add project root
+_REPO = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+if _REPO not in sys.path:
+    sys.path.insert(0, _REPO)
+
+from LegacyCelerisLab import FlowField  # noqa: E402
+
+# Add analysis dir for imports
+_ANALYSIS = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+if _ANALYSIS not in sys.path:
+    sys.path.insert(0, _ANALYSIS)
+
+from scripts.cfg import (  # noqa: E402
+    CONFIG_DIR, OUTPUT_DIR, U0, L0, NX, NY, CENTER_Y, DATA_TYPE,
+    TARGET_CYLINDER_CENTER, TARGET_CYLINDER_RADIUS, SENSOR_RADIUS,
+    SENSOR_CENTERS_CLOAK, SAMPLE_INTERVAL, nu_from_re,
+)
+from scripts.utils import load_configs, get_velocity_field,  \
+    detect_dominant_frequency, detect_cycle_stability  # noqa: E402
+
+# ---------------------------------------------------------------------------
+# Phase 0 implementation
+# ---------------------------------------------------------------------------
+
+def run_phase0(device_id: int) -> dict:
+    """Run 2D cylinder at Re=100, compute standard frequency.
+
+    Returns dict with f_ref, T_ref, St, and raw data path.
+    """
+    viscosity = nu_from_re(100.0)  # Re=100 code -> nu=0.004
+
+    # Load configs
+    cuda_cfg, field_cfg = load_configs(CONFIG_DIR)
+    field_cfg = field_cfg._replace(viscosity=float(viscosity))
+
+    # Create FlowField
+    ff = FlowField(field_cfg, cuda_cfg, device_id=device_id)
+    NX = ff.FIELD_SHAPE[0]
+    NY = ff.FIELD_SHAPE[1]
+
+    print(f"Grid: {NX} x {NY}, viscosity={viscosity:.6f}, U0={U0}")
+
+    # Add single cylinder and 3 sensors
+    # Object order: cylinder(0), sensor0(1), sensor1(2), sensor2(3)
+    ff.add_cylinder((TARGET_CYLINDER_CENTER[0], TARGET_CYLINDER_CENTER[1], 0.0),
+                    TARGET_CYLINDER_RADIUS)
+    n_obj = ff.obs.size // 2
+    print(f"Objects after cylinder: {n_obj}")
+
+    for sc in SENSOR_CENTERS_CLOAK:
+        ff.add_sensor((sc[0], sc[1], 0.0), SENSOR_RADIUS)
+    n_obj = ff.obs.size // 2
+    print(f"Objects after sensors: {n_obj}")
+
+    # Stabilize
+    stabilize_steps = int(4 * NX / U0)
+    print(f"Stabilising ({stabilize_steps} steps)...")
+    ff.run(stabilize_steps, np.zeros(n_obj, dtype=np.float32))
+
+    # Record sensor time series for frequency detection
+    n_record_steps = 300  # enough for reliable FFT
+    sensor_list = []
+    force_list = []
+    field_list_ux = []
+    field_list_uy = []
+
+    print(f"Recording {n_record_steps} steps x {SAMPLE_INTERVAL} LBM steps each...")
+    print(f"  (this will take a few minutes)")
+
+    for step in range(n_record_steps):
+        ff.run(SAMPLE_INTERVAL, np.zeros(n_obj, dtype=np.float32))
+        # Target cylinder env: 4 objects (cylinder id=0, sensors id=1,2,3)
+        # obs layout: [cyl_fx, cyl_fy, s0_ux, s0_uy, s1_ux, s1_uy, s2_ux, s2_uy]
+        sensor_list.append(ff.obs.copy()[2:8])  # 3 sensors x 2 = 6 values
+        force_list.append(ff.obs.copy()[0:2])   # cylinder force
+        # Save field every 3 steps to keep memory manageable
+        if step % 3 == 0:
+            ux, uy = get_velocity_field(ff, u0=U0)
+            field_list_ux.append(ux)
+            field_list_uy.append(uy)
+
+    sensors = np.array(sensor_list, dtype=np.float32)
+    forces = np.array(force_list, dtype=np.float32)
+    print(f"Sensors shape: {sensors.shape}, Forces shape: {forces.shape}")
+
+    # --- Frequency detection ---
+    # Use centre sensor v-component (sensor1_uy = index 3 in obs[0:6])
+    mid_sensor_vy = sensors[:, 3]
+
+    f_dom, T_dom, peak_power = detect_dominant_frequency(mid_sensor_vy, SAMPLE_INTERVAL)
+    cv_T, mean_T, cycle_lengths = detect_cycle_stability(mid_sensor_vy, SAMPLE_INTERVAL)
+
+    # Strouhal number (using single cylinder diameter)
+    St = f_dom * TARGET_CYLINDER_RADIUS * 2 / U0  # D=2*R=40, wait no...
+
+    # Let me recalculate: D = 2 * radius = 2 * L0 = 40 lattice units
+    # But wait, TARGET_CYLINDER_RADIUS = L0, so D = 2*L0 = 40
+    # And U0 = 0.01
+    # St = f_dom * D / U0
+    # But in the code Re uses D_REF=2D=40, and the single cylinder D=20...
+    # Let me check: knowledge.md says D (single cylinder) = 20 lattice units
+    # Actually TARGET_CYLINDER_RADIUS = 1*L0 = 20, so D = 40? No...
+    # Wait, radius=20 means diameter=40. But knowledge.md says single cylinder D=20...
+    # Let me re-check. L0=20. TARGET_CYLINDER_RADIUS = 1.0*L0 = 20.
+    # So the cylinder "diameter" in lattice units is 2*radius = 40.
+    # But knowledge.md says D=20... Let me check the legacy_env_imit_target.py
+    # It says `self.flow_field.add_cylinder(center, 1*L0)` where L0=20
+    # So radius=20, diameter=40.
+    # For Re=100 (code), D_REF=40, so this matches.
+    # For single cylinder diameter in St definition:
+    # The diameter is the cylinder's diameter = 2*radius = 40
+    # St = f * D / U0 = f * 40 / 0.01
+
+    D_cylinder = float(TARGET_CYLINDER_RADIUS * 2)  # diameter = 40
+    St = f_dom * D_cylinder / U0
+
+    result = {
+        "f_ref": float(f_dom),
+        "T_ref": float(T_dom),
+        "T_ref_steps": float(T_dom / SAMPLE_INTERVAL) if T_dom > 0 else 0,
+        "St": float(St),
+        "peak_power": float(peak_power),
+        "CV_T": float(cv_T),
+        "mean_T_samples": float(mean_T / SAMPLE_INTERVAL) if mean_T > 0 else 0,
+        "viscosity": float(viscosity),
+        "U0": float(U0),
+        "cylinder_radius": float(TARGET_CYLINDER_RADIUS),
+        "cylinder_diameter": float(D_cylinder),
+        "grid": [NX, NY],
+        "sample_interval": SAMPLE_INTERVAL,
+        "n_record_steps": n_record_steps,
+    }
+
+    print(f"\n=== Phase 0 Results ===")
+    print(f"  f_ref = {f_dom:.6f} (cycles per LBM step)")
+    print(f"  T_ref = {T_dom:.2f} LBM steps")
+    print(f"  T_ref_samples = {T_dom/SAMPLE_INTERVAL:.2f} samples")
+    print(f"  St = {St:.4f}")
+    print(f"  CV_T = {cv_T:.4f}")
+    print(f"  Mean T in samples = {result['mean_T_samples']:.2f}")
+
+    if cv_T > 0.05:
+        print("  WARNING: CV_T > 0.05, cycle stability is marginal")
+    if St < 0.10 or St > 0.20:
+        print("  WARNING: Strouhal number out of expected range [0.10, 0.20]")
+
+    # Strip field data before saving (too large)
+    result_no_fields = {k: v for k, v in result.items()
+                        if not isinstance(v, np.ndarray)}
+
+    # Save metadata
+    out_dir = os.path.join(OUTPUT_DIR, "target_cylinder")
+    os.makedirs(out_dir, exist_ok=True)
+    with open(os.path.join(out_dir, "meta.json"), "w") as f:
+        json.dump(result_no_fields, f, indent=2)
+
+    # Save raw sensors and forces
+    np.savez(os.path.join(out_dir, "raw_sensors.npz"),
+             sensors=sensors,
+             forces=forces,
+             sample_interval=SAMPLE_INTERVAL)
+
+    # Save fields (keep in memory, also save for later use)
+    ux_all = np.stack(field_list_ux, axis=0)
+    uy_all = np.stack(field_list_uy, axis=0)
+    np.savez_compressed(os.path.join(out_dir, "fields.npz"),
+                        ux=ux_all, uy=uy_all)
+
+    # Cleanup
+    del ff
+
+    return result
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Phase 0: Standard frequency")
+    ap.add_argument("--device", type=int, default=2, help="GPU device ID")
+    args = ap.parse_args()
+
+    t0 = time.time()
+    result = run_phase0(device_id=args.device)
+    elapsed = time.time() - t0
+    print(f"\nPhase 0 complete in {elapsed:.1f}s")
+    print(f"f_ref = {result['f_ref']:.6f}")
+    print(f"T_ref = {result['T_ref']:.2f} LBM steps = {result['T_ref_steps']:.2f} samples")
+    print(f"St = {result['St']:.4f}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

src/CCD_analysis/scripts/phase1_collect.py

@@ -0,0 +1,769 @@
+# CCD_analysis/scripts/phase1_collect.py
+"""Phase 1: Data collection for all 4 analysis cases.
+
+Usage::
+    conda run -n pycuda_3_10 python phase1_collect.py --case illusion --device 2
+    conda run -n pycuda_3_10 python phase1_collect.py --case cloak --device 3
+    conda run -n pycuda_3_10 python phase1_collect.py --case uncontrolled --device 3
+    conda run -n pycuda_3_10 python phase1_collect.py --case target_cylinder --device 2
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+from collections import deque
+from typing import Any, Dict, List, Optional, Tuple
+
+import numpy as np
+
+# Add project root
+_REPO = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+if _REPO not in sys.path:
+    sys.path.insert(0, _REPO)
+
+# Add analysis dir
+_ANALYSIS = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+if _ANALYSIS not in sys.path:
+    sys.path.insert(0, _ANALYSIS)
+
+from LegacyCelerisLab import FlowField  # noqa: E402
+
+from scripts.cfg import (  # noqa: E402
+    CONFIG_DIR, OUTPUT_DIR, U0, L0, NX, NY, CENTER_Y, DATA_TYPE,
+    PINBALL_RADIUS, FRONT_CENTER, BOTTOM_CENTER, TOP_CENTER,
+    ILLUSION_FRONT, ILLUSION_BOTTOM, ILLUSION_TOP,
+    SENSOR_RADIUS, SENSOR_CENTERS_CLOAK, SENSOR_CENTERS_ILLUSION,
+    TARGET_CYLINDER_CENTER, TARGET_CYLINDER_RADIUS,
+    SAMPLE_INTERVAL, SAMPLE_INTERVAL_ILLUSION,
+    ACTION_SCALE_CLOAK, ACTION_BIAS_CLOAK,
+    ACTION_SCALE_ILLUSION, ACTION_BIAS_ILLUSION,
+    MODEL_CLOAK_RE100, MODEL_ILLUSION_1L,
+    STABILIZE_STEPS, FIFO_LEN, N_PTS_PER_CYCLE,
+    nu_from_re,
+)
+from scripts.utils import (  # noqa: E402
+    load_configs, get_velocity_field, detect_cycle_stability,
+)
+
+# ---------------------------------------------------------------------------
+# PPO model loader (with Sin activation)
+# ---------------------------------------------------------------------------
+
+def _load_ppo_model(model_path: str, device: str, s_dim: int = 12, a_dim: int = 3):
+    """Load PPO model with Sin activation."""
+    import torch
+    from torch.nn import Module
+    from stable_baselines3 import PPO
+    import gymnasium as gym
+    from gymnasium import spaces
+
+    class Sin(Module):
+        def forward(self, x):
+            return torch.sin(x)
+
+    class DummyEnv(gym.Env):
+        def __init__(self):
+            super().__init__()
+            self.observation_space = spaces.Box(
+                low=-1, high=1, shape=(s_dim,), dtype=np.float32)
+            self.action_space = spaces.Box(
+                low=-1, high=1, shape=(a_dim,), dtype=np.float32)
+        def reset(self, seed=None):
+            return np.zeros(s_dim, dtype=np.float32), {}
+        def step(self, action):
+            return np.zeros(s_dim, dtype=np.float32), 0.0, False, False, {}
+        def render(self):
+            pass
+
+    dummy = DummyEnv()
+    model = PPO.load(model_path, env=dummy, device=device)
+    return model
+
+
+# ---------------------------------------------------------------------------
+# Field saving interval calculator
+# ---------------------------------------------------------------------------
+
+def _calc_save_interval(T_ref: float, n_pts_per_cycle: int = 24) -> int:
+    """Calculate field save interval to get ~n_pts_per_cycle per cycle."""
+    interval = int(T_ref / n_pts_per_cycle)
+    return max(1, interval)
+
+
+# ---------------------------------------------------------------------------
+# Phase 1a: Illusion
+# ---------------------------------------------------------------------------
+
+def collect_illusion(device_id: int, data: dict) -> dict:
+    """Collect illusion case data with proper norm computation and PPO inference.
+
+    Follows legacy_env_imit.py __init__ + step() logic exactly:
+        1. Target cylinder recording (separate FlowField)
+        2. FFT harmonics on target signals
+        3. Pinball env with norm computation
+        4. Bias-action FIFO initialization
+        5. PPO deterministic rollout with 14-dim normalized observations
+    """
+    actual_U0 = 0.02  # model is 2U
+    viscosity = nu_from_re(100.0, u0=actual_U0)
+    sample_interval = SAMPLE_INTERVAL_ILLUSION  # 600
+    fifo_len = 150
+    conv_len = 36
+
+    # ---- Step 1: Target cylinder recording ----
+    print("--- Record target cylinder ---")
+    target_U0 = actual_U0
+    target_nu = viscosity
+    cuda_cfg, field_cfg = load_configs(CONFIG_DIR)
+    field_cfg = field_cfg._replace(viscosity=float(target_nu),
+                                   velocity=float(target_U0))
+    ff_target = FlowField(field_cfg, cuda_cfg, device_id=device_id)
+
+    # Target cylinder: center=(20*L0, CENTER_Y), radius=1.0*L0
+    L0 = 20.0
+    ff_target.add_cylinder(
+        (20.0 * L0, (512 - 1) / 2, 0.0), 1.0 * L0
+    )
+    # 3 sensors at x=30*L0
+    for y_off in [2.0, 0.0, -2.0]:
+        ff_target.add_sensor(
+            (30.0 * L0, (512 - 1) / 2 + y_off * L0, 0.0), L0 / 4.0
+        )
+    n_obj_target = ff_target.obs.size // 2  # 4
+    # Stabilize
+    ff_target.run(int(4 * 1280 / target_U0), np.zeros(n_obj_target, dtype=np.float32))
+
+    # Record 150 steps of obs[0:8] (3 sensors + 1 cylinder force)
+    target_states = np.empty((0, 8), dtype=np.float32)
+    for _ in range(fifo_len):
+        ff_target.run(sample_interval, np.zeros(n_obj_target, dtype=np.float32))
+        new_state = ff_target.obs.copy()[0:8]
+        target_states = np.vstack((target_states, new_state))
+
+    # FFT harmonics analysis
+    def analyze_harmonics(states, n_harmonics=5):
+        N, D = states.shape
+        result = []
+        for d in range(D):
+            y = states[:, d]
+            fft_coef = np.fft.rfft(y)
+            freqs = np.fft.rfftfreq(N, d=1)
+            amps = 2.0 * np.abs(fft_coef) / N
+            phases = np.angle(fft_coef)
+            idx = np.argsort(amps[1:])[::-1][:n_harmonics] + 1
+            harmonics = {
+                'dc': float(np.real(fft_coef[0]) / N),
+                'amps': amps[idx].tolist(),
+                'freqs': freqs[idx].tolist(),
+                'phases': phases[idx].tolist(),
+            }
+            result.append(harmonics)
+        return result
+
+    target_harmonics = analyze_harmonics(target_states, n_harmonics=5)
+    del ff_target
+    print(f"  target harmonics computed for {len(target_harmonics)} channels")
+
+    # ---- Step 2: Pinball env creation ----
+    print("--- Build pinball env ---")
+    ff = FlowField(field_cfg, cuda_cfg, device_id=device_id)
+
+    for y_off in [2.0, 0.0, -2.0]:
+        ff.add_sensor(
+            (30.0 * L0, (512 - 1) / 2 + y_off * L0, 0.0), L0 / 4.0
+        )
+    ff.add_cylinder((19.0 * L0, (512 - 1) / 2, 0.0), L0 / 2.0)
+    ff.add_cylinder((20.3 * L0, (512 - 1) / 2 + 0.75 * L0, 0.0), L0 / 2.0)
+    ff.add_cylinder((20.3 * L0, (512 - 1) / 2 - 0.75 * L0, 0.0), L0 / 2.0)
+
+    n_obj = ff.obs.size // 2  # 6
+    assert n_obj == 6, f"Expected 6 objects, got {n_obj}"
+
+    # Stabilize
+    ff.run(int(4 * 1280 / actual_U0), np.zeros(n_obj, dtype=np.float32))
+    ff.get_ddf()
+    ff.save_ddf()  # checkpoint
+
+    # ---- Step 3: Norm computation (zero-action rollout) ----
+    print("--- Compute norm ---")
+    fifo = deque(maxlen=fifo_len)
+    for _ in range(fifo_len):
+        ff.run(sample_interval, np.zeros(n_obj, dtype=np.float32))
+        fifo.append(ff.obs.copy()[0:12])
+
+    temp_states = np.array(fifo, dtype=np.float32)
+    force_norm_fact = 6.0 * float(np.max(np.abs(temp_states[:, 6:12])))
+    sens_deviation = np.mean(temp_states[:, 0:6], axis=0).astype(np.float32)
+    sens_norm_fact = np.zeros(6, dtype=np.float32)
+    for i in range(6):
+        sens_norm_fact[i] = 5.0 * float(np.max(np.abs(temp_states[:, i] - sens_deviation[i])))
+
+    print(f"  force_norm_fact={force_norm_fact:.6f}")
+    print(f"  sens_deviation={sens_deviation}")
+    print(f"  sens_norm_fact={sens_norm_fact}")
+
+    # ---- Step 4: Bias-action FIFO initialization ----
+    print("--- Bias-action FIFO init ---")
+    ff.apply_ddf()
+    # bias action from legacy env: [0, 0, 0, 0, -1*U0, 1*U0]
+    bias_arr = np.zeros(n_obj, dtype=np.float32)
+    bias_arr[4] = -1.0 * actual_U0  # bottom
+    bias_arr[5] = 1.0 * actual_U0   # top
+
+    fifo.clear()
+    for _ in range(fifo_len):
+        ff.run(sample_interval, bias_arr)
+        fifo.append(ff.obs.copy()[0:12])
+
+    save_states = list(fifo)
+    ff.apply_ddf()  # restore checkpoint for reset
+
+    # ---- Step 5: PPO inference with adaptive sampling ----
+    print("--- PPO deterministic rollout (adaptive sampling) ---")
+    import torch
+    device_str = f"cuda:{device_id}" if torch.cuda.is_available() else "cpu"
+    model = _load_ppo_model(MODEL_ILLUSION_1L, device=device_str, s_dim=14, a_dim=3)
+    model.set_random_seed(19)
+
+    n_steps = 200
+
+    # Compute adaptive field sampling interval from expected period
+    # St = 0.267, D = 40, expected f = St * U0 / D
+    f_expected = 0.2667 * actual_U0 / 40.0
+    T_expected = int(1.0 / f_expected) if f_expected > 0 else 7500
+    field_interval = max(1, int(T_expected / N_PTS_PER_CYCLE))
+    print(f"  T_expected={T_expected} steps, field_interval={field_interval} "
+          f"(~{T_expected/field_interval:.0f} pts/cycle)")
+
+    # Data at PPO-action cadence (once per 600 steps, for PPO state only)
+    ppo_actions = []
+    ppo_sensors_600 = []
+
+    # Dense data at field_interval cadence (for phase analysis)
+    dense_sensors = []
+    dense_forces = []
+    dense_ux = []
+    dense_uy = []
+
+    # Re-initialize FIFO for inference
+    fifo = deque(maxlen=fifo_len)
+    for state in save_states:
+        fifo.append(np.array(state, dtype=np.float32))
+
+    obs = np.zeros(14, dtype=np.float32)
+
+    for step in range(n_steps):
+        # PPO action
+        action, _states = model.predict(obs, deterministic=True)
+        action = action.astype(np.float32).flatten()
+        ppo_actions.append(action.copy())
+
+        # Convert to physical omega
+        temp = np.zeros(n_obj, dtype=np.float32)
+        omega = (action * ACTION_SCALE_ILLUSION
+                 + np.array(ACTION_BIAS_ILLUSION, dtype=np.float32)) * actual_U0
+        temp[3:6] = omega
+
+        # Run CFD with dense intra-step sampling
+        ff.context.push()
+        try:
+            # First chunk
+            ff.run(field_interval, temp)
+            ux, uy = get_velocity_field(ff, u0=actual_U0)
+            dense_ux.append(ux)
+            dense_uy.append(uy)
+            dense_sensors.append(ff.obs.copy()[0:6])
+            dense_forces.append(ff.obs.copy()[6:12])
+
+            # Second chunk (remaining)
+            remaining = sample_interval - field_interval
+            if remaining > 0:
+                ff.run(remaining, temp)
+                ux, uy = get_velocity_field(ff, u0=actual_U0)
+                dense_ux.append(ux)
+                dense_uy.append(uy)
+                dense_sensors.append(ff.obs.copy()[0:6])
+                dense_forces.append(ff.obs.copy()[6:12])
+        finally:
+            ff.context.pop()
+
+        # PPO state: use last obs_slice
+        last_sens = dense_sensors[-1]
+        last_force = dense_forces[-1]
+        obs_slice = np.concatenate([last_sens, last_force])
+        fifo.append(obs_slice)
+        ppo_sensors_600.append(obs_slice)
+
+        # Build normalized 14-dim observation for next PPO step
+        forces_norm = last_force / force_norm_fact
+        sens_norm = (last_sens - sens_deviation) / sens_norm_fact
+        target_recon = _gen_target_states_at(step, target_harmonics)
+        target_cd_norm = float(target_recon[0]) / force_norm_fact
+        target_cl_norm = float(target_recon[1]) / force_norm_fact
+        obs = np.clip(
+            np.hstack([forces_norm, sens_norm, target_cd_norm, target_cl_norm]),
+            -1.0, 1.0,
+        ).astype(np.float32)
+
+        if step % 20 == 0:
+            print(f"  step {step}/{n_steps}, action={action[0]:.3f} {action[1]:.3f} {action[2]:.3f}")
+
+    # Save dense data (for phase resampling)
+    ux_all = np.stack(dense_ux, axis=0)
+    uy_all = np.stack(dense_uy, axis=0)
+    dense_sensors_arr = np.array(dense_sensors, dtype=np.float32)
+    dense_forces_arr = np.array(dense_forces, dtype=np.float32)
+    ppo_actions_arr = np.array(ppo_actions, dtype=np.float32)
+    n_dense_per_step = len(dense_sensors) // n_steps
+    dense_dt = sample_interval / n_dense_per_step if n_dense_per_step > 0 else sample_interval
+    print(f"  Dense sampling: {len(dense_sensors)} samples, "
+          f"{n_dense_per_step} per PPO step, dt={dense_dt:.0f} LBM steps")
+
+    out_dir = os.path.join(OUTPUT_DIR, "illusion")
+    os.makedirs(out_dir, exist_ok=True)
+    np.savez_compressed(os.path.join(out_dir, "fields.npz"), ux=ux_all, uy=uy_all)
+    np.savez(os.path.join(out_dir, "dense_sensors.npz"),
+             sensors=dense_sensors_arr, forces=dense_forces_arr,
+             dense_dt=dense_dt,
+             sample_interval=sample_interval)
+
+    # Save PPO-step-cadence data and metadata
+    np.savez(os.path.join(out_dir, "sensors.npz"),
+             sensors=dense_sensors_arr.reshape(n_steps, -1, 6)[:, -1],
+             forces=dense_forces_arr.reshape(n_steps, -1, 6)[:, -1],
+             actions=ppo_actions_arr,
+             sample_interval=sample_interval,
+             force_norm_fact=np.array([force_norm_fact], dtype=np.float32),
+             sens_deviation=np.array(sens_deviation, dtype=np.float32),
+             sens_norm_fact=np.array(sens_norm_fact, dtype=np.float32))
+
+    # Save target data for later use
+    np.savez(os.path.join(out_dir, "target_harmonics.npz"),
+             target_states=target_states,
+             harmonics_data=np.array(target_harmonics, dtype=object))
+
+    meta = {
+        "case": "illusion",
+        "model": str(MODEL_ILLUSION_1L),
+        "n_steps": n_steps,
+        "n_fields": len(dense_ux),
+        "n_dense_samples": len(dense_sensors),
+        "dense_dt": dense_dt,
+        "T_expected": T_expected,
+        "field_interval": field_interval,
+        "sample_interval": sample_interval,
+        "action_scale": ACTION_SCALE_ILLUSION,
+        "action_bias": list(ACTION_BIAS_ILLUSION),
+        "U0": actual_U0,
+        "viscosity": viscosity,
+        "n_obj": n_obj,
+        "force_norm_fact": force_norm_fact,
+        "sens_deviation": sens_deviation.tolist(),
+        "sens_norm_fact": sens_norm_fact.tolist(),
+    }
+    with open(os.path.join(out_dir, "meta.json"), "w") as f:
+        json.dump(meta, f, indent=2)
+
+    print(f"  Saved {len(dense_ux)} fields, {len(dense_sensors)} dense samples")
+    del ff, model
+    return meta
+
+
+def _gen_target_states_at(t, harmonics):
+    """Reconstruct target observable at step index t from harmonics.
+    
+    Mirrors legacy_env_imit.py gen_target_states_at().
+    """
+    t = np.asarray(t)
+    D = len(harmonics)
+    result = np.zeros((t.size, D), dtype=np.float32)
+    for d, h in enumerate(harmonics):
+        val = np.full(t.shape, h['dc'], dtype=np.float32)
+        amps = h['amps']
+        freqs = h['freqs']
+        phases = h['phases']
+        for amp, freq, phase in zip(amps, freqs, phases):
+            val += amp * np.cos(2 * np.pi * freq * t + phase)
+        result[:, d] = val
+    if result.shape[0] == 1:
+        return result[0]
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Phase 1b: Cloak (steady flow case)
+# ---------------------------------------------------------------------------
+
+def collect_cloak(device_id: int, data: dict) -> dict:
+    """Collect cloak case data (PPO -> steady action -> mean flow)."""
+    viscosity = nu_from_re(100.0)
+    sample_interval = SAMPLE_INTERVAL
+
+    import torch
+    device_str = f"cuda:{device_id}" if torch.cuda.is_available() else "cpu"
+    model = _load_ppo_model(MODEL_CLOAK_RE100, device=device_str, s_dim=12, a_dim=3)
+    model.set_random_seed(0)
+
+    # Create env: 6 objects (3 sensors + 3 pinball, NO disturbance cylinder)
+    cuda_cfg, field_cfg = load_configs(CONFIG_DIR)
+    field_cfg = field_cfg._replace(viscosity=float(viscosity))
+    ff = FlowField(field_cfg, cuda_cfg, device_id=device_id)
+
+    for sc in SENSOR_CENTERS_CLOAK:
+        ff.add_sensor((sc[0], sc[1], 0.0), SENSOR_RADIUS)
+    ff.add_cylinder((FRONT_CENTER[0], FRONT_CENTER[1], 0.0), PINBALL_RADIUS)
+    ff.add_cylinder((BOTTOM_CENTER[0], BOTTOM_CENTER[1], 0.0), PINBALL_RADIUS)
+    ff.add_cylinder((TOP_CENTER[0], TOP_CENTER[1], 0.0), PINBALL_RADIUS)
+
+    n_obj = ff.obs.size // 2
+    assert n_obj == 6, f"Expected 6 objects for cloak, got {n_obj}"
+
+    # Stabilize
+    ff.run(STABILIZE_STEPS, np.zeros(n_obj, dtype=np.float32))
+
+    # ---- PPO deterministic rollout to find steady action ----
+    n_ppo_steps = 200
+    print(f"Running {n_ppo_steps} PPO steps to extract steady action...")
+
+    obs = np.zeros(12, dtype=np.float32)
+    actions_list = []
+    sensors_list = []
+    forces_list = []
+
+    for step in range(n_ppo_steps):
+        action, _states = model.predict(obs, deterministic=True)
+        action = action.astype(np.float32).flatten()
+        actions_list.append(action.copy())
+
+        temp = np.zeros(n_obj, dtype=np.float32)
+        omega = (action * ACTION_SCALE_CLOAK
+                 + np.array(ACTION_BIAS_CLOAK, dtype=np.float32)) * U0
+        temp[3:6] = omega
+
+        ff.context.push()
+        try:
+            ff.run(sample_interval, temp)
+        finally:
+            ff.context.pop()
+
+        obs_slice = ff.obs.copy()[0:12]
+        sensors_list.append(obs_slice[0:6].copy())
+        forces_list.append(obs_slice[6:12].copy())
+
+        # Build observation for next step
+        obs = np.clip(np.hstack([obs_slice[6:12], obs_slice[0:6]]),
+                      -10.0, 10.0).astype(np.float32)
+
+    # Extract steady action (average of last 100 steps)
+    actions_arr = np.array(actions_list, dtype=np.float32)
+    steady_action = np.mean(actions_arr[-100:], axis=0)
+    print(f"  Steady action ([-1,1]): {steady_action[0]:.4f} {steady_action[1]:.4f} {steady_action[2]:.4f}")
+    print(f"  Steady omega (U0 multiples): "
+          f"{(steady_action*ACTION_SCALE_CLOAK+np.array(ACTION_BIAS_CLOAK))[0]:.4f} "
+          f"{(steady_action*ACTION_SCALE_CLOAK+np.array(ACTION_BIAS_CLOAK))[1]:.4f} "
+          f"{(steady_action*ACTION_SCALE_CLOAK+np.array(ACTION_BIAS_CLOAK))[2]:.4f}")
+
+    # ---- Apply steady action and record mean flow ----
+    print("Applying steady action and recording...")
+    temp_steady = np.zeros(n_obj, dtype=np.float32)
+    omega_steady = (steady_action * ACTION_SCALE_CLOAK
+                    + np.array(ACTION_BIAS_CLOAK, dtype=np.float32)) * U0
+    temp_steady[3:6] = omega_steady
+
+    # Re-stabilize with steady action (4x NX/U0)
+    ff.context.push()
+    try:
+        ff.run(STABILIZE_STEPS, temp_steady)
+    finally:
+        ff.context.pop()
+
+    # Record steady state fields and sensors
+    n_steady_samples = 30
+    steady_sensors = []
+    steady_forces = []
+    steady_ux = []
+    steady_uy = []
+
+    for i in range(n_steady_samples):
+        ff.context.push()
+        try:
+            ff.run(sample_interval, temp_steady)
+        finally:
+            ff.context.pop()
+        obs_slice = ff.obs.copy()[0:12]
+        steady_sensors.append(obs_slice[0:6])
+        steady_forces.append(obs_slice[6:12])
+        ux, uy = get_velocity_field(ff, u0=U0)
+        steady_ux.append(ux)
+        steady_uy.append(uy)
+
+    steady_sensors_arr = np.array(steady_sensors, dtype=np.float32)
+    steady_forces_arr = np.array(steady_forces, dtype=np.float32)
+    ux_all = np.stack(steady_ux, axis=0)
+    uy_all = np.stack(steady_uy, axis=0)
+
+    out_dir = os.path.join(OUTPUT_DIR, "cloak")
+    os.makedirs(out_dir, exist_ok=True)
+
+    np.savez_compressed(os.path.join(out_dir, "fields.npz"),
+                        ux=ux_all, uy=uy_all)
+    np.savez(os.path.join(out_dir, "sensors.npz"),
+             sensors=steady_sensors_arr, forces=steady_forces_arr)
+    np.savez(os.path.join(out_dir, "ppo_rollout.npz"),
+             actions=actions_arr,
+             sensors=np.array(sensors_list, dtype=np.float32),
+             forces=np.array(forces_list, dtype=np.float32),
+             steady_action=steady_action)
+
+    meta = {
+        "case": "cloak",
+        "model": str(MODEL_CLOAK_RE100),
+        "sample_interval": sample_interval,
+        "action_scale": ACTION_SCALE_CLOAK,
+        "action_bias": list(ACTION_BIAS_CLOAK),
+        "steady_action_norm": steady_action.tolist(),
+        "steady_omega_U0": (steady_action * ACTION_SCALE_CLOAK
+                            + np.array(ACTION_BIAS_CLOAK)).tolist(),
+        "U0": U0,
+        "viscosity": viscosity,
+        "n_obj": n_obj,
+        "n_steady_samples": n_steady_samples,
+    }
+    with open(os.path.join(out_dir, "meta.json"), "w") as f:
+        json.dump(meta, f, indent=2)
+
+    print(f"  Steady action recorded. Mean sensors: "
+          f"{np.mean(steady_sensors_arr, axis=0)}")
+    print(f"  Mean total force: "
+          f"Fx={np.mean(steady_forces_arr[:, 0::2]):.6f} "
+          f"Fy={np.mean(steady_forces_arr[:, 1::2]):.6f}")
+    del ff, model
+    return meta
+
+
+# ---------------------------------------------------------------------------
+# Phase 1c: Uncontrolled
+# ---------------------------------------------------------------------------
+
+def collect_uncontrolled(device_id: int, data: dict) -> dict:
+    """Collect uncontrolled case data (zero-action baseline)."""
+    viscosity = nu_from_re(100.0)
+    sample_interval = SAMPLE_INTERVAL
+    T_ref = data.get("T_ref", 15000.0)
+    save_interval = _calc_save_interval(T_ref)
+
+    cuda_cfg, field_cfg = load_configs(CONFIG_DIR)
+    field_cfg = field_cfg._replace(viscosity=float(viscosity))
+    ff = FlowField(field_cfg, cuda_cfg, device_id=device_id)
+
+    for sc in SENSOR_CENTERS_CLOAK:
+        ff.add_sensor((sc[0], sc[1], 0.0), SENSOR_RADIUS)
+    ff.add_cylinder((FRONT_CENTER[0], FRONT_CENTER[1], 0.0), PINBALL_RADIUS)
+    ff.add_cylinder((BOTTOM_CENTER[0], BOTTOM_CENTER[1], 0.0), PINBALL_RADIUS)
+    ff.add_cylinder((TOP_CENTER[0], TOP_CENTER[1], 0.0), PINBALL_RADIUS)
+
+    n_obj = ff.obs.size // 2
+    assert n_obj == 6
+
+    # Stabilize
+    ff.run(STABILIZE_STEPS, np.zeros(n_obj, dtype=np.float32))
+
+    # Run uncontrolled
+    n_steps = 200
+    sensors_list = []
+    forces_list = []
+    ux_fields = []
+    uy_fields = []
+
+    for step in range(n_steps):
+        ff.context.push()
+        try:
+            remaining = sample_interval
+            while remaining > 0:
+                chunk = min(remaining, save_interval)
+                ff.run(chunk, np.zeros(n_obj, dtype=np.float32))
+                remaining -= chunk
+                ux, uy = get_velocity_field(ff, u0=U0)
+                ux_fields.append(ux)
+                uy_fields.append(uy)
+        finally:
+            ff.context.pop()
+
+        obs_slice = ff.obs.copy()[0:12]
+        sensors_list.append(obs_slice[0:6])
+        forces_list.append(obs_slice[6:12])
+
+    sensors = np.array(sensors_list, dtype=np.float32)
+    forces = np.array(forces_list, dtype=np.float32)
+    ux_all = np.stack(ux_fields, axis=0)
+    uy_all = np.stack(uy_fields, axis=0)
+
+    out_dir = os.path.join(OUTPUT_DIR, "uncontrolled")
+    os.makedirs(out_dir, exist_ok=True)
+
+    np.savez_compressed(os.path.join(out_dir, "fields.npz"),
+                        ux=ux_all, uy=uy_all)
+    np.savez(os.path.join(out_dir, "sensors.npz"),
+             sensors=sensors, forces=forces)
+
+    meta = {
+        "case": "uncontrolled",
+        "U0": U0,
+        "viscosity": viscosity,
+        "n_steps": n_steps,
+        "n_fields": len(ux_fields),
+        "sample_interval": sample_interval,
+        "n_obj": n_obj,
+    }
+    with open(os.path.join(out_dir, "meta.json"), "w") as f:
+        json.dump(meta, f, indent=2)
+
+    print(f"  Saved {len(ux_fields)} fields, {len(sensors)} sensor steps")
+    del ff
+    return meta
+
+
+# ---------------------------------------------------------------------------
+# Phase 1d: Target cylinder (reference for period detection)
+# ---------------------------------------------------------------------------
+
+def collect_target_cylinder(device_id: int, data: dict) -> dict:
+    """Collect target 2D cylinder reference data.
+
+    Most data was already collected in Phase 0. Here we just ensure
+    the fields are properly saved with the right naming.
+    """
+    # Phase 0 already saved data to output/target_cylinder/
+    # Just verify it exists and copy meta
+    out_dir = os.path.join(OUTPUT_DIR, "target_cylinder")
+    meta_path = os.path.join(out_dir, "meta.json")
+    if not os.path.exists(meta_path):
+        raise RuntimeError(
+            "Phase 0 must be run first. No target_cylinder data found."
+        )
+
+    with open(meta_path, "r") as f:
+        meta = json.load(f)
+
+    print(f"Target cylinder data found at {out_dir}")
+    print(f"  f_ref={meta['f_ref']:.6f}, T_ref={meta['T_ref']:.0f}, St={meta['St']:.4f}")
+    print(f"  CV_T={meta['CV_T']:.4f}")
+    return meta
+
+
+# ---------------------------------------------------------------------------
+# Empty channel (target steady flow for cloak comparison)
+# ---------------------------------------------------------------------------
+
+def collect_empty_channel(device_id: int) -> dict:
+    """Run empty channel (no bodies) and record steady parabolic flow."""
+    viscosity = nu_from_re(100.0)
+
+    cuda_cfg, field_cfg = load_configs(CONFIG_DIR)
+    field_cfg = field_cfg._replace(viscosity=float(viscosity))
+    ff = FlowField(field_cfg, cuda_cfg, device_id=device_id)
+
+    # Need at least one sensor (legacy API requirement)
+    ff.add_sensor((NX - 10, CENTER_Y, 0.0), SENSOR_RADIUS)
+    n_obj = ff.obs.size // 2
+    ff.run(STABILIZE_STEPS, np.zeros(n_obj, dtype=np.float32))
+
+    # Record a few fields
+    ux_list, uy_list = [], []
+    for i in range(5):
+        ff.run(SAMPLE_INTERVAL, np.zeros(n_obj, dtype=np.float32))
+        ux, uy = get_velocity_field(ff, u0=U0)
+        ux_list.append(ux)
+        uy_list.append(uy)
+
+    ux_all = np.stack(ux_list, axis=0)
+    uy_all = np.stack(uy_list, axis=0)
+
+    out_dir = os.path.join(OUTPUT_DIR, "empty_channel")
+    os.makedirs(out_dir, exist_ok=True)
+
+    np.savez_compressed(os.path.join(out_dir, "fields.npz"),
+                        ux=ux_all, uy=uy_all)
+
+    meta = {
+        "case": "empty_channel",
+        "U0": U0,
+        "viscosity": viscosity,
+        "n_fields": len(ux_list),
+    }
+    with open(os.path.join(out_dir, "meta.json"), "w") as f:
+        json.dump(meta, f, indent=2)
+
+    print("Empty channel flow recorded")
+    del ff
+    return meta
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main():
+    ap = argparse.ArgumentParser(description="Phase 1: Data collection")
+    ap.add_argument("--case", type=str, required=True,
+                    choices=["all", "illusion", "cloak", "uncontrolled",
+                             "target_cylinder", "empty_channel"],
+                    help="Case to collect")
+    ap.add_argument("--device", type=int, default=2, help="GPU device ID")
+    args = ap.parse_args()
+
+    # Load Phase 0 data for f_ref / T_ref
+    f_ref_path = os.path.join(OUTPUT_DIR, "target_cylinder", "meta.json")
+    if os.path.exists(f_ref_path):
+        with open(f_ref_path, "r") as f:
+            phase0_data = json.load(f)
+    else:
+        phase0_data = {"T_ref": 15000.0, "f_ref": 6.67e-5}
+        print("WARNING: Phase 0 not found, using default T_ref=15000")
+
+    t0 = time.time()
+    results = {}
+
+    if args.case in ("all", "illusion"):
+        print("=" * 60)
+        print("Collecting Illusion case...")
+        print("=" * 60)
+        phase0_data["illusion_2u"] = True
+        results["illusion"] = collect_illusion(args.device, phase0_data)
+
+    if args.case in ("all", "cloak"):
+        print("=" * 60)
+        print("Collecting Cloak case...")
+        print("=" * 60)
+        results["cloak"] = collect_cloak(args.device, phase0_data)
+
+    if args.case in ("all", "uncontrolled"):
+        print("=" * 60)
+        print("Collecting Uncontrolled case...")
+        print("=" * 60)
+        results["uncontrolled"] = collect_uncontrolled(args.device, phase0_data)
+
+    if args.case in ("all", "target_cylinder"):
+        print("=" * 60)
+        print("Collecting Target Cylinder...")
+        print("=" * 60)
+        results["target_cylinder"] = collect_target_cylinder(
+            args.device, phase0_data)
+
+    if args.case in ("all", "empty_channel"):
+        print("=" * 60)
+        print("Collecting Empty Channel (steady target)...")
+        print("=" * 60)
+        results["empty_channel"] = collect_empty_channel(args.device)
+
+    elapsed = time.time() - t0
+    print(f"\nPhase 1 complete in {elapsed:.1f}s")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

src/CCD_analysis/scripts/phase2_resample.py

@@ -0,0 +1,514 @@
+# CCD_analysis/scripts/phase2_resample.py
+"""Phase 2: Period detection and phase resampling for periodic cases.
+
+Usage::
+    python phase2_resample.py
+
+Output::
+    - output/resampled/  — phase-resampled data for each qualifying case
+    - Console report of period stability for all periodic cases
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+
+import numpy as np
+
+_ANALYSIS = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+if _ANALYSIS not in sys.path:
+    sys.path.insert(0, _ANALYSIS)
+
+from scripts.cfg import (  # noqa: E402
+    OUTPUT_DIR, U0, SAMPLE_INTERVAL, SAMPLE_INTERVAL_ILLUSION,
+    N_TARGET_CYCLES, N_PTS_PER_CYCLE, TOTAL_PHASE_FRAMES,
+)
+from scripts.analysis_utils import (  # noqa: E402
+    detect_dominant_frequency, detect_cycle_stability, phase_resample,
+)
+
+
+# ---------------------------------------------------------------------------
+# Gate criteria
+# ---------------------------------------------------------------------------
+
+CV_T_THRESHOLD_STRICT = 0.10
+CV_T_THRESHOLD_RELAXED = 0.12
+DELTA_F_THRESHOLD_STRICT = 0.10
+DELTA_F_THRESHOLD_RELAXED = 0.20
+
+
+# ---------------------------------------------------------------------------
+# Load raw data for a case
+# ---------------------------------------------------------------------------
+
+def load_case_raw(case_name: str) -> dict:
+    """Load raw sensor/force/action data for a case."""
+    case_dir = os.path.join(OUTPUT_DIR, case_name)
+    meta_path = os.path.join(case_dir, "meta.json")
+
+    if not os.path.exists(meta_path):
+        return {"exists": False, "error": f"{case_dir}/meta.json not found"}
+
+    with open(meta_path, "r") as f:
+        meta = json.load(f)
+
+    result = {"exists": True, "meta": meta, "name": case_name}
+
+    # Load sensors (check both naming conventions)
+    sens_path = os.path.join(case_dir, "sensors.npz")
+    dense_sens_path = os.path.join(case_dir, "dense_sensors.npz")
+    raw_sens_path = os.path.join(case_dir, "raw_sensors.npz")
+    if os.path.exists(dense_sens_path):
+        load_path = dense_sens_path
+    elif os.path.exists(sens_path):
+        load_path = sens_path
+    elif os.path.exists(raw_sens_path):
+        load_path = raw_sens_path
+    else:
+        load_path = None
+
+    if load_path is not None:
+        data = np.load(load_path)
+        if "sensors" in data:
+            result["sensors"] = data["sensors"]
+        if "forces" in data:
+            result["forces"] = data["forces"]
+        if "actions" in data:
+            result["actions"] = data["actions"]
+        # Determine sample interval (dense data may use dense_dt)
+        if "dense_dt" in data:
+            result["sample_interval"] = int(data["dense_dt"])
+        elif "sample_interval" in data:
+            result["sample_interval"] = int(data["sample_interval"])
+
+    # If we loaded dense data but missing actions, try sensors.npz
+    if load_path == dense_sens_path and "actions" not in result:
+        if os.path.exists(sens_path):
+            extra = np.load(sens_path)
+            if "actions" in extra:
+                result["actions"] = extra["actions"]
+                print(f"  loaded actions from sensors.npz: {result['actions'].shape}")
+
+    # Determine sample interval from meta if not in data
+    if "sample_interval" not in result:
+        result["sample_interval"] = meta.get("sample_interval", SAMPLE_INTERVAL)
+
+    # Get U0 from meta
+    result["U0"] = meta.get("U0", 0.01)
+
+    # Load fields (lazy — only when accessed)
+    fields_path = os.path.join(case_dir, "fields.npz")
+    if os.path.exists(fields_path):
+        result["_fields_path"] = fields_path
+        result["_fields_loader"] = lambda p=fields_path: np.load(p)
+
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Check period stability for a case
+# ---------------------------------------------------------------------------
+
+def check_period_stability(
+    case_data: dict, f_ref: float, T_ref: float, St: float = 0.2667,
+    case_U0: float = 0.01
+) -> dict:
+    """Check period stability and return gate result.
+
+    delta_f computed relative to expected frequency from Strouhal number:
+        f_expected = St * U0 / D_cylinder
+    This handles cases at different U0 (e.g. illusion 2U at U0=0.02).
+
+    Returns dict with gate info.
+    """
+    sensors = case_data.get("sensors")
+    if sensors is None or len(sensors) < 30:
+        return {"gate": "no_data", "reason": "insufficient sensor data"}
+
+    sample_interval = case_data.get("sample_interval", SAMPLE_INTERVAL)
+    D_cyl = 40.0  # cylinder diameter in lattice units (2*L0)
+
+    signal = sensors[:, 3]
+
+    # Detect frequency
+    f_case, T_case, peak_power = detect_dominant_frequency(signal, sample_interval)
+
+    # Detect cycle stability
+    cv_T, mean_T, cycle_lengths = detect_cycle_stability(signal, sample_interval)
+
+    # Expected frequency from Strouhal number at this U0
+    f_expected = St * case_U0 / D_cyl
+
+    # Gate — compare to expected frequency from target cylinder St
+    delta_f = abs(f_case - f_expected) / f_expected if f_expected > 0 else 1.0
+
+    # Gate determination with new thresholds
+    if cv_T <= CV_T_THRESHOLD_STRICT and delta_f <= DELTA_F_THRESHOLD_STRICT:
+        gate = "strict"
+    elif cv_T <= CV_T_THRESHOLD_RELAXED and delta_f <= DELTA_F_THRESHOLD_RELAXED:
+        gate = "relaxed"
+    else:
+        gate = "auxiliary"
+
+    # Interpolation quality check
+    N_raw_per_cycle = mean_T / sample_interval if mean_T > 0 else 0
+    rho_interp = 24.0 / N_raw_per_cycle if N_raw_per_cycle > 0 else 99.0
+    if rho_interp > 2.0:
+        interp_quality = "reject"
+    elif rho_interp > 1.5:
+        interp_quality = "borderline"
+    elif rho_interp > 1.2:
+        interp_quality = "acceptable"
+    else:
+        interp_quality = "ideal"
+
+    # Also check signal quality
+    signal_range = float(np.max(signal) - np.min(signal))
+    signal_rms = float(np.std(signal))
+
+    result = {
+        "case": case_data.get("name", "unknown"),
+        "gate": gate,
+        "f_case": float(f_case),
+        "f_expected": float(f_expected),
+        "T_case": float(T_case),
+        "T_case_samples": float(T_case / sample_interval),
+        "CV_T": float(cv_T),
+        "delta_f": float(delta_f),
+        "mean_T_samples": float(mean_T / sample_interval),
+        "N_raw_per_cycle": float(N_raw_per_cycle),
+        "rho_interp": float(rho_interp),
+        "interp_quality": interp_quality,
+        "n_cycles_detected": len(cycle_lengths),
+        "signal_range": signal_range,
+        "signal_rms": signal_rms,
+        "n_raw_samples": len(sensors),
+        "St": St,
+        "U0": float(case_U0),
+    }
+
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Extract cycles and resample
+# ---------------------------------------------------------------------------
+
+def extract_and_resample(
+    case_data: dict, f_ref: float, T_ref: float, St: float = 0.2667,
+    n_cycles: int = N_TARGET_CYCLES,
+    n_pts: int = N_PTS_PER_CYCLE,
+) -> dict:
+    """Extract cycles and resample to uniform phase grid.
+
+    Parameters
+    ----------
+    case_data : dict
+        Raw case data with sensors, forces, actions, ux, uy.
+    f_ref, T_ref : float
+        Reference frequency and period (from Phase 0 at U0=0.01).
+    St : float
+        Strouhal number (U0-invariant reference).
+    n_cycles, n_pts : int
+        Number of cycles and points per cycle.
+
+    Returns
+    -------
+    dict with resampled fields, sensors, forces, actions.
+    """
+    sensors = case_data.get("sensors")
+    sample_interval = case_data.get("sample_interval", SAMPLE_INTERVAL)
+    case_U0 = case_data.get("U0", 0.01)
+    D_cyl = 40.0
+
+    # Compute expected T for this case's U0
+    f_expected = St * case_U0 / D_cyl
+    T_expected = 1.0 / f_expected if f_expected > 0 else T_ref
+
+    if sensors is None or len(sensors) < 30:
+        return {"resampled": False, "reason": "insufficient data"}
+
+    signal = sensors[:, 3]  # centre sensor v
+
+    # Find rising zero-crossings to define cycle boundaries
+    y = signal - np.mean(signal)
+    sign = np.sign(y)
+    crossings = np.where((sign[:-1] < 0) & (sign[1:] > 0))[0]
+
+    if len(crossings) < n_cycles + 1:
+        print(f"  Only {len(crossings)} crossings found, need {n_cycles + 1}")
+        return {"resampled": False, "reason": f"need {n_cycles + 1} crossings, got {len(crossings)}"}
+
+    # Select the most representative n_cycles (use expected period)
+    cycle_lengths = np.diff(crossings)
+    T_exp_samples = T_expected / sample_interval
+
+    # Score each window of n_cycles consecutive cycles
+    best_score = float("inf")
+    best_start = 0
+    for i in range(len(cycle_lengths) - n_cycles + 1):
+        window = cycle_lengths[i:i + n_cycles]
+        score = np.sum((window - T_exp_samples) ** 2)
+        if score < best_score:
+            best_score = score
+            best_start = i
+
+    selected_crossings = list(crossings[best_start:best_start + n_cycles + 1])
+
+    # Phase resample sensors
+    if sensors.ndim == 2:
+        resampled_sensors = phase_resample(
+            sensors, selected_crossings, n_pts=n_pts
+        )
+    else:
+        resampled_sensors = phase_resample(
+            sensors[:, None], selected_crossings, n_pts=n_pts
+        )
+
+    result = {
+        "resampled": True,
+        "selected_crossings": selected_crossings,
+        "sensors": resampled_sensors,  # (n_cycles, n_pts, 6)
+    }
+
+    # Resample forces
+    forces = case_data.get("forces")
+    if forces is not None and forces.ndim == 2:
+        result["forces"] = phase_resample(
+            forces, selected_crossings, n_pts=n_pts
+        )
+
+    # Resample actions
+    actions = case_data.get("actions")
+    if actions is not None and actions.ndim == 2:
+        result["actions"] = phase_resample(
+            actions, selected_crossings, n_pts=n_pts
+        )
+
+    # Resample field data (lazy-loaded if available)
+    ux = None
+    uy = None
+    loader = case_data.get("_fields_loader")
+    if loader is not None:
+        fields_npz = loader()
+        if "ux" in fields_npz and "uy" in fields_npz:
+            ux = fields_npz["ux"]
+            uy = fields_npz["uy"]
+    if ux is not None and uy is not None:
+        n_fields = len(ux)
+        n_sensors = len(sensors)
+
+        # Fields and sensors are sampled at different rates
+        # Fields are saved at save_interval within each PPO step
+        # Sensors are saved once per PPO step
+        # The ratio is approximately T_ref / n_pts / sample_interval
+
+        # Convert crossing indices from sensor-space to field-space
+        # Simple approach: resample fields using the same crossing indices
+        # Since fields may have different count, use normalized indices
+        field_crossings = [
+            int(c * n_fields / n_sensors) for c in selected_crossings
+        ]
+        field_crossings = [max(0, min(c, n_fields - 1)) for c in field_crossings]
+        # Deduplicate and ensure > n_cycles+1 entries
+        field_crossings = sorted(set(field_crossings))
+
+        if len(field_crossings) >= 2:
+            # Stack ux and uy into single array
+            nx, ny = ux.shape[1], ux.shape[2]
+            field_flat = np.column_stack([
+                ux.reshape(n_fields, -1), uy.reshape(n_fields, -1)
+            ])
+            resampled_fields = phase_resample(
+                field_flat, field_crossings[:n_cycles + 1], n_pts=n_pts
+            )
+            # Unflatten
+            n_cycle_actual, n_pt, n_dim = resampled_fields.shape
+            half = n_dim // 2
+            result["ux"] = resampled_fields[:, :, :half].reshape(
+                n_cycle_actual, n_pt, ny, nx
+            )
+            result["uy"] = resampled_fields[:, :, half:].reshape(
+                n_cycle_actual, n_pt, ny, nx
+            )
+
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main():
+    # Load Phase 0 reference data
+    ref_path = os.path.join(OUTPUT_DIR, "target_cylinder", "meta.json")
+    if not os.path.exists(ref_path):
+        print("ERROR: Phase 0 data not found. Run phase0_standard_freq.py first.")
+        return 1
+
+    with open(ref_path, "r") as f:
+        ref = json.load(f)
+
+    f_ref = ref["f_ref"]
+    T_ref = ref["T_ref"]
+    print(f"Reference: f_ref={f_ref:.6f}, T_ref={T_ref:.0f} steps, St={ref['St']:.4f}")
+    print()
+
+    # Load all periodic cases
+    periodic_cases = ["target_cylinder", "illusion", "uncontrolled"]
+
+    all_raw = {}
+    for case in periodic_cases:
+        print(f"Loading {case}...")
+        all_raw[case] = load_case_raw(case)
+        if all_raw[case].get("exists"):
+            nf = "lazy"
+            ns = len(all_raw[case].get("sensors", []))
+            print(f"  fields={nf}, sensors={ns}")
+
+    # Check period stability
+    print("\n=== Period Stability Check ===")
+    results = []
+    for case in periodic_cases:
+        data = all_raw[case]
+        if not data.get("exists"):
+            print(f"  {case}: NO DATA, skipping")
+            continue
+        r = check_period_stability(
+            data, f_ref, T_ref, St=ref["St"],
+            case_U0=data.get("U0", 0.01),
+        )
+        results.append(r)
+        status = r["gate"].upper()
+        print(f"  {case}: {status}  f_case={r['f_case']:.6f}  "
+              f"CV_T={r['CV_T']:.4f}  delta_f={r['delta_f']:.4f}  "
+              f"T_samples={r['mean_T_samples']:.1f}  "
+              f"N_raw/cycle={r.get('N_raw_per_cycle', '?'):.1f}  "
+              f"interp={r.get('interp_quality', '?')}")
+
+    # Save stability report
+    os.makedirs(os.path.join(OUTPUT_DIR, "resampled"), exist_ok=True)
+    with open(os.path.join(OUTPUT_DIR, "resampled", "stability_report.json"), "w") as f:
+        json.dump({
+            "f_ref": f_ref,
+            "T_ref": T_ref,
+            "St": ref["St"],
+            "thresholds": {
+                "CV_T_strict": CV_T_THRESHOLD_STRICT,
+                "CV_T_relaxed": CV_T_THRESHOLD_RELAXED,
+                "delta_f_strict": DELTA_F_THRESHOLD_STRICT,
+                "delta_f_relaxed": DELTA_F_THRESHOLD_RELAXED,
+            },
+            "cases": results,
+        }, f, indent=2)
+
+    # Phase resample for qualifying cases
+    print("\n=== Phase Resampling ===")
+    qualifying = [r for r in results if r.get("gate") in ("strict", "relaxed")]
+    falling = [r for r in results if r.get("gate") not in ("strict", "relaxed")]
+
+    strict_cases = [r["case"] for r in results if r.get("gate") == "strict"]
+    relaxed_cases = [r["case"] for r in results if r.get("gate") == "relaxed"]
+    print(f"Strict (main POD basis): {strict_cases}")
+    print(f"Relaxed (projection): {relaxed_cases}")
+    print(f"Auxiliary/falling: {[r['case'] for r in falling]}")
+
+    for r in qualifying:
+        case_name = r["case"]
+        print(f"\nResampling {case_name} (strict)...")
+        data = all_raw[case_name]
+        result = extract_and_resample(data, f_ref, T_ref, St=ref["St"])
+
+        if result.get("resampled"):
+            out_dir = os.path.join(OUTPUT_DIR, "resampled", case_name)
+            os.makedirs(out_dir, exist_ok=True)
+
+            # Save resampled data
+            save_dict = {
+                "sensors": result["sensors"],  # (n_cycles, n_pts, 6)
+                "n_cycles": result["sensors"].shape[0],
+                "n_pts": result["sensors"].shape[1],
+            }
+            if "forces" in result:
+                save_dict["forces"] = result["forces"]
+            if "actions" in result:
+                save_dict["actions"] = result["actions"]
+            if "ux" in result and "uy" in result:
+                save_dict["ux"] = result["ux"]
+                save_dict["uy"] = result["uy"]
+
+            np.savez_compressed(os.path.join(out_dir, "resampled.npz"), **save_dict)
+
+            # Also save metadata
+            meta = {
+                "case": case_name,
+                "f_ref": f_ref,
+                "T_ref": T_ref,
+                "n_cycles": int(result["sensors"].shape[0]),
+                "n_pts": int(result["sensors"].shape[1]),
+                "selected_crossings": [int(c) for c in result["selected_crossings"]],
+                "has_fields": "ux" in result,
+            }
+            with open(os.path.join(out_dir, "meta.json"), "w") as f:
+                json.dump(meta, f, indent=2)
+
+            sh = result["sensors"].shape
+            print(f"  Resampled: {sh}, fields={'yes' if meta['has_fields'] else 'no'}")
+        else:
+            print(f"  Resampling failed: {result.get('reason', 'unknown')}")
+
+    # Also resample relaxed cases (Scheme A — projection only, no common POD)
+    # Also resample relaxed cases (projection only, no POD basis training)
+    for r in results:
+        if r.get("gate") != "relaxed":
+            continue
+        case_name = r["case"]
+        if case_name in [q["case"] for q in qualifying]:
+            continue  # already done above
+        print(f"\nResampling {case_name} (relaxed, projection)...")
+        data = all_raw[case_name]
+        result = extract_and_resample(data, f_ref, T_ref, St=ref["St"])
+        if result.get("resampled"):
+            out_dir = os.path.join(OUTPUT_DIR, "resampled", case_name)
+            os.makedirs(out_dir, exist_ok=True)
+            save_dict = {
+                "sensors": result["sensors"],
+                "n_cycles": result["sensors"].shape[0],
+                "n_pts": result["sensors"].shape[1],
+            }
+            if "forces" in result:
+                save_dict["forces"] = result["forces"]
+            if "actions" in result:
+                save_dict["actions"] = result["actions"]
+            if "ux" in result and "uy" in result:
+                save_dict["ux"] = result["ux"]
+                save_dict["uy"] = result["uy"]
+            np.savez_compressed(os.path.join(out_dir, "resampled.npz"), **save_dict)
+            meta = {"case": case_name, "f_ref": f_ref, "T_ref": T_ref,
+                    "n_cycles": int(result["sensors"].shape[0]),
+                    "n_pts": int(result["sensors"].shape[1]),
+                    "selected_crossings": [int(c) for c in result["selected_crossings"]],
+                    "gate": "relaxed"}
+            with open(os.path.join(out_dir, "meta.json"), "w") as f:
+                json.dump(meta, f, indent=2)
+            print(f"  Resampled (relaxed): {result['sensors'].shape}")
+        else:
+            print(f"  Resampling failed: {result.get('reason', 'unknown')}")
+
+    # Save resampling summary
+    summary = {"strict": strict_cases,
+               "relaxed": relaxed_cases,
+               "auxiliary": [r["case"] for r in results if r.get("gate") not in ("strict", "relaxed")]}
+    with open(os.path.join(OUTPUT_DIR, "resampled", "summary.json"), "w") as f:
+        json.dump(summary, f, indent=2)
+
+    print("\nPhase 2 complete.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

src/CCD_analysis/scripts/phase3_pod.py

@@ -0,0 +1,218 @@
+# CCD_analysis/scripts/phase3_pod.py
+"""Phase 3: Reference POD basis on phase-resampled periodic cases.
+
+Builds POD basis from strict-qualifying cases (target_cylinder + illusion).
+Non-qualifying cases (uncontrolled) are projected onto this basis.
+
+Output::
+    - output/pod/reference_pod_results.npz
+    - output/pod/reference_pod_metrics.json
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+
+import numpy as np
+
+_ANALYSIS = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+if _ANALYSIS not in sys.path:
+    sys.path.insert(0, _ANALYSIS)
+
+from scripts.cfg import OUTPUT_DIR, NX, NY
+from scripts.analysis_utils import (
+    compute_pod, cumulative_energy, e95_index,
+    stack_velocity_fields, unstack_velocity_modes,
+)
+
+R_CANDIDATES = [6, 8, 10]  # POD truncation levels to test
+
+
+def load_resampled(case_name: str) -> dict:
+    """Load resampled data for a case. Returns dict or None."""
+    resample_dir = os.path.join(OUTPUT_DIR, "resampled", case_name)
+    data_path = os.path.join(resample_dir, "resampled.npz")
+    meta_path = os.path.join(resample_dir, "meta.json")
+
+    if not os.path.exists(data_path):
+        print(f"  {case_name}: no resampled data at {data_path}")
+        return None
+
+    data = np.load(data_path)
+    meta = {}
+    if os.path.exists(meta_path):
+        with open(meta_path) as f:
+            meta = json.load(f)
+
+    return {"data": data, "meta": meta, "name": case_name}
+
+
+def main():
+    print("=== Phase 3: Common POD ===\n")
+
+    # Load summary from Phase 2
+    summary_path = os.path.join(OUTPUT_DIR, "resampled", "summary.json")
+    if not os.path.exists(summary_path):
+        print("ERROR: Run Phase 2 first.")
+        return 1
+
+    with open(summary_path) as f:
+        summary = json.load(f)
+
+    strict_cases = summary.get("strict", [])
+    relaxed_cases = summary.get("relaxed", [])
+    failed_cases = summary.get("failed", [])
+
+    print(f"  Strict: {strict_cases}")
+    print(f"  Relaxed (projected): {relaxed_cases}")
+    print(f"  Failed: {failed_cases}")
+
+    if not strict_cases:
+        print("ERROR: No strict-qualifying cases for common POD.")
+        return 1
+
+    # Load all resampled data
+    all_data = {}
+    for case in strict_cases + relaxed_cases:
+        d = load_resampled(case)
+        if d is not None:
+            all_data[case] = d
+
+    # Build snapshot matrix from strict cases
+    print("\nBuilding common POD snapshot matrix...")
+    snapshots = []
+    case_ranges = {}  # {case_name: (start_idx, end_idx)}
+
+    current_idx = 0
+    for case in strict_cases:
+        if case not in all_data:
+            continue
+        data = all_data[case]["data"]
+        ux = data.get("ux")
+        uy = data.get("uy")
+        if ux is None or uy is None:
+            print(f"  WARNING: {case} has no field data, skipping")
+            continue
+
+        # Flatten each resampled snapshot
+        n_cycles, n_pts = ux.shape[0], ux.shape[1]
+        for c in range(n_cycles):
+            for p in range(n_pts):
+                q = np.concatenate([
+                    ux[c, p].ravel(),
+                    uy[c, p].ravel(),
+                ])
+                snapshots.append(q)
+
+        case_ranges[case] = (current_idx, current_idx + n_cycles * n_pts)
+        current_idx += n_cycles * n_pts
+        print(f"  {case}: {n_cycles}x{n_pts} = {n_cycles*n_pts} snapshots")
+
+    if not snapshots:
+        print("ERROR: No field data for POD.")
+        return 1
+
+    Q = np.column_stack(snapshots)  # (2*nx*ny, N)
+    print(f"  Snapshot matrix: {Q.shape[0]} x {Q.shape[1]}")
+
+    # Compute POD
+    print("\nComputing POD...")
+    mean_field, modes, s, coeffs = compute_pod(Q)
+    energy = cumulative_energy(s)
+    e95 = e95_index(energy)
+
+    print(f"  Modes: {len(s)}")
+    print(f"  E95 = {e95}")
+    for i in range(min(10, len(s))):
+        print(f"    mode {i+1}: energy={energy[i]:.4f}, sigma={s[i]:.4e}")
+
+    # Project relaxed cases onto the POD basis
+    projection_coeffs = {}  # {case_name: coeffs_matrix}
+    for case in relaxed_cases:
+        if case not in all_data:
+            continue
+        data = all_data[case]["data"]
+        ux = data.get("ux")
+        uy = data.get("uy")
+        if ux is None or uy is None:
+            print(f"  WARNING: {case} has no field data for projection")
+            continue
+
+        proj_snapshots = []
+        n_cycles, n_pts = ux.shape[0], ux.shape[1]
+        for c in range(n_cycles):
+            for p in range(n_pts):
+                q = np.concatenate([ux[c, p].ravel(), uy[c, p].ravel()])
+                proj_snapshots.append(q)
+
+        Q_proj = np.column_stack(proj_snapshots)
+        # Remove mean field (from strict POD)
+        Q_proj_centered = Q_proj - mean_field[:, None]
+        # Project: coefficients = modes^T @ Q
+        coeffs_proj = modes[:, :R_CANDIDATES[-1]].T @ Q_proj_centered
+        projection_coeffs[case] = coeffs_proj
+        print(f"  {case}: projected {Q_proj.shape[1]} snapshots")
+
+    # Compute case centroids in a1-a2 phase space
+    print("\nCase centroids (a1, a2):")
+    centroids = {}
+    for case in strict_cases:
+        if case not in case_ranges:
+            continue
+        start, end = case_ranges[case]
+        a1 = np.mean(coeffs[0, start:end])
+        a2 = np.mean(coeffs[1, start:end])
+        centroids[case] = [float(a1), float(a2)]
+        print(f"  {case}: a1={a1:.4f}, a2={a2:.4f}")
+
+    for case, coeffs_p in projection_coeffs.items():
+        a1 = np.mean(coeffs_p[0])
+        a2 = np.mean(coeffs_p[1])
+        centroids[case] = [float(a1), float(a2)]
+        print(f"  {case}: a1={a1:.4f}, a2={a2:.4f}")
+
+    # Save results
+    out_dir = os.path.join(OUTPUT_DIR, "pod")
+    os.makedirs(out_dir, exist_ok=True)
+
+    # POD results
+    np.savez_compressed(os.path.join(out_dir, "pod_results.npz"),
+                        mean_field=mean_field,
+                        modes=modes[:, :R_CANDIDATES[-1]],
+                        singular_values=s,
+                        coefficients=coeffs[:R_CANDIDATES[-1]],
+                        energy_ratio=energy[:R_CANDIDATES[-1]],
+                        )
+
+    # Save projection coefficients for relaxed cases
+    for case, c in projection_coeffs.items():
+        np.savez(os.path.join(out_dir, f"projection_{case}.npz"),
+                 coefficients=c)
+
+    # Metrics
+    pod_metrics = {
+        "n_total_modes": len(s),
+        "E95": int(e95),
+        "energy_first_2": float(energy[1]) if len(energy) > 1 else float(energy[0]),
+        "energy_first_6": float(energy[min(5, len(energy)-1)]),
+        "singular_values": [float(v) for v in s[:R_CANDIDATES[-1]]],
+        "energy_ratio": [float(v) for v in energy[:R_CANDIDATES[-1]]],
+        "case_centroids": centroids,
+        "case_ranges": {k: [int(v[0]), int(v[1])] for k, v in case_ranges.items()},
+        "n_strict_cases": len(strict_cases),
+        "strict_cases": strict_cases,
+        "relaxed_cases": relaxed_cases,
+    }
+    with open(os.path.join(out_dir, "pod_metrics.json"), "w") as f:
+        json.dump(pod_metrics, f, indent=2)
+
+    print(f"\nResults saved to {out_dir}")
+    print("Phase 3 complete.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

src/CCD_analysis/scripts/phase4_ccd.py

@@ -0,0 +1,332 @@
+# CCD_analysis/scripts/phase4_ccd.py
+"""Phase 4: CCD analysis on POD coefficients.
+
+Computes:
+  - force-CCD (all periodic cases): total Fx, Fy
+  - action-CCD (illusion only): [Omega_front, Omega_bottom, Omega_top]
+  - signature-CCD (illusion only): e_s(t+tau_c)
+  - Modal overlap O_k between case pairs
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+import numpy as np
+
+_ANALYSIS = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+if _ANALYSIS not in sys.path:
+    sys.path.insert(0, _ANALYSIS)
+
+from scripts.cfg import OUTPUT_DIR
+from scripts.analysis_utils import compute_reduced_ccd, cumulative_energy
+
+R_CANDIDATES = [6, 8, 10]
+CCD_Q = 12
+
+
+def load_resampled_coeffs(case_name: str, r: int) -> np.ndarray:
+    """Load POD coefficients from projection or strict POD."""
+    proj_path = os.path.join(OUTPUT_DIR, "pod", f"projection_{case_name}.npz")
+    if os.path.exists(proj_path):
+        data = np.load(proj_path)
+        return data["coefficients"][:r]
+
+    pod_path = os.path.join(OUTPUT_DIR, "pod", "pod_results.npz")
+    metrics_path = os.path.join(OUTPUT_DIR, "pod", "pod_metrics.json")
+    if os.path.exists(pod_path) and os.path.exists(metrics_path):
+        pod = np.load(pod_path)
+        with open(metrics_path) as f:
+            metrics = json.load(f)
+        cr = metrics.get("case_ranges", {})
+        if case_name in cr:
+            start, end = cr[case_name]
+            return pod["coefficients"][:r, start:end]
+    return None
+
+
+def load_resampled_signals(case_name: str, key: str = "sensors", n_channels: int = 6) -> np.ndarray:
+    """Load resampled signal and return (n_channels, N)."""
+    path = os.path.join(OUTPUT_DIR, "resampled", case_name, "resampled.npz")
+    if not os.path.exists(path):
+        return None
+    data = np.load(path)
+    arr = data.get(key)
+    if arr is None:
+        return None
+    if key == "forces":
+        arr_2d = arr.reshape(-1, arr.shape[-1])
+        if arr_2d.shape[1] == 2:
+            return arr_2d.T
+        f = arr_2d
+        Fx = (f[:, 0] + f[:, 2] + f[:, 4])
+        Fy = (f[:, 1] + f[:, 3] + f[:, 5])
+        return np.vstack([Fx, Fy])
+    if key == "actions":
+        return arr.reshape(-1, arr.shape[-1]).T
+    return arr.reshape(-1, arr.shape[-1]).T
+
+
+def compute_ccd_metrics(case: str, coeffs: np.ndarray, observable: np.ndarray, obs_name: str) -> dict:
+    """Compute CCD metrics for a single case-observable pair."""
+    N = coeffs.shape[1]
+    N_train = N * 3 // 4
+    a_train = coeffs[:, :N_train]
+    a_test = coeffs[:, N_train:]
+    y_train = observable[:, :N_train]
+    y_test = observable[:, N_train:]
+
+    r = coeffs.shape[0]
+
+    # CCD
+    W, sigma, z = compute_reduced_ccd(coeffs, observable, Q_delay=CCD_Q)
+    ccd_ene = cumulative_energy(sigma)
+    m80 = int(np.searchsorted(ccd_ene, 0.80) + 1) if len(ccd_ene) > 0 else 0
+
+    # POD regression
+    W_pod = y_train @ a_train.T @ np.linalg.pinv(a_train @ a_train.T + 1e-8 * np.eye(r))
+    y_pred_pod = W_pod @ a_test
+    y_test_r = y_test.ravel()
+    y_pred_pod_r = y_pred_pod.ravel()
+    if np.std(y_test_r) > 1e-12 and np.std(y_pred_pod_r) > 1e-12:
+        corr_pod = float(np.corrcoef(y_pred_pod_r, y_test_r)[0, 1])
+    else:
+        corr_pod = 0.0
+
+    # CCD regression
+    n_ccd = min(r, z.shape[0])
+    z_train = z[:n_ccd, :N_train]
+    z_test = z[:n_ccd, N_train:]
+    W_reg_ccd = y_train @ z_train.T @ np.linalg.pinv(z_train @ z_train.T + 1e-8 * np.eye(n_ccd))
+    y_pred_ccd = W_reg_ccd @ z_test
+    y_pred_ccd_r = y_pred_ccd.ravel()
+    if np.std(y_test_r) > 1e-12 and np.std(y_pred_ccd_r) > 1e-12:
+        corr_ccd = float(np.corrcoef(y_pred_ccd_r, y_test_r)[0, 1])
+    else:
+        corr_ccd = 0.0
+
+    # Top CCD mode correlations with observable
+    n_corr = min(5, len(sigma))
+    corr_z = []
+    for k in range(n_corr):
+        zk_train = z[k, :N_train]
+        if np.std(zk_train) > 1e-12:
+            rho = float(np.corrcoef(zk_train, observable[0, :N_train])[0, 1])
+        else:
+            rho = 0.0
+        corr_z.append(rho)
+
+    return {
+        "case": case,
+        "observable": obs_name,
+        "r": r,
+        "sigma": [float(s) for s in sigma[:n_corr]],
+        "ccd_energy": [float(e) for e in ccd_ene[:n_corr]],
+        "m80": int(m80),
+        "corr_POD_obs": corr_pod,
+        "corr_CCD_obs": corr_ccd,
+        "corr_z_top5": corr_z,
+        "N_total": int(N),
+        "N_train": int(N_train),
+        "N_test": int(N - N_train),
+    }
+
+
+def compute_modal_overlap(W_dict: dict, case_pairs: list) -> dict:
+    """Compute modal overlap O_k between cases.
+
+    O_k(A, B) = |W[:,k]_A^T @ W[:,k]_B|
+    Higher means the k-th CCD direction is more aligned between cases.
+    """
+    overlap = {}
+    for case_a, case_b in case_pairs:
+        if case_a not in W_dict or case_b not in W_dict:
+            continue
+        Wa = W_dict[case_a]
+        Wb = W_dict[case_b]
+        n = min(Wa.shape[1], Wb.shape[1])
+        pair_key = f"O_{case_a}_{case_b}"
+        pair_vals = []
+        for k in range(min(n, 5)):
+            ak = Wa[:, k] / (np.linalg.norm(Wa[:, k]) + 1e-12)
+            bk = Wb[:, k] / (np.linalg.norm(Wb[:, k]) + 1e-12)
+            pair_vals.append(float(abs(ak @ bk)))
+        overlap[pair_key] = pair_vals
+    return overlap
+
+
+def load_target_signals(case_name: str) -> np.ndarray:
+    """Load target_cylinder resampled sensors as reference signature.
+    
+    Since target_cylinder is at U0=0.01 and illusion at U0=0.02,
+    signals are amplitude-normalized by their respective RMS.
+    """
+    # Use target_cylinder resampled sensors as reference
+    ref_path = os.path.join(OUTPUT_DIR, "resampled", "target_cylinder", "resampled.npz")
+    if not os.path.exists(ref_path):
+        return None
+    ref = np.load(ref_path)
+    sensors_ref = ref.get("sensors")  # (n_cycles, n_pts, 6)
+    if sensors_ref is None:
+        return None
+    return sensors_ref.reshape(-1, sensors_ref.shape[-1]).T  # (6, N)
+
+
+def main():
+    print("=== Phase 4: CCD Analysis ===\n")
+
+    metrics_path = os.path.join(OUTPUT_DIR, "pod", "pod_metrics.json")
+    if not os.path.exists(metrics_path):
+        print("ERROR: Run Phase 3 first.")
+        return 1
+    with open(metrics_path) as f:
+        pod_metrics = json.load(f)
+
+    all_cases = pod_metrics.get("strict_cases", []) + pod_metrics.get("relaxed_cases", [])
+    all_results = {}
+    W_dict = {}  # {case_observable_r: W_matrix}
+
+    for r in R_CANDIDATES:
+        print(f"\n{'='*60}")
+        print(f"POD truncation r={r}")
+        print(f"{'='*60}")
+
+        # ----- 1. Force-CCD (all cases) -----
+        print("\n--- Force-CCD ---")
+        for case in all_cases:
+            coeffs = load_resampled_coeffs(case, r)
+            if coeffs is None:
+                continue
+            y_force = load_resampled_signals(case, "forces", 2)
+            if y_force is None:
+                print(f"  {case}: no force data")
+                continue
+            if y_force.shape[-1] != coeffs.shape[1]:
+                print(f"  {case}: force length mismatch, skipping")
+                continue
+
+            # CCD computation
+            W, sigma, z = compute_reduced_ccd(coeffs, y_force, Q_delay=CCD_Q)
+            ccd_ene = cumulative_energy(sigma)
+            m80 = int(np.searchsorted(ccd_ene, 0.80) + 1)
+
+            key = f"{case}_force_r{r}"
+            W_dict[key] = W
+            all_results[key] = compute_ccd_metrics(case, coeffs, y_force, "force_CCD")
+            print(f"  {case}: m80={all_results[key]['m80']}, "
+                  f"sigma={sigma[0]:.3f},{sigma[1]:.3f}")
+
+        # ----- 2. Action-CCD (illusion only) -----
+        print("\n--- Action-CCD (illusion only) ---")
+        if "illusion" in all_cases:
+            coeffs = load_resampled_coeffs("illusion", r)
+            if coeffs is not None:
+                y_act = load_resampled_signals("illusion", "actions", 3)
+                if y_act is not None and y_act.shape[-1] == coeffs.shape[1]:
+                    key = f"illusion_action_r{r}"
+                    W, sigma, z = compute_reduced_ccd(coeffs, y_act, Q_delay=CCD_Q)
+                    W_dict[key] = W
+                    all_results[key] = compute_ccd_metrics(
+                        "illusion", coeffs, y_act, "action_CCD")
+                    print(f"  illusion: m80={all_results[key]['m80']}, "
+                          f"sigma={sigma[0]:.3f},{sigma[1]:.3f}")
+                else:
+                    print(f"  illusion: no action data (y={y_act.shape if y_act is not None else None}, "
+                          f"N={coeffs.shape[1]})")
+
+        # ----- 3. Signature-CCD (illusion only, tau_c=0) -----
+        print("\n--- Signature-CCD (illusion only, tau_c=0) ---")
+        if "illusion" in all_cases:
+            coeffs = load_resampled_coeffs("illusion", r)
+            if coeffs is not None:
+                # Load actual sensors
+                sensors = load_resampled_signals("illusion", "sensors", 6)
+                # Load target sensors
+                target_sensors = load_target_signals("illusion")
+                if sensors is not None and target_sensors is not None and sensors.shape == target_sensors.shape:
+                    # e_s(t) = s(t) - s_tar(t)
+                    e_s = sensors - target_sensors
+                    key = f"illusion_signature_r{r}"
+                    W, sigma, z = compute_reduced_ccd(coeffs, e_s, Q_delay=CCD_Q)
+                    W_dict[key] = W
+                    all_results[key] = compute_ccd_metrics(
+                        "illusion", coeffs, e_s, "signature_CCD")
+                    print(f"  illusion: m80={all_results[key]['m80']}, "
+                          f"sigma={sigma[0]:.3f},{sigma[1]:.3f}")
+                else:
+                    print(f"  illusion: signature data issue "
+                          f"(sensors={sensors.shape if sensors is not None else None}, "
+                          f"target={target_sensors.shape if target_sensors is not None else None})")
+
+    # ----- Modal Overlap O_k -----
+    print("\n--- Modal Overlap O_k ---")
+    all_obs_keys = [k for k in all_results.keys()]
+    pair_results = {}
+    for r in R_CANDIDATES:
+        # Force-CCD overlap between strict cases
+        strict_cases = pod_metrics.get("strict_cases", [])
+        for i, ca in enumerate(strict_cases):
+            for cb in strict_cases[i+1:]:
+                key_a = f"{ca}_force_r{r}"
+                key_b = f"{cb}_force_r{r}"
+                if key_a in W_dict and key_b in W_dict:
+                    Wa = W_dict[key_a]
+                    Wb = W_dict[key_b]
+                    n = min(Wa.shape[1], Wb.shape[1], 5)
+                    ov = []
+                    for k in range(n):
+                        ak = Wa[:, k] / (np.linalg.norm(Wa[:, k]) + 1e-12)
+                        bk = Wb[:, k] / (np.linalg.norm(Wb[:, k]) + 1e-12)
+                        ov.append(float(abs(ak @ bk)))
+                    pk = f"O_{ca}_{cb}_force_r{r}"
+                    pair_results[pk] = ov
+                    print(f"  {ca} vs {cb} (force, r={r}): "
+                          f"O1={ov[0]:.4f}, O2={ov[1]:.4f}")
+
+        # Also compare illusion to target in action and signature space
+        if "illusion" in all_cases:
+            ia_key = f"illusion_action_r{r}"
+            is_key = f"illusion_signature_r{r}"
+            for tc in strict_cases:
+                tf_key = f"{tc}_force_r{r}"
+                if ia_key in W_dict and tf_key in W_dict:
+                    Wa = W_dict[ia_key]
+                    Wb = W_dict[tf_key]
+                    n = min(Wa.shape[1], Wb.shape[1], 5)
+                    ov = []
+                    for k in range(n):
+                        ak = Wa[:, k] / (np.linalg.norm(Wa[:, k]) + 1e-12)
+                        bk = Wb[:, k] / (np.linalg.norm(Wb[:, k]) + 1e-12)
+                        ov.append(float(abs(ak @ bk)))
+                    pk = f"O_action_vs_force_{tc}_r{r}"
+                    pair_results[pk] = ov
+                    print(f"  action vs {tc}-force (r={r}): "
+                          f"O1={ov[0]:.4f}, O2={ov[1]:.4f}")
+
+    # Save
+    out_dir = os.path.join(OUTPUT_DIR, "ccd")
+    os.makedirs(out_dir, exist_ok=True)
+    all_results["modal_overlaps"] = pair_results
+    with open(os.path.join(out_dir, "ccd_metrics.json"), "w") as f:
+        json.dump(all_results, f, indent=2)
+
+    # Summary
+    print(f"\n{'='*70}")
+    print("Summary: CCD metrics")
+    print(f"{'='*70}")
+    for key in sorted([k for k in all_results.keys() if k != "modal_overlaps"]):
+        m = all_results[key]
+        sig = m.get("sigma", [0, 0])
+        print(f"  {key:<40} m80={m['m80']}  "
+              f"sigma=[{sig[0]:.3f},{sig[1] if len(sig)>1 else 0:.3f}]  "
+              f"corr_CCD={m['corr_CCD_obs']:.4f}")
+
+    print(f"\nSaved to {out_dir}/ccd_metrics.json")
+    print("Phase 4 complete.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

src/CCD_analysis/scripts/phase5_steady.py

@@ -0,0 +1,232 @@
+# CCD_analysis/scripts/phase5_steady.py
+"""
+WARNING: This script has known issues.
+- E_mean_uy calculation explodes because empty_channel uy ~ 0 (denominator near zero)
+- eta_fluc is negative because cloak and uncontrolled use different pinball positions
+  (cloak uses standard layout FRONT/BOTTOM/TOP, uncontrolled may differ)
+- L_r (recirculation zone length) = 0, which may indicate incorrect u=0 detection logic
+  Need to verify against actual flow fields.
+
+Use this as reference only. Do NOT use resulting metrics for conclusions without validation.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+import numpy as np
+
+_ANALYSIS = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+if _ANALYSIS not in sys.path:
+    sys.path.insert(0, _ANALYSIS)
+
+from scripts.cfg import OUTPUT_DIR, NX, NY
+
+
+def load_fields(case_name: str):
+    """Load fields.npz for a case, return (ux, uy) as (N, NY, NX)."""
+    path = os.path.join(OUTPUT_DIR, case_name, "fields.npz")
+    if not os.path.exists(path):
+        return None
+    data = np.load(path)
+    return data["ux"].astype(np.float64), data["uy"].astype(np.float64)
+
+
+def load_sensors(case_name: str):
+    """Load sensors.npz for a case."""
+    path = os.path.join(OUTPUT_DIR, case_name, "sensors.npz")
+    if not os.path.exists(path):
+        return None
+    return np.load(path)
+
+
+def compute_mean_rms(ux, uy):
+    """Compute mean and RMS fields from time series."""
+    ux_mean = np.mean(ux, axis=0)
+    uy_mean = np.mean(uy, axis=0)
+    ux_rms = np.sqrt(np.mean((ux - ux_mean) ** 2, axis=0))
+    uy_rms = np.sqrt(np.mean((uy - uy_mean) ** 2, axis=0))
+    return ux_mean, uy_mean, ux_rms, uy_rms
+
+
+def recirculation_metrics(ux_mean):
+    """Extract recirculation zone from mean ux field.
+
+    Returns (L_r, A_r) where:
+      L_r = length of recirculation zone along centerline
+      A_r = area of recirculation zone (u < 0)
+    """
+    ny, nx = ux_mean.shape
+    center_y = ny // 2
+    margin = 10
+
+    # Centerline ux
+    cline = ux_mean[center_y, :]
+
+    # Find u=0 crossings behind the pinball (x > 400 or so)
+    start_x = 400
+    end_x = nx - 50
+    roi = cline[start_x:end_x]
+    neg = np.where(roi < 0)[0]
+    if len(neg) > 0:
+        # Recirculation length = distance from end of negative region
+        neg_end = neg[-1] + start_x
+        L_r = float(neg_end - 400)
+    else:
+        L_r = 0.0
+
+    # Area: count cells with u < 0 in the wake region
+    wake_region = ux_mean[:, 300:800]
+    area_mask = wake_region < 0
+    A_r = float(np.sum(area_mask) * 1.0)  # in lattice cells
+
+    return L_r, A_r
+
+
+def main():
+    print("=== Phase 5: Cloak Steady-Line Analysis ===\n")
+
+    # Load data
+    cloak_fields = load_fields("cloak")
+    if cloak_fields is None:
+        print("ERROR: No cloak fields found. Run Phase 1b first.")
+        return 1
+    ux_c, uy_c = cloak_fields
+
+    channel_fields = load_fields("empty_channel")
+    if channel_fields is None:
+        print("ERROR: No empty_channel fields found. Run Phase 1d first.")
+        return 1
+    ux_ch, uy_ch = channel_fields
+
+    unc_fields = load_fields("uncontrolled")
+    if unc_fields is None:
+        print("WARNING: No uncontrolled fields for comparison.")
+        unc_fields = None
+
+    cloak_sens = load_sensors("cloak")
+    if cloak_sens is None:
+        print("ERROR: No cloak sensors found.")
+        return 1
+
+    # Compute mean and RMS
+    ux_c_mean, uy_c_mean, ux_c_rms, uy_c_rms = compute_mean_rms(ux_c, uy_c)
+    ux_ch_mean, uy_ch_mean, _, _ = compute_mean_rms(ux_ch, uy_ch)
+
+    # 1. E_mean: mean flow relative error (vs empty channel), normalized by U0
+    ux_err = np.mean((ux_c_mean - ux_ch_mean) ** 2)
+    ux_ref = np.mean(ux_ch_mean ** 2) + 1e-12
+    E_mean_ux = float(ux_err / ux_ref)
+    E_mean_uy = float(np.mean((uy_c_mean - uy_ch_mean) ** 2)) / (np.mean(uy_ch_mean ** 2) + 1e-12)
+    E_mean = (E_mean_ux + E_mean_uy) / 2.0
+    print(f"1. E_mean (rel. to empty channel):")
+    print(f"   ux error={E_mean_ux:.4f}, uy error={E_mean_uy:.4f}, avg={E_mean:.4f}")
+
+    # 2. E_sensor_mean
+    sensors = cloak_sens["sensors"]
+    forces = cloak_sens["forces"]
+    sensor_mean = np.mean(sensors, axis=0)
+    # Target empty channel: U0=0.01 parabolic, sensor ux should be near U0, uy near 0
+    sensor_target_mean = np.array([1.0, 0.0, 1.0, 0.0, 1.0, 0.0], dtype=np.float32)
+    E_sensor_mean = float(np.mean(np.abs(sensor_mean - sensor_target_mean)))
+    print(f"2. E_sensor_mean = {E_sensor_mean:.4f} "
+          f"(sensor_mean={sensor_mean[:3].tolist()})")
+
+    # 3. eta_fluc: fluctuation suppression ratio
+    if unc_fields is not None:
+        ux_unc, uy_unc = unc_fields
+        # Use first 30 frames of uncontrolled for fair comparison
+        n_compare = min(len(ux_c), len(ux_unc), 30)
+        ux_c_sub, uy_c_sub = ux_c[:n_compare], uy_c[:n_compare]
+        ux_unc_sub, uy_unc_sub = ux_unc[:n_compare], uy_unc[:n_compare]
+
+        # RMS in wake region only (300-800, full height)
+        wake_x_start, wake_x_end = 300, 800
+        ux_c_mean_s, uy_c_mean_s = np.mean(ux_c_sub, axis=0), np.mean(uy_c_sub, axis=0)
+        ux_unc_mean_s, uy_unc_mean_s = np.mean(ux_unc_sub, axis=0), np.mean(uy_unc_sub, axis=0)
+
+        rms_c = np.sqrt(np.mean((ux_c_sub - ux_c_mean_s) ** 2 + (uy_c_sub - uy_c_mean_s) ** 2, axis=0))
+        rms_unc = np.sqrt(np.mean((ux_unc_sub - ux_unc_mean_s) ** 2 + (uy_unc_sub - uy_unc_mean_s) ** 2, axis=0))
+
+        # Integrate RMS over wake region
+        int_rms_c = float(np.sum(rms_c[:, wake_x_start:wake_x_end]))
+        int_rms_unc = float(np.sum(rms_unc[:, wake_x_start:wake_x_end]))
+        eps = 1e-12
+        eta_fluc = 1.0 - int_rms_c / (int_rms_unc + eps)
+        print(f"3. eta_fluc = {eta_fluc:.4f} (wake region, first {n_compare} frames)")
+    else:
+        eta_fluc = 0.0
+        print("3. eta_fluc: skipped (no uncontrolled data)")
+
+    # 4. Recirculation zone
+    L_r_c, A_r_c = recirculation_metrics(ux_c_mean)
+    if unc_fields is not None:
+        ux_unc_mean = np.mean(ux_unc_sub, axis=0)
+        L_r_unc, A_r_unc = recirculation_metrics(ux_unc_mean)
+        print(f"4. Recirculation: cloak L_r={L_r_c:.0f}, A_r={A_r_c:.0f}  "
+              f"vs uncontrolled L_r={L_r_unc:.0f}, A_r={A_r_unc:.0f}")
+    else:
+        print(f"4. Recirculation: cloak L_r={L_r_c:.0f}, A_r={A_r_c:.0f}")
+
+    # 5. Force statistics
+    cloak_forces = forces
+    if len(cloak_forces) > 0:
+        fx = cloak_forces[:, 0::2]
+        fy = cloak_forces[:, 1::2]
+        sigma_F = float(np.std(np.sum(fx, axis=1) + np.sum(fy, axis=1)))
+        mean_Fx = float(np.mean(fx))
+        print(f"5. Force stats: sigma_F={sigma_F:.6f}, mean_Fx={mean_Fx:.6f}")
+
+    # 6. Control amplitude
+    ppo_rollout_path = os.path.join(OUTPUT_DIR, "cloak", "ppo_rollout.npz")
+    if os.path.exists(ppo_rollout_path):
+        pr = np.load(ppo_rollout_path)
+        steady_action = pr.get("steady_action")
+        if steady_action is not None:
+            J_omega_rms = float(np.sum(np.abs(steady_action)))
+            print(f"6. J_omega_rms = {J_omega_rms:.4f} (norm action sum abs)")
+
+    # 7. eta_cloak_obs (control efficiency proxy)
+    if unc_fields is not None:
+        unc_sens = load_sensors("uncontrolled")
+        if unc_sens is not None:
+            unc_sensor_mean = np.mean(unc_sens["sensors"], axis=0)
+            E_unc = float(np.mean(np.abs(unc_sensor_mean - sensor_target_mean)))
+            E_cloak = E_sensor_mean
+            J_omega = J_omega_rms if 'J_omega_rms' in dir() else 1.0
+            eta_cloak_obs = (E_unc - E_cloak) / (J_omega + 1e-12)
+            print(f"7. eta_cloak_obs = {eta_cloak_obs:.4f} "
+                  f"(E_unc={E_unc:.4f}, E_cloak={E_cloak:.4f})")
+
+    # Compile and save
+    steady_metrics = {
+        "E_mean_ux": E_mean_ux,
+        "E_mean_uy": E_mean_uy,
+        "E_mean_avg": E_mean,
+        "E_sensor_mean": E_sensor_mean,
+        "sensor_mean": sensor_mean.tolist(),
+        "eta_fluc": eta_fluc,
+        "L_r_cloak": L_r_c,
+        "A_r_cloak": A_r_c,
+        "sigma_F": sigma_F if 'sigma_F' in dir() else 0,
+        "mean_Fx": mean_Fx if 'mean_Fx' in dir() else 0,
+        "J_omega_rms": J_omega_rms if 'J_omega_rms' in dir() else 0,
+        "eta_cloak_obs": eta_cloak_obs if 'eta_cloak_obs' in dir() else 0,
+        "L_r_uncontrolled": L_r_unc if unc_fields is not None and 'L_r_unc' in dir() else None,
+        "A_r_uncontrolled": A_r_unc if unc_fields is not None and 'A_r_unc' in dir() else None,
+    }
+
+    out_dir = os.path.join(OUTPUT_DIR, "steady")
+    os.makedirs(out_dir, exist_ok=True)
+    with open(os.path.join(out_dir, "steady_metrics.json"), "w") as f:
+        json.dump(steady_metrics, f, indent=2)
+
+    print(f"\nSaved to {out_dir}/steady_metrics.json")
+    print("Phase 5 complete.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

src/CCD_analysis/scripts/utils.py

@@ -0,0 +1,308 @@
+# CCD_analysis/scripts/utils.py
+"""Shared utilities for CCD analysis pipeline.
+
+All CFD uses LegacyCelerisLab (old API). Must run under conda pycuda_3_10.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from typing import Any, Dict, List, Optional, Tuple
+
+import numpy as np
+
+# Add project root for LegacyCelerisLab import
+_REPO = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+if _REPO not in sys.path:
+    sys.path.insert(0, _REPO)
+
+from LegacyCelerisLab import FlowField  # noqa: E402
+from LegacyCelerisLab import utils as legacy_utils  # noqa: E402
+
+# ---------------------------------------------------------------------------
+# Config loading
+# ---------------------------------------------------------------------------
+
+def load_configs(config_dir: str) -> Tuple[Any, Any]:
+    """Load legacy (cuda_config, field_config) from config_dir."""
+    cuda_cfg = legacy_utils.load_cuda_config(
+        os.path.join(config_dir, "config_cuda.json")
+    )
+    field_cfg = legacy_utils.load_flow_field_config(
+        os.path.join(config_dir, "config_flowfield.json")
+    )
+    return cuda_cfg, field_cfg
+
+
+# ---------------------------------------------------------------------------
+# Field I/O from DDF (matches uni_test pattern)
+# ---------------------------------------------------------------------------
+
+def get_velocity_field(flow_field: FlowField, u0: float = 0.01) -> Tuple[np.ndarray, np.ndarray]:
+    """Extract ux, uy fields from DDF on host. Returns (ux, uy) each (NY, NX)."""
+    flow_field.get_ddf()
+    NX = flow_field.FIELD_SHAPE[0]
+    NY = flow_field.FIELD_SHAPE[1]
+    ddf = flow_field.ddf.copy().reshape((9, NY, NX)).transpose(2, 1, 0)
+    ux = (ddf[:, :, 1] + ddf[:, :, 5] + ddf[:, :, 8]
+          - ddf[:, :, 3] - ddf[:, :, 6] - ddf[:, :, 7]) / u0
+    uy = (ddf[:, :, 2] + ddf[:, :, 5] + ddf[:, :, 6]
+          - ddf[:, :, 4] - ddf[:, :, 7] - ddf[:, :, 8]) / u0
+    return ux.astype(np.float32), uy.astype(np.float32)
+
+
+def vorticity_from_fields(ux: np.ndarray, uy: np.ndarray) -> np.ndarray:
+    """Compute z-vorticity omega = dv/dx - du/dy."""
+    return (np.gradient(uy, axis=1) - np.gradient(ux, axis=0)).astype(np.float64)
+
+
+# ---------------------------------------------------------------------------
+# Period detection helpers
+# ---------------------------------------------------------------------------
+
+def detect_dominant_frequency(
+    signal: np.ndarray, sample_dt: float
+) -> Tuple[float, float, float]:
+    """Detect dominant frequency via FFT.
+
+    Parameters
+    ----------
+    signal : 1D array
+        Time series to analyse.
+    sample_dt : float
+        Time between samples (in same units as desired frequency).
+
+    Returns
+    -------
+    f_dom : float
+        Dominant frequency.
+    period : float
+        Corresponding period (1/f_dom).
+    peak_power : float
+        Power at dominant frequency.
+    """
+    n = len(signal)
+    if n < 16:
+        return 0.0, 0.0, 0.0
+    y = signal - np.mean(signal)
+    window = np.hanning(n)
+    spec = np.abs(np.fft.rfft(y * window)) ** 2
+    freqs = np.fft.rfftfreq(n, d=sample_dt)
+    # Skip DC
+    idx = 1 + np.argmax(spec[1:])
+    f_dom = float(freqs[idx])
+    period = 1.0 / f_dom if f_dom > 0 else 0.0
+    return f_dom, period, float(spec[idx])
+
+
+def detect_cycle_stability(
+    signal: np.ndarray, sample_dt: float
+) -> Tuple[float, float, List[float]]:
+    """Detect cycle lengths and compute stability metrics.
+
+    Parameters
+    ----------
+    signal : 1D array
+    sample_dt : float
+
+    Returns
+    -------
+    cv_T : float
+        Coefficient of variation of detected cycle lengths.
+    mean_T : float
+        Mean cycle length in time units.
+    cycle_lengths : list of float
+        Detected cycle lengths.
+    """
+    y = signal - np.mean(signal)
+    # Find rising zero-crossings
+    sign = np.sign(y)
+    crossings = np.where((sign[:-1] < 0) & (sign[1:] > 0))[0]
+    if len(crossings) < 2:
+        return 0.0, 0.0, []
+
+    cycle_lengths = np.diff(crossings).astype(float) * sample_dt
+    if len(cycle_lengths) < 2:
+        return 0.0, float(cycle_lengths[0]) if len(cycle_lengths) > 0 else 0.0, cycle_lengths.tolist()
+
+    mean_T = float(np.mean(cycle_lengths))
+    std_T = float(np.std(cycle_lengths))
+    cv_T = std_T / mean_T if mean_T > 0 else 0.0
+    return cv_T, mean_T, cycle_lengths.tolist()
+
+
+# ---------------------------------------------------------------------------
+# Phase resampling
+# ---------------------------------------------------------------------------
+
+def phase_resample(
+    data: np.ndarray,
+    cycle_starts: List[int],
+    n_pts: int = 24,
+    kind: str = "linear",
+) -> np.ndarray:
+    """Resample a multi-channel signal to uniform phase points per cycle.
+
+    Parameters
+    ----------
+    data : (T, C) ndarray
+        Multi-channel time series.
+    cycle_starts : list of int
+        Indices where each cycle starts (rising zero-crossings).
+    n_pts : int
+        Number of phase points per cycle.
+    kind : str
+        Interpolation kind ('linear' or 'cubic').
+
+    Returns
+    -------
+    resampled : (n_cycles, n_pts, C) ndarray
+    """
+    from scipy import interpolate
+
+    n_cycles = len(cycle_starts) - 1
+    if n_cycles < 1:
+        raise ValueError("Need at least 2 cycle starts")
+
+    C = data.shape[1] if data.ndim > 1 else 1
+    out = np.zeros((n_cycles, n_pts, C), dtype=np.float64)
+
+    for c in range(n_cycles):
+        i_start = cycle_starts[c]
+        i_end = cycle_starts[c + 1]
+        segment = data[i_start:i_end + 1]
+        seg_len = len(segment)
+        if seg_len < 2:
+            continue
+
+        old_phase = np.linspace(0, 2 * np.pi, seg_len)
+        new_phase = np.linspace(0, 2 * np.pi, n_pts, endpoint=False)
+
+        for ch in range(C):
+            interp = interpolate.interp1d(
+                old_phase, segment[:, ch] if segment.ndim > 1 else segment,
+                kind=kind, bounds_error=False, fill_value="extrapolate",
+            )
+            out[c, :, ch] = interp(new_phase)
+
+    return out
+
+
+# ---------------------------------------------------------------------------
+# POD
+# ---------------------------------------------------------------------------
+
+def compute_pod(snapshot_matrix: np.ndarray) -> Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
+    """Compute POD from snapshot matrix.
+
+    Parameters
+    ----------
+    snapshot_matrix : (n_points, n_snapshots) ndarray
+        Each column is one flattened snapshot.
+
+    Returns
+    -------
+    mean_field : (n_points,) ndarray
+    modes : (n_points, min(n_points, n_snapshots)) ndarray
+        Spatial modes (columns of U from SVD).
+    singular_values : (min_dim,) ndarray
+    coefficients : (min_dim, n_snapshots) ndarray
+        Temporal coefficients (Sigma V^T).
+    """
+    mean_field = np.mean(snapshot_matrix, axis=1)
+    Q = snapshot_matrix - mean_field[:, None]  # remove mean
+    U, s, Vt = np.linalg.svd(Q, full_matrices=False)
+    coeffs = (U.T @ Q)  # alternative: np.diag(s) @ Vt
+    return mean_field, U, s, coeffs
+
+
+def cumulative_energy(singular_values: np.ndarray) -> np.ndarray:
+    """Return cumulative energy fraction."""
+    e = singular_values ** 2
+    return np.cumsum(e) / np.sum(e)
+
+
+def e95_index(cumulative_energy: np.ndarray) -> int:
+    """Return first index where cumulative energy >= 95%."""
+    return int(np.searchsorted(cumulative_energy, 0.95) + 1)
+
+
+# ---------------------------------------------------------------------------
+# CCD (reduced version, Lyu23-inspired)
+# ---------------------------------------------------------------------------
+
+def compute_reduced_ccd(
+    pod_coeffs: np.ndarray,
+    observable: np.ndarray,
+    Q_delay: int = 12,
+) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Compute reduced CCD in POD coefficient space.
+
+    Parameters
+    ----------
+    pod_coeffs : (r, N) ndarray
+        Standardized POD coefficients (r modes, N time steps).
+    observable : (m, N) ndarray
+        Standardized observable (m channels, N time steps).
+    Q_delay : int
+        Number of delay steps.
+
+    Returns
+    -------
+    W : (r, min(r, m*Q_delay)) ndarray
+        CCD directions in POD coefficient space.
+    sigma : (min_dim,) ndarray
+        Singular values (correlation strengths).
+    z : (min_dim, N) ndarray
+        CCD temporal coefficients.
+    """
+    N = pod_coeffs.shape[1]
+    m = observable.shape[0]
+
+    # Build delay matrix P
+    # For each time t_i, p_i = [y(t_i+τ_1), ..., y(t_i+τ_Q)]
+    # where τ_j spans -Q_delay/2 to +Q_delay/2
+    half = Q_delay // 2
+    P_rows = []
+    for shift in range(-half, half + 1):
+        shifted = np.roll(observable, -shift, axis=1)
+        if shift < 0:
+            shifted[:, shift:] = 0  # zero pad edges
+        elif shift > 0:
+            shifted[:, :-shift] = 0
+        P_rows.append(shifted)
+    P = np.vstack(P_rows)  # (m*Q_delay, N)
+
+    # CCD matrix: C = P * A^T / (N * sqrt(Q))
+    C = P @ pod_coeffs.T / (N * np.sqrt(Q_delay))
+
+    # SVD
+    R, s, Wt = np.linalg.svd(C, full_matrices=False)
+    W = Wt.T  # (r, min_dim)
+
+    # CCD coefficients
+    z = W.T @ pod_coeffs  # (min_dim, N)
+
+    return W, s, z
+
+
+# ---------------------------------------------------------------------------
+# Field stacking
+# ---------------------------------------------------------------------------
+
+def stack_velocity_fields(
+    ux_fields: List[np.ndarray],
+    uy_fields: List[np.ndarray],
+) -> np.ndarray:
+    """Stack list of (ux, uy) field pairs into snapshot matrix.
+
+    Each field is flattened, then ux and uy are interleaved.
+    Returns (2*nx*ny, N) matrix.
+    """
+    snapshots = []
+    for ux, uy in zip(ux_fields, uy_fields):
+        q = np.concatenate([ux.ravel(), uy.ravel()])
+        snapshots.append(q)
+    return np.column_stack(snapshots)

src/CCD_analysis/scripts/validate_control.py

@@ -0,0 +1,561 @@
+# CCD_analysis/scripts/validate_control.py
+"""
+WARNING: This validation script has NOT produced correct results.
+Despite multiple iterations, the PPO inference does not reproduce thesis-level
+reward/similarity values (cloak sim ~0.19 vs expected 0.90, illusion sim ~0.82 vs 0.98).
+
+Known issues that need to be investigated:
+1. The norm values seem reasonable but may not match training-time distributions
+2. Obs layout (what obs[i] means) depends on object add order, which differs between
+   legacy_env_karman_cloak_standard.py and uni_test.ipynb -- need to determine which
+   was actually used during training
+3. The FIFO initialization may not exactly match training-time behavior
+4. Action smoothing (legacy FlowField.run() uses exponential smoothing weight=0.1)
+   may affect dynamics in ways not accounted for
+
+DO NOT USE these results for analysis. Fix the PPO replay first.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+from collections import deque
+
+import numpy as np
+
+_REPO = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+if _REPO not in sys.path:
+    sys.path.insert(0, _REPO)
+_ANALYSIS = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+if _ANALYSIS not in sys.path:
+    sys.path.insert(0, _ANALYSIS)
+
+from LegacyCelerisLab import FlowField
+from scripts.cfg import CONFIG_DIR, OUTPUT_DIR, L0, NX, NY, CENTER_Y
+from scripts.utils import load_configs, get_velocity_field
+
+# -- Constants --
+FIFO_LEN = 150
+DATA_TYPE = np.float32
+U0 = 0.01
+U0_ILLUSION = 0.02
+SAMPLE_INTERVAL = 800
+SAMPLE_INTERVAL_ILL = 600
+
+MODEL_CLOAK = os.path.join(_REPO, "models", "old", "d1a3o12_re100.zip")
+MODEL_ILLUSION = os.path.join(_REPO, "models", "250525", "d1a3o14_250525_imit_1L_2U_600S.zip")
+
+# Geometry
+PR = L0 / 2.0   # pinball radius = 10
+SR = L0 / 4.0   # sensor radius = 5
+
+# Cloak layout (lattice units)
+DIST_POS = (10.0 * L0, CENTER_Y, 0.0)
+SENSOR_X = 40.0 * L0
+SENSOR_YS = [CENTER_Y + 2.0 * L0, CENTER_Y, CENTER_Y - 2.0 * L0]
+FRONT_POS = (30.0 * L0, CENTER_Y, 0.0)
+BOTTOM_POS = (31.3 * L0, CENTER_Y - 0.75 * L0, 0.0)
+TOP_POS = (31.3 * L0, CENTER_Y + 0.75 * L0, 0.0)
+
+# Illusion layout
+ILL_SENSOR_X = 30.0 * L0
+ILL_SENSOR_YS = [CENTER_Y + 2.0 * L0, CENTER_Y, CENTER_Y - 2.0 * L0]
+ILL_FRONT = (19.0 * L0, CENTER_Y, 0.0)
+ILL_BOTTOM = (20.3 * L0, CENTER_Y + 0.75 * L0, 0.0)
+ILL_TOP = (20.3 * L0, CENTER_Y - 0.75 * L0, 0.0)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _calc_lag(t, s):
+    tm = float(np.mean(t))
+    sm = float(np.mean(s))
+    corr = np.correlate(t - tm, s - sm, mode="full")
+    lags = np.arange(-len(t) + 1, len(t))
+    return int(lags[np.argmax(corr)])
+
+
+def _calc_dtw_sim(t, s):
+    n, m = len(t), len(s)
+    dtw = np.full((n + 1, m + 1), np.inf)
+    dtw[0, 0] = 0.0
+    for i in range(1, n + 1):
+        for j in range(1, m + 1):
+            cost = abs(float(t[i - 1]) - float(s[j - 1]))
+            dtw[i, j] = cost + min(dtw[i - 1, j], dtw[i, j - 1], dtw[i - 1, j - 1])
+    return float(1.0 - dtw[n, m] / n)
+
+
+def _save_vorticity_png(ff, path, title="", u0=U0):
+    import matplotlib
+    matplotlib.use("Agg")
+    import matplotlib.pyplot as plt
+    ux, uy = get_velocity_field(ff, u0=u0)
+    omega = np.gradient(uy, axis=1) - np.gradient(ux, axis=0)  # dv/dx - du/dy
+    abs_o = np.abs(omega[np.isfinite(omega)])
+    vmax = float(np.percentile(abs_o, 99.5)) if abs_o.size > 0 else 1.0
+    if vmax <= 0:
+        vmax = 1.0
+    ny, nx = omega.shape
+    fig, ax = plt.subplots(figsize=(min(18, max(8, nx / 60)), min(10, max(3, ny / 40))))
+    im = ax.imshow(omega, origin="lower", aspect="equal", cmap="RdBu_r",
+                   vmin=-vmax, vmax=vmax, extent=(0, nx - 1, 0, ny - 1))
+    ax.set_xlabel("x (lattice)")
+    ax.set_ylabel("y (lattice)")
+    if title:
+        ax.set_title(title)
+    fig.colorbar(im, ax=ax, fraction=0.046, pad=0.04, label=r"$\omega_z$")
+    fig.tight_layout()
+    fig.savefig(path, dpi=150, bbox_inches="tight")
+    plt.close(fig)
+
+
+def _load_ppo(model_path, device, s_dim=12, a_dim=3):
+    import torch
+    from torch.nn import Module
+    from stable_baselines3 import PPO
+    import gymnasium as gym
+    from gymnasium import spaces
+    class Sin(Module):
+        def forward(self, x):
+            return torch.sin(x)
+    class DummyEnv(gym.Env):
+        def __init__(self):
+            super().__init__()
+            self.observation_space = spaces.Box(low=-1, high=1, shape=(s_dim,), dtype=np.float32)
+            self.action_space = spaces.Box(low=-1, high=1, shape=(a_dim,), dtype=np.float32)
+        def reset(self, seed=None):
+            return np.zeros(s_dim, dtype=np.float32), {}
+        def step(self, action):
+            return np.zeros(s_dim, dtype=np.float32), 0.0, False, False, {}
+        def render(self):
+            pass
+    return PPO.load(model_path, env=DummyEnv(), device=device)
+
+
+def _analyze_harmonics(states, n=5):
+    N, D = states.shape
+    r = []
+    for d in range(D):
+        y = states[:, d]
+        fc = np.fft.rfft(y)
+        fr = np.fft.rfftfreq(N, d=1)
+        amps = 2.0 * np.abs(fc) / N
+        ph = np.angle(fc)
+        idx = np.argsort(amps[1:])[::-1][:n] + 1
+        r.append({'dc': float(np.real(fc[0]) / N), 'amps': amps[idx].tolist(),
+                   'freqs': fr[idx].tolist(), 'phases': ph[idx].tolist()})
+    return r
+
+
+def _gen_target(t, harm):
+    t = np.asarray(t)
+    D = len(harm)
+    r = np.zeros((t.size, D), dtype=np.float32)
+    for d, h in enumerate(harm):
+        v = np.full(t.shape, h['dc'], dtype=np.float32)
+        for a, f, p in zip(h['amps'], h['freqs'], h['phases']):
+            v += a * np.cos(2 * np.pi * f * t + p)
+        r[:, d] = v
+    if r.shape[0] == 1:
+        return r[0]
+    return r
+
+
+# ---------------------------------------------------------------------------
+# Cloak validation (EXACTLY matching analysis_crossre + legacy_env)
+# ---------------------------------------------------------------------------
+
+def validate_cloak(device_id, out_dir):
+    print("=" * 60)
+    print("Validating Cloak (Karman)")
+    print("=" * 60)
+    os.makedirs(out_dir, exist_ok=True)
+
+    cuda_cfg, field_cfg = load_configs(CONFIG_DIR)
+    field_cfg = field_cfg._replace(viscosity=0.004, velocity=U0)
+    ff = FlowField(field_cfg, cuda_cfg, device_id=device_id)
+
+    # -- Phase 1: target recording (dist_cyl + 3 sensors) --
+    print("\n--- Target recording ---")
+    ff.add_cylinder(DIST_POS, L0)           # dist(0)
+    for y in SENSOR_YS:
+        ff.add_sensor((SENSOR_X, y, 0.0), SR)  # sensors(1,2,3)
+    n_obj = ff.obs.size // 2  # 4
+    ff.run(int(4 * NX / U0), np.zeros(n_obj, dtype=DATA_TYPE))
+
+    target_states = np.empty((0, 6), dtype=DATA_TYPE)
+    for _ in range(FIFO_LEN):
+        ff.run(SAMPLE_INTERVAL, np.zeros(n_obj, dtype=DATA_TYPE))
+        # obs layout: dist(0) + 3 sensors(1,2,3) → 4×2=8 values
+        # obs[2:8] = s0_ux,uy, s1_ux,uy, s2_ux,uy = 6 sensors
+        target_states = np.vstack((target_states, ff.obs.copy()[2:8]))
+    print(f"  target: {target_states.shape}")
+
+    # -- Phase 2: add pinball (ids 4,5,6) --
+    print("\n--- Add pinball ---")
+    ff.add_cylinder(FRONT_POS, PR)   # front(4)
+    ff.add_cylinder(BOTTOM_POS, PR)  # bottom(5)
+    ff.add_cylinder(TOP_POS, PR)     # top(6)
+    n_obj = ff.obs.size // 2  # 7
+    ff.run(int(4 * NX / U0), np.zeros(n_obj, dtype=DATA_TYPE))
+    ff.get_ddf()
+    ff.save_ddf()  # checkpoint
+
+    # -- Phase 3: Norm computation --
+    print("\n--- Norm (obs[2:14]) ---")
+    fifo = deque(maxlen=FIFO_LEN)
+    for _ in range(FIFO_LEN):
+        ff.run(SAMPLE_INTERVAL, np.zeros(n_obj, dtype=DATA_TYPE))
+        fifo.append(ff.obs.copy()[2:14])  # [sensors(6), forces(6)]
+    temp = np.array(fifo, dtype=DATA_TYPE)
+    force_norm_fact = 6.0 * float(np.max(np.abs(temp[:, 6:12])))
+    sens_deviation = np.mean(temp[:, 0:6], axis=0).astype(DATA_TYPE)
+    sens_norm_fact = np.zeros(6, dtype=DATA_TYPE)
+    for i in range(6):
+        sens_norm_fact[i] = 5.0 * float(np.max(np.abs(temp[:, i] - sens_deviation[i])))
+    print(f"  force_norm_fact={force_norm_fact:.6f}")
+
+    # -- Phase 4: Bias-action FIFO (uni_test: [0,0,0,0,0,-4*U0,4*U0]) --
+    print("\n--- Bias FIFO ---")
+    ff.apply_ddf()
+    bias = np.zeros(n_obj, dtype=DATA_TYPE)
+    bias[5] = -4.0 * U0  # bottom
+    bias[6] = 4.0 * U0   # top
+    fifo.clear()
+    for _ in range(FIFO_LEN):
+        ff.run(SAMPLE_INTERVAL, bias)
+        fifo.append(ff.obs.copy()[2:14])
+    save_states = list(fifo)
+    ff.apply_ddf()
+
+    # -- Phase 5: PPO inference --
+    print("\n--- PPO inference (500 steps) ---")
+    import torch
+    dev = f"cuda:{device_id}" if torch.cuda.is_available() else "cpu"
+    model = _load_ppo(MODEL_CLOAK, device=dev, s_dim=12, a_dim=3)
+    model.set_random_seed(0)
+
+    n_steps = 500
+    fifo = deque(maxlen=FIFO_LEN)
+    for s in save_states:
+        fifo.append(np.array(s, dtype=DATA_TYPE))
+
+    obs = np.zeros(12, dtype=DATA_TYPE)
+    rewards, sims, cds, cls = [], [], [], []
+
+    for step in range(n_steps):
+        action, _ = model.predict(obs, deterministic=True)
+        action = action.astype(DATA_TYPE).flatten()
+
+        # Action: legacy pattern, pinball at indices 4,5,6
+        temp_a = np.zeros(n_obj, dtype=DATA_TYPE)
+        temp_a[4:7] = (action * 8.0 + np.array([0.0, -4.0, 4.0], dtype=DATA_TYPE)) * U0
+
+        ff.context.push()
+        try:
+            ff.run(SAMPLE_INTERVAL, temp_a)
+        finally:
+            ff.context.pop()
+
+        obs_slice = ff.obs.copy()[2:14]  # [sensors(6), forces(6)]
+        fifo.append(obs_slice)
+
+        # Observation: [forces_norm(6), sens_norm(6)]  ← matches analysis_crossre order
+        forces_norm = obs_slice[6:12] / force_norm_fact
+        sens_norm = (obs_slice[0:6] - sens_deviation) / sens_norm_fact
+        obs = np.clip(np.hstack([forces_norm, sens_norm]), -1.0, 1.0).astype(DATA_TYPE)
+
+        # Reward (legacy env style: cd/cl from forces in obs_slice[6:12])
+        sarr = np.array(fifo, dtype=DATA_TYPE)
+        if len(sarr) >= 30:
+            f = sarr[-1, 6:12] / force_norm_fact
+            cd = float((f[0] + f[2] + f[4]) / 3.0)
+            cl = float((f[1] + f[3] + f[5]) / 3.0)
+
+            # DTW: lag from middle sensor (index 1 in sensor block = obs[4] in obs[2:14] = sensor1_uy)
+            ref = target_states[30:60, 1]
+            cur = sarr[-30:, 1]
+            lag = _calc_lag(ref, cur)
+
+            sim = 0.0
+            for i in range(6):
+                t_seq = np.roll(target_states[:, i], -lag)[30:60]
+                s_seq = sarr[-30:, i]
+                sim += _calc_dtw_sim(t_seq, s_seq) / 6.0
+
+            r_cd = float(np.exp(-abs(cd * 20.0)))
+            r_cl = float(np.exp(-abs(cl * 80.0)))
+            r_sim = float(np.exp(-10.0 * abs(sim - 1.0)))
+            reward = float(min(0.3 * r_cd + 0.4 * r_cl + 0.3 * r_sim, 1.0))
+        else:
+            cd, cl, sim, reward = 0.0, 0.0, 0.0, 0.0
+
+        rewards.append(reward)
+        sims.append(sim)
+        cds.append(cd)
+        cls.append(cl)
+
+    _save_vorticity_png(ff, os.path.join(out_dir, "cloak_vorticity_final.png"),
+                        title="Cloak (Karman) Re=100", u0=U0)
+
+    tail = 100
+    result = {
+        "case": "cloak_karman", "n_steps": n_steps,
+        "mean_reward_last100": float(np.mean(rewards[-tail:])),
+        "std_reward_last100": float(np.std(rewards[-tail:])),
+        "mean_similarity_last100": float(np.mean(sims[-tail:])),
+        "mean_cd_last100": float(np.mean(cds[-tail:])),
+        "mean_cl_last100": float(np.mean(cls[-tail:])),
+        "force_norm_fact": force_norm_fact,
+        "vorticity_png": "cloak_vorticity_final.png",
+    }
+    print(f"\n  mean_reward={result['mean_reward_last100']:.4f}  "
+          f"sim={result['mean_similarity_last100']:.4f}  cd={result['mean_cd_last100']:.4f}")
+    del ff, model
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Illusion validation
+# ---------------------------------------------------------------------------
+
+def validate_illusion(device_id, out_dir):
+    print("=" * 60)
+    print("Validating Illusion (1L)")
+    print("=" * 60)
+    os.makedirs(out_dir, exist_ok=True)
+
+    cuda_cfg, field_cfg = load_configs(CONFIG_DIR)
+    field_cfg = field_cfg._replace(viscosity=0.008, velocity=U0_ILLUSION)
+
+    # -- Target recording --
+    print("\n--- Target recording ---")
+    ff_tgt = FlowField(field_cfg, cuda_cfg, device_id=device_id)
+    ff_tgt.add_cylinder((20.0 * L0, CENTER_Y, 0.0), L0)  # target cylinder
+    for y in ILL_SENSOR_YS:
+        ff_tgt.add_sensor((ILL_SENSOR_X, y, 0.0), SR)
+    n_tgt = ff_tgt.obs.size // 2  # 4
+    ff_tgt.run(int(4 * NX / U0_ILLUSION), np.zeros(n_tgt, dtype=DATA_TYPE))
+
+    target_states = np.empty((0, 8), dtype=DATA_TYPE)
+    for _ in range(FIFO_LEN):
+        ff_tgt.run(SAMPLE_INTERVAL_ILL, np.zeros(n_tgt, dtype=DATA_TYPE))
+        target_states = np.vstack((target_states, ff_tgt.obs.copy()[0:8]))
+    harmonics = _analyze_harmonics(target_states, 5)
+    print(f"  target: {target_states.shape}, harmonics: {len(harmonics)} ch")
+    del ff_tgt
+
+    # -- Pinball env (6 objects: 3 sensors + 3 pinball) --
+    # Add sensors first, then pinball (matches legacy_env_imit.py)
+    print("\n--- Build pinball env ---")
+    ff = FlowField(field_cfg, cuda_cfg, device_id=device_id)
+    for y in ILL_SENSOR_YS:
+        ff.add_sensor((ILL_SENSOR_X, y, 0.0), SR)  # sensors(0,1,2)
+    ff.add_cylinder(ILL_FRONT, PR)   # front(3)
+    ff.add_cylinder(ILL_BOTTOM, PR)  # bottom(4)
+    ff.add_cylinder(ILL_TOP, PR)     # top(5)
+    n_obj = ff.obs.size // 2  # 6
+    ff.run(int(4 * NX / U0_ILLUSION), np.zeros(n_obj, dtype=DATA_TYPE))
+    ff.get_ddf()
+    ff.save_ddf()
+
+    # -- Norm (obs[0:12] = [sensors(6), forces(6)]) --
+    print("\n--- Norm ---")
+    fifo = deque(maxlen=FIFO_LEN)
+    for _ in range(FIFO_LEN):
+        ff.run(SAMPLE_INTERVAL_ILL, np.zeros(n_obj, dtype=DATA_TYPE))
+        fifo.append(ff.obs.copy()[0:12])
+    temp = np.array(fifo, dtype=DATA_TYPE)
+    force_norm_fact = 6.0 * float(np.max(np.abs(temp[:, 6:12])))
+    sens_deviation = np.mean(temp[:, 0:6], axis=0).astype(DATA_TYPE)
+    sens_norm_fact = np.zeros(6, dtype=DATA_TYPE)
+    for i in range(6):
+        sens_norm_fact[i] = 5.0 * float(np.max(np.abs(temp[:, i] - sens_deviation[i])))
+    print(f"  force_norm_fact={force_norm_fact:.6f}")
+
+    # -- Bias FIFO --
+    print("\n--- Bias FIFO ---")
+    ff.apply_ddf()
+    bias = np.zeros(n_obj, dtype=DATA_TYPE)
+    bias[4] = -1.0 * U0_ILLUSION
+    bias[5] = 1.0 * U0_ILLUSION
+    fifo.clear()
+    for _ in range(FIFO_LEN):
+        ff.run(SAMPLE_INTERVAL_ILL, bias)
+        fifo.append(ff.obs.copy()[0:12])
+    save_states = list(fifo)
+    ff.apply_ddf()
+
+    # -- PPO inference --
+    print("\n--- PPO inference (500 steps) ---")
+    import torch
+    dev = f"cuda:{device_id}" if torch.cuda.is_available() else "cpu"
+    model = _load_ppo(MODEL_ILLUSION, device=dev, s_dim=14, a_dim=3)
+    model.set_random_seed(19)
+
+    n_steps = 500
+    fifo = deque(maxlen=FIFO_LEN)
+    for s in save_states:
+        fifo.append(np.array(s, dtype=DATA_TYPE))
+
+    obs = np.zeros(14, dtype=DATA_TYPE)
+    rewards, sims, cds, cls = [], [], [], []
+
+    for step in range(n_steps):
+        action, _ = model.predict(obs, deterministic=True)
+        action = action.astype(DATA_TYPE).flatten()
+
+        temp_a = np.zeros(n_obj, dtype=DATA_TYPE)
+        temp_a[3:6] = (action * 8.0 + np.array([0.0, -2.0, 2.0], dtype=DATA_TYPE)) * U0_ILLUSION
+
+        ff.context.push()
+        try:
+            ff.run(SAMPLE_INTERVAL_ILL, temp_a)
+        finally:
+            ff.context.pop()
+
+        obs_slice = ff.obs.copy()[0:12]
+        fifo.append(obs_slice)
+
+        # 14-dim obs: [forces_norm(6), sens_norm(6), target_cd, target_cl]
+        forces_norm = obs_slice[6:12] / force_norm_fact
+        sens_norm = (obs_slice[0:6] - sens_deviation) / sens_norm_fact
+        target_recon = _gen_target(step, harmonics)
+        t_cd_n = float(target_recon[0]) / force_norm_fact
+        t_cl_n = float(target_recon[1]) / force_norm_fact
+        obs = np.clip(np.hstack([forces_norm, sens_norm, t_cd_n, t_cl_n]),
+                      -1.0, 1.0).astype(DATA_TYPE)
+
+        # Reward
+        sarr = np.array(fifo, dtype=DATA_TYPE)
+        if len(sarr) >= 36:
+            f = sarr[-1, 6:12] / force_norm_fact
+            cd = float(f[0] + f[2] + f[4])  # SUM
+            cl = float(f[1] + f[3] + f[5])
+
+            ref = target_states[36:72, 3]
+            cur = sarr[-36:, 3]
+            lag = _calc_lag(ref, cur)
+
+            sim = 0.0
+            for i in range(6):
+                t_seq = np.roll(target_states[:, i + 2], -lag)[36:72]
+                s_seq = sarr[-36:, i]
+                sim += _calc_dtw_sim(t_seq, s_seq) / 6.0
+
+            t_cd = float(target_recon[0]) / force_norm_fact
+            t_cl = float(target_recon[1]) / force_norm_fact
+            r_cd = float(np.exp(-abs((cd - t_cd) * 10.0)))
+            r_cl = float(np.exp(-abs((cl - t_cl) * 10.0)))
+            r_sim = float(np.exp(-10.0 * abs(sim - 1.0)))
+            reward = float(min(0.3 * r_cd + 0.3 * r_cl + 0.4 * r_sim, 1.0))
+        else:
+            cd, cl, sim, reward = 0.0, 0.0, 0.0, 0.0
+
+        rewards.append(reward)
+        sims.append(sim)
+        cds.append(cd)
+        cls.append(cl)
+
+    _save_vorticity_png(ff, os.path.join(out_dir, "illusion_vorticity_final.png"),
+                        title="Illusion (1L) Re=100", u0=U0_ILLUSION)
+
+    tail = 100
+    result = {
+        "case": "illusion_1L", "n_steps": n_steps,
+        "mean_reward_last100": float(np.mean(rewards[-tail:])),
+        "std_reward_last100": float(np.std(rewards[-tail:])),
+        "mean_similarity_last100": float(np.mean(sims[-tail:])),
+        "mean_cd_last100": float(np.mean(cds[-tail:])),
+        "mean_cl_last100": float(np.mean(cls[-tail:])),
+        "force_norm_fact": force_norm_fact,
+        "vorticity_png": "illusion_vorticity_final.png",
+    }
+    print(f"\n  mean_reward={result['mean_reward_last100']:.4f}  "
+          f"sim={result['mean_similarity_last100']:.4f}  cd={result['mean_cd_last100']:.4f}")
+    del ff, model
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Baseline
+# ---------------------------------------------------------------------------
+
+def validate_uncontrolled(device_id, out_dir):
+    cuda_cfg, field_cfg = load_configs(CONFIG_DIR)
+    field_cfg = field_cfg._replace(viscosity=0.004, velocity=U0)
+    ff = FlowField(field_cfg, cuda_cfg, device_id=device_id)
+    for y in SENSOR_YS:
+        ff.add_sensor((SENSOR_X, y, 0.0), SR)
+    ff.add_cylinder(FRONT_POS, PR)
+    ff.add_cylinder(BOTTOM_POS, PR)
+    ff.add_cylinder(TOP_POS, PR)
+    ff.run(int(4 * NX / U0), np.zeros(6, dtype=DATA_TYPE))
+    for _ in range(200):
+        ff.run(SAMPLE_INTERVAL, np.zeros(6, dtype=DATA_TYPE))
+    _save_vorticity_png(ff, os.path.join(out_dir, "uncontrolled_vorticity_final.png"),
+                        title="Uncontrolled Pinball Re=100", u0=U0)
+    del ff
+    return {"case": "uncontrolled", "vorticity_png": "uncontrolled_vorticity_final.png"}
+
+
+def validate_target(device_id, out_dir):
+    cuda_cfg, field_cfg = load_configs(CONFIG_DIR)
+    field_cfg = field_cfg._replace(viscosity=0.004, velocity=U0)
+    ff = FlowField(field_cfg, cuda_cfg, device_id=device_id)
+    ff.add_cylinder((20.0 * L0, CENTER_Y, 0.0), L0)
+    for y in SENSOR_YS:
+        ff.add_sensor((SENSOR_X, y, 0.0), SR)
+    ff.run(int(4 * NX / U0), np.zeros(4, dtype=DATA_TYPE))
+    for _ in range(200):
+        ff.run(SAMPLE_INTERVAL, np.zeros(4, dtype=DATA_TYPE))
+    _save_vorticity_png(ff, os.path.join(out_dir, "target_vorticity_final.png"),
+                        title="Target 2D Cylinder Re=100", u0=U0)
+    del ff
+    return {"case": "target_cylinder", "vorticity_png": "target_vorticity_final.png"}
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main():
+    ap = argparse.ArgumentParser(description="Validate control quality")
+    ap.add_argument("--device", type=int, default=2)
+    ap.add_argument("--case", type=str, required=True,
+                    choices=["all", "cloak", "illusion", "uncontrolled", "target"])
+    args = ap.parse_args()
+    out_dir = os.path.join(OUTPUT_DIR, "validation")
+    os.makedirs(out_dir, exist_ok=True)
+    t0 = time.time()
+    results = {}
+    if args.case in ("all", "cloak"):
+        results["cloak"] = validate_cloak(args.device, out_dir)
+    if args.case in ("all", "illusion"):
+        results["illusion"] = validate_illusion(args.device, out_dir)
+    if args.case in ("all", "uncontrolled"):
+        results["uncontrolled"] = validate_uncontrolled(args.device, out_dir)
+    if args.case in ("all", "target"):
+        results["target"] = validate_target(args.device, out_dir)
+    with open(os.path.join(out_dir, "validation_results.json"), "w") as f:
+        json.dump({"device": args.device, "elapsed_sec": time.time() - t0,
+                    "results": results}, f, indent=2)
+    print(f"\n{'='*60}\nSummary\n{'='*60}")
+    for c, r in results.items():
+        if "mean_reward_last100" in r:
+            print(f"  {c}: reward={r['mean_reward_last100']:.4f}  sim={r['mean_similarity_last100']:.4f}")
+        else:
+            print(f"  {c}: baseline")
+    print(f"\nVorticity: {out_dir}/ | Total: {time.time()-t0:.1f}s")
+    return 0
+
+
+if __name__ == "__main__":
+    main()

src/__init__.py

@@ -1,11 +1 @@
-"""
-DynamisLab: Machine Learning for Computational Fluid Dynamics
-"""
 
-__version__ = '0.1.0'
-__author__ = 'Frank14f'
-
-from . import config
-from . import environments
-
-__all__ = ['config', 'environments', '__version__']

src/analysis_cloak/common/feature_builder.py

@@ -0,0 +1,214 @@
+"""Unified feature builder for all cloak scenes.
+
+Produces dimensionless features with consistent G-equivariant structure.
+All scenes (Karman, steady, vortex, erase) use this same builder.
+"""
+from __future__ import annotations
+
+from typing import Dict, List, Optional, Tuple
+
+import numpy as np
+
+
+# -- Physical constants ------------------------------------------------------
+U0 = 0.01       # inlet velocity (lattice units)
+D_CYL = 20.0    # cylinder diameter (lattice)
+
+
+# -- Dimensionless conversion ------------------------------------------------
+
+def compute_dimensionless(
+    sensors: np.ndarray,  # (T, 6) raw lattice [s0_ux,s0_uy, s1_ux,s1_uy, s2_ux,s2_uy]
+    forces: np.ndarray,   # (T, 6) raw lattice [f0_fx,f0_fy, f1_fx,f1_fy, f2_fx,f2_fy]
+    u0: float = U0,
+    d: float = D_CYL,
+    rho: float = 1.0,
+) -> Dict[str, np.ndarray]:
+    """Convert raw lattice CFD data to dimensionless quantities.
+
+    Sensor order: [s0_ux,s0_uy, s1_ux,s1_uy, s2_ux,s2_uy]
+        where s0=top(y=+2L0), s1=mid(y=0), s2=bottom(y=-2L0)
+    Force order: [front_fx,front_fy, bottom_fx,bottom_fy, top_fx,top_fy]
+
+    Returns:
+        u_hat_B, u_hat_C, u_hat_T: nondim streamwise velocity (bottom/centre/top)
+        v_hat_B, v_hat_C, v_hat_T: nondim crosswise velocity
+        Cd_F, Cd_T, Cd_B: drag coefficient per cylinder
+        Cl_F, Cl_T, Cl_B: lift coefficient per cylinder
+    """
+    s = np.asarray(sensors, dtype=np.float64)
+    f = np.asarray(forces, dtype=np.float64)
+
+    # Sensor positions: s0=top, s1=centre, s2=bottom
+    # Convention: B=bottom=s2, C=centre=s1, T=top=s0
+    return {
+        "u_hat_T": s[:, 0] / u0,
+        "v_hat_T": s[:, 1] / u0,
+        "u_hat_C": s[:, 2] / u0,
+        "v_hat_C": s[:, 3] / u0,
+        "u_hat_B": s[:, 4] / u0,
+        "v_hat_B": s[:, 5] / u0,
+        "Cd_F": 2.0 * f[:, 0] / (rho * u0**2 * d),
+        "Cl_F": 2.0 * f[:, 1] / (rho * u0**2 * d),
+        "Cd_B": 2.0 * f[:, 2] / (rho * u0**2 * d),
+        "Cl_B": 2.0 * f[:, 3] / (rho * u0**2 * d),
+        "Cd_T": 2.0 * f[:, 4] / (rho * u0**2 * d),
+        "Cl_T": 2.0 * f[:, 5] / (rho * u0**2 * d),
+    }
+
+
+# -- G operator (corrected) --------------------------------------------------
+
+def apply_G_alpha(alpha: np.ndarray) -> np.ndarray:
+    """Apply mirror G to action: [aF, aT, aB] -> [-aF, -aB, -aT]."""
+    return np.array([-alpha[0], -alpha[2], -alpha[1]], dtype=alpha.dtype)
+
+
+def apply_G_x(dim: Dict[str, np.ndarray],
+              a_prev: np.ndarray,
+              a_prev2: np.ndarray) -> Tuple[Dict, np.ndarray, np.ndarray]:
+    """Apply G to dimensionless state.
+
+    Returns (G_dim, G_a_prev, G_a_prev2) with corrected sign rules.
+    """
+    G_dim = {
+        "u_hat_B": dim["u_hat_T"], "u_hat_C": dim["u_hat_C"], "u_hat_T": dim["u_hat_B"],
+        "v_hat_B": -dim["v_hat_T"], "v_hat_C": -dim["v_hat_C"], "v_hat_T": -dim["v_hat_B"],
+        "Cd_F": dim["Cd_F"], "Cd_T": dim["Cd_B"], "Cd_B": dim["Cd_T"],
+        "Cl_F": -dim["Cl_F"], "Cl_T": -dim["Cl_B"], "Cl_B": -dim["Cl_T"],
+    }
+    G_a_prev = np.column_stack([-a_prev[:, 0], -a_prev[:, 2], -a_prev[:, 1]])
+    G_a_prev2 = np.column_stack([-a_prev2[:, 0], -a_prev2[:, 2], -a_prev2[:, 1]])
+    return G_dim, G_a_prev, G_a_prev2
+
+
+# -- Feature key definitions -------------------------------------------------
+
+CORE_FEAT_KEYS = [
+    "u_m", "u_a", "u_c",
+    "v_a",
+    "Cd_tot", "Cd_rear",
+    "Cl_tot", "Cl_diff",
+    "sin_ua", "cos_ua",
+    "aF_lag1", "aB_lag1", "aT_lag1",
+    "daF", "daB", "daT",
+]
+
+MU_FEAT_KEYS = ["mu", "mu_u_a", "mu_v_a", "mu_Cd_tot", "mu_Cl_diff"]
+
+ALL_FEAT_KEYS = CORE_FEAT_KEYS + MU_FEAT_KEYS
+
+
+# -- Feature computation -----------------------------------------------------
+
+def compute_features(
+    dim: Dict[str, np.ndarray],
+    actions_prev: np.ndarray,   # (T, 3) physical omega(t-1) or nondim alpha(t-1)
+    actions_prev2: np.ndarray,  # (T, 3) physical omega(t-2)
+    mu: float,
+    alpha_mode: bool = False,  # if True, actions_prev are already nondim alpha
+    include_mu: bool = True,
+) -> Dict[str, np.ndarray]:
+    """Compute unified feature dictionary from dimensionless primitives.
+
+    Args:
+        dim: from compute_dimensionless()
+        actions_prev: lagged actions (physical omega or nondim alpha)
+        actions_prev2: twice-lagged actions
+        mu: 1/Re_D
+        alpha_mode: if True, actions are already nondim; else convert
+        include_mu: include mu modulation terms
+
+    Returns dict with all features as (T,) or (T,3) arrays.
+    """
+    T = actions_prev.shape[0]
+    u_B, u_C, u_T = dim["u_hat_B"], dim["u_hat_C"], dim["u_hat_T"]
+    v_B, v_C, v_T = dim["v_hat_B"], dim["v_hat_C"], dim["v_hat_T"]
+    Cd_F, Cd_T, Cd_B = dim["Cd_F"], dim["Cd_T"], dim["Cd_B"]
+    Cl_F, Cl_T, Cl_B = dim["Cl_F"], dim["Cl_T"], dim["Cl_B"]
+
+    # If actions are in physical omega, convert to nondim alpha
+    if alpha_mode:
+        a = actions_prev.astype(np.float64)
+        a2 = actions_prev2.astype(np.float64)
+    else:
+        a = actions_prev.astype(np.float64) / U0
+        a2 = actions_prev2.astype(np.float64) / U0
+
+    sym = {}
+
+    # Sensor combinations (nondim)
+    sym["u_m"] = (u_B + u_C + u_T) / 3.0
+    sym["u_a"] = (u_T - u_B) / 2.0
+    sym["u_c"] = u_C.copy()
+    sym["v_a"] = (v_T - v_B) / 2.0
+
+    # Force combinations (dimensionless Cd/Cl)
+    sym["Cd_tot"] = Cd_F + Cd_T + Cd_B
+    sym["Cd_rear"] = Cd_T + Cd_B
+    sym["Cl_tot"] = Cl_F + Cl_T + Cl_B
+    sym["Cl_diff"] = Cl_T - Cl_B
+
+    # Phase
+    sym["sin_ua"] = np.sin(np.pi * sym["u_a"])
+    sym["cos_ua"] = np.cos(np.pi * sym["u_a"])
+
+    # Memory (nondim alpha)
+    sym["aF_lag1"] = a[:, 0]
+    sym["aB_lag1"] = a[:, 1]
+    sym["aT_lag1"] = a[:, 2]
+    sym["daF"] = a[:, 0] - a2[:, 0]
+    sym["daB"] = a[:, 1] - a2[:, 1]
+    sym["daT"] = a[:, 2] - a2[:, 2]
+
+    # Mu modulation
+    if include_mu:
+        sym["mu"] = np.full(T, mu, dtype=np.float64)
+        sym["mu_u_a"] = sym["u_a"] * mu
+        sym["mu_v_a"] = sym["v_a"] * mu
+        sym["mu_Cd_tot"] = sym["Cd_tot"] * mu
+        sym["mu_Cl_diff"] = sym["Cl_diff"] * mu
+
+    return sym
+
+
+def build_feature_matrix(
+    sym: Dict[str, np.ndarray],
+    feat_keys: List[str],
+    add_bias: bool = True,
+) -> np.ndarray:
+    """Build feature matrix (T, N) from symbol dict."""
+    cols = []
+    if add_bias:
+        cols.append(np.ones(sym[feat_keys[0]].shape[0], dtype=np.float64))
+    for k in feat_keys:
+        if k in sym:
+            cols.append(np.asarray(sym[k], dtype=np.float64))
+        else:
+            # Missing key (e.g. mu terms when include_mu=False) -> zero
+            T = sym.get("u_m", np.ones(1)).shape[0]
+            cols.append(np.zeros(T, dtype=np.float64))
+    return np.column_stack(cols)
+
+
+def get_feature_names(feat_keys: List[str], add_bias: bool = True) -> List[str]:
+    """Get feature names matching build_feature_matrix output."""
+    names = []
+    if add_bias:
+        names.append("bias")
+    names.extend(feat_keys)
+    return names
+
+
+# -- Scene metadata ----------------------------------------------------------
+
+def get_scene_metadata(scene: str) -> dict:
+    """Return default metadata for a cloak scene."""
+    meta = {
+        "karman": {"scene_id": "karman", "control_interval": 800, "target_type": "periodic"},
+        "steady": {"scene_id": "steady", "control_interval": 800, "target_type": "steady"},
+        "vortex_lamb": {"scene_id": "vortex_lamb", "control_interval": 800, "target_type": "transient"},
+        "vortex_taylor": {"scene_id": "vortex_taylor", "control_interval": 800, "target_type": "transient"},
+        "erase": {"scene_id": "erase", "control_interval": 600, "target_type": "periodic"},
+    }
+    return meta.get(scene, {"scene_id": scene, "control_interval": 800, "target_type": "unknown"})

src/analysis_cloak/common/prebuild_features.py

@@ -0,0 +1,81 @@
+"""Pre-build feature matrices for SR (run in pycuda_3_10).
+
+Saves pickle files that run_sr_gplearn.py can load in sr_env.
+
+Usage:
+    conda run -n pycuda_3_10 python prebuild_features.py
+"""
+from __future__ import annotations
+
+import os
+import pickle
+import sys
+
+import numpy as np
+
+_THIS = os.path.abspath(os.path.dirname(__file__))
+_PARENT = os.path.abspath(os.path.join(_THIS, ".."))  # src/analysis_cloak/
+_REPO = os.path.abspath(os.path.join(_THIS, "..", "..", ".."))
+for p in [_PARENT, os.path.join(_PARENT, "..", "analysis_crossre", "scripts"), _REPO]:
+    if p not in sys.path:
+        sys.path.insert(0, p)
+
+from common.feature_builder import (
+    compute_dimensionless, compute_features, build_feature_matrix,
+    get_feature_names, ALL_FEAT_KEYS, U0,
+)
+from utils import action_to_physical
+from cfg import OUTPUT_DIR, ACTION_SCALE, ACTION_BIAS
+
+
+def build(scene: str):
+    X_f_l, X_r_l, y_l = [], [], []
+    if scene == "karman":
+        for rc in [50, 100, 200]:
+            npz = np.load(os.path.join(OUTPUT_DIR, f"re{rc}", "controlled.npz"))
+            s, f = npz["sensors"].astype(np.float64), npz["forces"].astype(np.float64)
+            ap = action_to_physical(npz["actions"].astype(np.float64),
+                                     scale=ACTION_SCALE, bias=ACTION_BIAS, u0=U0)
+            mu = 2.0 / rc
+            T = s.shape[0]
+            a1 = np.zeros((T, 3), dtype=np.float64)
+            a2 = np.zeros((T, 3), dtype=np.float64)
+            a1[1:] = ap[:-1]; a2[2:] = ap[:-2]
+            dim = compute_dimensionless(s, f, u0=U0, d=20.0)
+            sym = compute_features(dim, a1, a2, mu, alpha_mode=True, include_mu=True)
+            X_f_l.append(build_feature_matrix(sym, ALL_FEAT_KEYS, add_bias=False)[2:])
+            X_r_l.append(build_feature_matrix(sym, ALL_FEAT_KEYS, add_bias=True)[2:])
+            y_l.append(ap[2:])
+    else:
+        npz = np.load(os.path.join(_REPO, "src", "analysis_cloak", "scenes",
+                                    "steady", "closed_loop", "steady_data.npz"))
+        s, f = npz["sensors"].astype(np.float64), npz["forces"].astype(np.float64)
+        ap = npz["actions"].astype(np.float64)
+        mu = 2.0 / 100
+        T = s.shape[0]
+        a1 = np.zeros((T, 3), dtype=np.float64)
+        a2 = np.zeros((T, 3), dtype=np.float64)
+        a1[1:] = ap[:-1]; a2[2:] = ap[:-2]
+        dim = compute_dimensionless(s, f, u0=U0, d=20.0)
+        sym = compute_features(dim, a1, a2, mu, alpha_mode=True, include_mu=True)
+        X_f_l.append(build_feature_matrix(sym, ALL_FEAT_KEYS, add_bias=False)[2:])
+        X_r_l.append(build_feature_matrix(sym, ALL_FEAT_KEYS, add_bias=True)[2:])
+        y_l.append(ap[2:])
+
+    data = {
+        "X_f": np.vstack(X_f_l),
+        "X_r": np.vstack(X_r_l),
+        "y": np.vstack(y_l),
+        "fn_f": get_feature_names(ALL_FEAT_KEYS, add_bias=False),
+        "fn_r": get_feature_names(ALL_FEAT_KEYS, add_bias=True),
+    }
+    out = os.path.join(_REPO, "src", "analysis_cloak", "scenes", scene, "sr", f"{scene}_features.pkl")
+    os.makedirs(os.path.dirname(out), exist_ok=True)
+    with open(out, "wb") as f:
+        pickle.dump(data, f)
+    print(f"Saved {scene} features: X_f={data['X_f'].shape}, X_r={data['X_r'].shape}")
+
+
+if __name__ == "__main__":
+    for s in ["karman", "steady"]:
+        build(s)

src/analysis_cloak/common/run_sindy.py

@@ -0,0 +1,253 @@
+"""Unified SINDy fitting for all cloak scenes.
+
+Usage:
+    conda run -n pycuda_3_10 python run_sindy.py --scene karman
+    conda run -n pycuda_3_10 python run_sindy.py --scene steady
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from typing import Dict, List, Tuple
+
+import numpy as np
+
+_REPO = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+if _REPO not in sys.path:
+    sys.path.insert(0, _REPO)
+
+from src.analysis_cloak.common.feature_builder import (
+    compute_dimensionless,
+    compute_features,
+    build_feature_matrix,
+    get_feature_names,
+    apply_G_x,
+    CORE_FEAT_KEYS,
+    MU_FEAT_KEYS,
+    ALL_FEAT_KEYS,
+    U0,
+    get_scene_metadata,
+)
+from src.analysis_crossre.scripts.cfg import OUTPUT_DIR as CROSSRE_OUTPUT
+from src.analysis_crossre.scripts.utils import action_to_physical, fit_channel
+from src.analysis_crossre.scripts.cfg import ACTION_SCALE, ACTION_BIAS
+
+THRESHOLDS = [0.0, 0.001, 0.002, 0.005, 0.01, 0.015, 0.02, 0.03, 0.05, 0.1]
+
+
+def load_karman_data(re_code: int) -> Tuple:
+    """Load Karman cloak data for a single Re."""
+    case_dir = os.path.join(CROSSRE_OUTPUT, f"re{re_code}")
+    npz_path = os.path.join(case_dir, "controlled.npz")
+    if not os.path.isfile(npz_path):
+        raise FileNotFoundError(f"Missing {npz_path}")
+    data = np.load(npz_path)
+    sensors = data["sensors"].astype(np.float64)
+    forces = data["forces"].astype(np.float64)
+    actions_norm = data["actions"].astype(np.float64)
+    actions_phys = action_to_physical(
+        actions_norm, scale=ACTION_SCALE, bias=ACTION_BIAS, u0=U0)
+    mu = 2.0 / re_code
+    return sensors, forces, actions_phys, mu
+
+
+def load_steady_data():
+    """Load steady cloak data."""
+    steady_dir = os.path.join(_REPO, "src", "analysis_cloak", "scenes", "steady", "closed_loop")
+    npz_path = os.path.join(steady_dir, "steady_data.npz")
+    if not os.path.isfile(npz_path):
+        raise FileNotFoundError(f"Missing {npz_path}. Run gen_steady_data.py first.")
+    data = np.load(npz_path)
+    sensors = data["sensors"].astype(np.float64)
+    forces = data["forces"].astype(np.float64)
+    actions_phys = data["actions"].astype(np.float64)
+    mu = 2.0 / 100  # Re=100 for steady (default Re)
+    return sensors, forces, actions_phys, mu
+
+
+def build_scene_data(scene: str, re_codes: List[int] = None):
+    """Build feature matrices for a scene.
+
+    Returns (Theta_front, Theta_rear_input, Y, feat_names_front, feat_names_rear, scene_info)
+    where Theta_rear_input is the feature matrix for the rear shared-head model (top channel).
+    """
+    all_feats_front = []
+    all_feats_rear = []
+    all_Y = []
+    all_info = []
+
+    if scene == "karman":
+        if re_codes is None:
+            re_codes = [50, 100, 200]
+        for rc in re_codes:
+            sensors, forces, actions_phys, mu = load_karman_data(rc)
+            _append_scene_data(sensors, forces, actions_phys, mu, rc,
+                               all_feats_front, all_feats_rear, all_Y, all_info)
+    elif scene == "steady":
+        sensors, forces, actions_phys, mu = load_steady_data()
+        _append_scene_data(sensors, forces, actions_phys, mu, 100,
+                           all_feats_front, all_feats_rear, all_Y, all_info)
+    else:
+        raise ValueError(f"Unknown scene: {scene}")
+
+    # Stack all data
+    Theta_front = np.vstack(all_feats_front)
+    Theta_rear = np.vstack(all_feats_rear)
+    Y = np.vstack(all_Y)
+
+    # Feature names (front has no bias)
+    feat_names_front = get_feature_names(ALL_FEAT_KEYS, add_bias=False)
+    feat_names_rear = get_feature_names(ALL_FEAT_KEYS, add_bias=True)
+
+    return Theta_front, Theta_rear, Y, feat_names_front, feat_names_rear, all_info
+
+
+def _append_scene_data(sensors, forces, actions_phys, mu, re_code,
+                       all_feats_front, all_feats_rear, all_Y, all_info):
+    """Helper: compute features and append to lists."""
+    T = sensors.shape[0]
+
+    # Memory terms
+    a_prev = np.zeros((T, 3), dtype=np.float64)
+    a_prev2 = np.zeros((T, 3), dtype=np.float64)
+    a_prev[1:] = actions_phys[:-1]
+    a_prev2[2:] = actions_phys[:-2]
+
+    # Dimensionless
+    dim = compute_dimensionless(sensors, forces, u0=U0, d=20.0)
+
+    # Compute features
+    sym = compute_features(dim, a_prev, a_prev2, mu, alpha_mode=False, include_mu=True)
+
+    # Front model: no bias
+    T_eff = min(sensors.shape[0], actions_phys.shape[0])
+    Theta_f = build_feature_matrix(sym, ALL_FEAT_KEYS, add_bias=False)
+
+    # Rear model (top channel): with bias  
+    Theta_r = build_feature_matrix(sym, ALL_FEAT_KEYS, add_bias=True)
+
+    # Remove warmup (2 steps needed for lag/da)
+    all_feats_front.append(Theta_f[2:])
+    all_feats_rear.append(Theta_r[2:])
+    all_Y.append(actions_phys[2:])
+    all_info.append({"re_code": re_code, "mu": mu, "n_samples": T - 2})
+
+
+def fit_sindy(Theta, y, thresholds, output_prefix=""):
+    """Run SINDy with threshold grid, return results."""
+    import pysindy as ps
+
+    std = np.std(Theta, axis=0)
+    std = np.where(std < 1e-8, 1.0, std)
+    Theta_s = Theta / std
+
+    results = []
+    for th in thresholds:
+        opt = ps.STLSQ(threshold=th, alpha=1e-4, max_iter=25)
+        opt.fit(Theta_s, y)
+        coef = np.asarray(opt.coef_, dtype=np.float64).flatten() / std
+
+        y_pred = Theta @ coef
+        ssr = float(np.sum((y - y_pred) ** 2))
+        sst = float(np.sum((y - np.mean(y)) ** 2) + 1e-12)
+        r2 = 1.0 - ssr / sst
+        mae = float(np.mean(np.abs(y - y_pred)))
+        nz = int(np.sum(np.abs(coef) > 1e-8))
+
+        results.append({
+            "threshold": float(th), "nz": nz, "r2": r2,
+            "mae": mae, "coef": [float(c) for c in coef],
+        })
+
+    return results
+
+
+def run(scene: str, out_dir: str, re_codes: List[int] = None):
+    """Run SINDy fitting for a scene."""
+    print(f"\n{'='*60}")
+    print(f"Scene: {scene}")
+    print(f"{'='*60}")
+
+    Theta_f, Theta_r, Y, fn_f, fn_r, info = build_scene_data(scene, re_codes)
+    print(f"  Front features: {Theta_f.shape}")
+    print(f"  Rear features:  {Theta_r.shape}")
+    print(f"  Y shape:        {Y.shape}")
+
+    # Rear shared-head: fit top channel (ci=2), bottom = -top(Gx)
+    # We fit both channels independently first for comparison
+    # Front channel (ci=0, no bias)
+    print(f"\n  --- Front (no bias) ---")
+    front_results = fit_sindy(Theta_f, Y[:, 0], THRESHOLDS)
+    best_f = max(front_results, key=lambda r: r["r2"])
+    print(f"    Best: th={best_f['threshold']:.4f} nz={best_f['nz']:2d} R2={best_f['r2']:.6f}")
+
+    # Rear shared: fit top (ci=2)
+    print(f"\n  --- Top (rear shared-head) ---")
+    top_results = fit_sindy(Theta_r, Y[:, 2], THRESHOLDS)
+    best_t = max(top_results, key=lambda r: r["r2"])
+    print(f"    Best: th={best_t['threshold']:.4f} nz={best_t['nz']:2d} R2={best_t['r2']:.6f}")
+
+    # Bottom (for comparison): fit independently
+    print(f"\n  --- Bottom (independent, for comparison) ---")
+    bot_results = fit_sindy(Theta_r, Y[:, 1], THRESHOLDS)
+    best_b = max(bot_results, key=lambda r: r["r2"])
+    print(f"    Best: th={best_b['threshold']:.4f} nz={best_b['nz']:2d} R2={best_b['r2']:.6f}")
+
+    # Save results
+    result = {
+        "scene": scene,
+        "re_codes": re_codes or "default",
+        "n_samples_front": Theta_f.shape[0],
+        "n_features_front": Theta_f.shape[1],
+        "n_features_rear": Theta_r.shape[1],
+        "feature_names_front": fn_f,
+        "feature_names_rear": fn_r,
+        "front": {
+            "results": [{k: v for k, v in r.items() if k != "coef"} for r in front_results],
+            "best": {k: v for k, v in best_f.items() if k != "coef"},
+            "best_coef": best_f["coef"],
+            "sparsity_curve": [(r["threshold"], r["nz"], r["r2"]) for r in front_results],
+        },
+        "top": {
+            "results": [{k: v for k, v in r.items() if k != "coef"} for r in top_results],
+            "best": {k: v for k, v in best_t.items() if k != "coef"},
+            "best_coef": best_t["coef"],
+            "sparsity_curve": [(r["threshold"], r["nz"], r["r2"]) for r in top_results],
+        },
+        "bottom": {
+            "results": [{k: v for k, v in r.items() if k != "coef"} for r in bot_results],
+            "best": {k: v for k, v in best_b.items() if k != "coef"},
+            "best_coef": best_b["coef"],
+            "sparsity_curve": [(r["threshold"], r["nz"], r["r2"]) for r in bot_results],
+        },
+        "scene_info": info,
+    }
+
+    os.makedirs(out_dir, exist_ok=True)
+    out_path = os.path.join(out_dir, f"{scene}_sindy.json")
+    with open(out_path, "w") as f:
+        json.dump(result, f, indent=2)
+    print(f"\nSaved: {out_path}")
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--scene", type=str, required=True, choices=["karman", "steady", "all"])
+    ap.add_argument("--out-dir", type=str,
+                    default=os.path.join(_REPO, "src", "analysis_cloak", "scenes"))
+    ap.add_argument("--re-codes", type=str, default=None,
+                    help="Comma-separated Re codes for Karman (default: 50,100,200)")
+    args = ap.parse_args()
+
+    re_codes = [int(r) for r in args.re_codes.split(",")] if args.re_codes else None
+    scenes = ["karman", "steady"] if args.scene == "all" else [args.scene]
+
+    for scene in scenes:
+        sindy_dir = os.path.join(args.out_dir, scene, "sindy")
+        run(scene, sindy_dir, re_codes)
+
+
+if __name__ == "__main__":
+    main()

src/analysis_cloak/common/run_sr_pareto.py

@@ -0,0 +1,84 @@
+"""Pareto analysis of SINDy threshold grid.
+No external SR library. Runs in any env.
+
+Usage: python run_sr_pareto.py --scene karman
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from typing import List, Tuple
+
+import numpy as np
+
+_THIS = os.path.abspath(os.path.dirname(__file__))
+_REPO = os.path.abspath(os.path.join(_THIS, "..", "..", ".."))
+
+
+def load_sindy(scene: str):
+    path = os.path.join(_REPO, "src", "analysis_cloak", "scenes", scene, "sindy", f"{scene}_sindy.json")
+    with open(path) as f:
+        return json.load(f)
+
+
+def pareto(points):
+    sp = sorted(points, key=lambda x: (x[0], x[1]))
+    front, best = [], float("inf")
+    for c, e in sp:
+        if e < best:
+            front.append((c, e))
+            best = e
+    return front
+
+
+def fmt(fn, coef, th):
+    ca = np.array(coef, dtype=np.float64)
+    sc = np.max(np.abs(ca)) if np.max(np.abs(ca)) > 0 else 1.0
+    mask = np.abs(ca) / sc >= th
+    terms = [f"{ca[i]:+.4f}*{fn[i]}" for i in range(len(fn)) if mask[i]]
+    return " ".join(terms) if terms else "0"
+
+
+def analyze(name, fn, ch):
+    grid = ch["results"]
+    pts = [(g["nz"], 1.0 - g["r2"]) for g in grid]
+    front = pareto(pts)
+    best = ch["best"]
+    coef = ch["best_coef"]
+    print(f"\n  {name}:")
+    for nz, err in front:
+        r2 = 1.0 - err
+        for g in grid:
+            if g["nz"] == nz and abs(1.0 - g["r2"] - err) < 1e-10:
+                th = g["threshold"]
+                print(f"    nz={nz:2d} R2={r2:.6f} th={th:.4f}")
+                if nz <= 8:
+                    print(f"      {fmt(fn, coef, th)[:120]}")
+    print(f"  Best: R2={best['r2']:.6f}")
+    return {"channel": name, "best_r2": best["r2"],
+            "best_nz": sum(1 for c in coef if abs(float(c)) > 1e-8),
+            "pareto": [{"nz": nz, "r2": 1.0 - e} for nz, e in front]}
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--scene", required=True, choices=["karman", "steady"])
+    args = ap.parse_args()
+    s = load_sindy(args.scene)
+    print(f"Pareto SR: {args.scene}")
+    chs = [("front", s["feature_names_front"], s["front"]),
+           ("top", s["feature_names_rear"], s["top"]),
+           ("bottom", s["feature_names_rear"], s["bottom"])]
+    results = {"scene": args.scene, "channels": [analyze(*c) for c in chs]}
+    out = os.path.join(_REPO, "src", "analysis_cloak", "scenes", args.scene, "sr",
+                       f"{args.scene}_sr_pareto.json")
+    os.makedirs(os.path.dirname(out), exist_ok=True)
+    with open(out, "w") as f:
+        json.dump(results, f, indent=2)
+    print(f"Saved: {out}")
+
+
+if __name__ == "__main__":
+    main()

src/analysis_cloak/comparisons/support_overlap/run_overlap.py

@@ -0,0 +1,84 @@
+"""Support Overlap Analysis: Karman vs Steady.
+
+Compares SINDy support sets at a given sparsity threshold.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from typing import Dict, List, Tuple
+
+import numpy as np
+
+_REPO = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", "..", ".."))
+if _REPO not in sys.path:
+    sys.path.insert(0, _REPO)
+
+THRESHOLD = 0.002
+
+
+def load_sindy(scene: str) -> dict:
+    path = os.path.join(_REPO, "src", "analysis_cloak", "scenes", scene, "sindy", f"{scene}_sindy.json")
+    with open(path) as f:
+        return json.load(f)
+
+
+def get_active(feat_names: List[str], coef: List[float], threshold: float) -> Dict[str, float]:
+    scale = max(abs(c) for c in coef) if coef and max(abs(c) for c in coef) > 1e-12 else 1.0
+    active = {}
+    for name, c in zip(feat_names, coef):
+        if abs(c) / scale >= threshold:
+            active[name] = c
+    return active
+
+
+def classify(k_active: Dict, s_active: Dict) -> Tuple[List, List, List]:
+    k_set = set(k_active.keys())
+    s_set = set(s_active.keys())
+    return sorted(k_set & s_set), sorted(k_set - s_set), sorted(s_set - k_set)
+
+
+def feat_group(name: str) -> str:
+    if name == "bias": return "bias"
+    if name in ("u_m", "u_a", "u_c", "v_a", "sin_ua", "cos_ua"): return "sensor"
+    if name in ("Cd_tot", "Cd_rear", "Cl_tot", "Cl_diff"): return "force"
+    if "lag1" in name: return "memory_lag"
+    if name.startswith("da"): return "memory_delta"
+    if name == "mu" or name.startswith("mu_"): return "mu_mod"
+    return "other"
+
+
+def main():
+    print("=" * 60)
+    print(f"Support Overlap: Karman vs Steady (th={THRESHOLD})")
+    print("=" * 60)
+
+    k = load_sindy("karman")
+    s = load_sindy("steady")
+
+    channels = [
+        ("Front", "feature_names_front", "front"),
+        ("Top (shared)", "feature_names_rear", "top"),
+        ("Bottom", "feature_names_rear", "bottom"),
+    ]
+
+    for label, fn_key, ch_key in channels:
+        print(f"\n--- {label} ---")
+        fn_k, fn_s = k[fn_key], s[fn_key]
+        ka = get_active(fn_k, k[ch_key]["best_coef"], THRESHOLD)
+        sa = get_active(fn_s, s[ch_key]["best_coef"], THRESHOLD)
+        shared, ko, so = classify(ka, sa)
+
+        print(f"  Karman nz={len(ka)}  Steady nz={len(sa)}  Shared={len(shared)}")
+        for name in shared:
+            g = feat_group(name)
+            print(f"    {name:20s}  K={ka[name]:+9.6f}  S={sa[name]:+9.6f}  [{g}]")
+        for name in ko:
+            print(f"    K-ONLY {name:20s}  K={ka[name]:+9.6f}  [{feat_group(name)}]")
+        for name in so:
+            print(f"    S-ONLY {name:20s}  S={sa[name]:+9.6f}  [{feat_group(name)}]")
+
+
+if __name__ == "__main__":
+    main()

src/analysis_cloak/scenes/karman/closed_loop/re200_freq_test.json

@@ -0,0 +1,5 @@
+{
+  "si800": 0.7044314206319138,
+  "si400": 0.7877798695065495,
+  "si200": 0.6587465172737008
+}

src/analysis_cloak/scenes/karman/closed_loop/test_re200_freq.py

@@ -0,0 +1,182 @@
+"""Re200 control frequency experiment.
+
+Tests if higher control frequency improves Re200 performance.
+Uses v23 predictor (v2 coeffs + front bias=0 + rear shared-head).
+
+Usage:
+    conda run -n pycuda_3_10 python test_re200_freq.py --device 2
+"""
+import argparse
+import json
+import os
+import sys
+from collections import deque
+
+import numpy as np
+
+_PROJ = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", "..", "..", ".."))
+if _PROJ not in sys.path:
+    sys.path.insert(0, _PROJ)
+from LegacyCelerisLab import FlowField
+
+from src.analysis_crossre.scripts.utils import (
+    nu_from_re, action_to_physical, scale_action, build_karman_cloak_env,
+    add_pinball, compute_physical_symbols, save_vorticity_png,
+    vorticity_from_ddf, compute_similarity, load_legacy_configs,
+)
+from src.analysis_crossre.scripts.cfg import (
+    OUTPUT_DIR, FIFO_LEN, CONV_LEN, S_DIM, ACTION_SCALE, ACTION_BIAS, U0, CONFIG_DIR,
+)
+
+DATA_TYPE = np.float32
+RE_CODE = 200
+V2_RESULTS = os.path.join(OUTPUT_DIR, "sindy", "sindy_results_v2.json")
+
+# Feature keys matching v2 layout
+V2_FEAT_KEYS = [
+    "u_m", "u_a", "u_c", "v_a",
+    "Fx_tot", "Fx_rear", "Fy_tot", "Fy_diff",
+    "sin_ua", "cos_ua",
+    "a0_lag1", "a1_lag1", "a2_lag1",
+    "da0", "da1", "da2",
+]
+V2_MU_KEYS = ["mu", "mu_u_a", "mu_v_a", "mu_Fx_tot", "mu_Fy_diff", "mu_Fy_tot"]
+
+
+def apply_G_raw(obs_slice, a_prev, a_prev2):
+    G_obs = np.zeros(12, dtype=np.float64)
+    G_obs[0] = obs_slice[4]
+    G_obs[1] = -obs_slice[5]
+    G_obs[2] = obs_slice[2]
+    G_obs[3] = -obs_slice[3]
+    G_obs[4] = obs_slice[0]
+    G_obs[5] = -obs_slice[1]
+    G_obs[6] = obs_slice[6]
+    G_obs[7] = -obs_slice[7]
+    G_obs[8] = obs_slice[10]
+    G_obs[9] = -obs_slice[11]
+    G_obs[10] = obs_slice[8]
+    G_obs[11] = -obs_slice[9]
+    G_a_prev = np.array([-a_prev[0], -a_prev[2], -a_prev[1]], dtype=np.float64)
+    G_a_prev2 = np.array([-a_prev2[0], -a_prev2[2], -a_prev2[1]], dtype=np.float64)
+    return G_obs, G_a_prev, G_a_prev2
+
+
+def build_feat_vec(obs_slice, a_prev, a_prev2, mu, add_bias):
+    sensors = obs_slice[0:6].astype(np.float64).reshape(1, 6)
+    forces = obs_slice[6:12].astype(np.float64).reshape(1, 6)
+    ap = a_prev.astype(np.float64).reshape(1, 3)
+    ap2 = a_prev2.astype(np.float64).reshape(1, 3)
+    sym = compute_physical_symbols(sensors, forces, ap, ap2)
+    sym["mu"] = np.array([mu])
+    sym["mu_u_a"] = sym["u_a"] * mu
+    sym["mu_v_a"] = sym["v_a"] * mu
+    sym["mu_Fx_tot"] = sym["Fx_tot"] * mu
+    sym["mu_Fy_diff"] = sym["Fy_diff"] * mu
+    sym["mu_Fy_tot"] = sym["Fy_tot"] * mu
+    vals = []
+    if add_bias:
+        vals.append(1.0)
+    for k in V2_FEAT_KEYS:
+        vals.append(float(sym[k][0]))
+    for k in V2_MU_KEYS:
+        vals.append(float(sym[k][0]))
+    return np.array(vals, dtype=np.float64)
+
+
+def load_coefs(path):
+    with open(path) as f:
+        data = json.load(f)
+    coefs_list = data["cross_re"]["channels"]
+    coefs_list[0]["best_coef"][0] = 0.0  # zero front bias
+    return {
+        "front": {"coef": np.array(coefs_list[0]["best_coef"], dtype=np.float64), "has_bias": True},
+        "top": {"coef": np.array(coefs_list[2]["best_coef"], dtype=np.float64), "has_bias": True},
+    }
+
+
+def predict(obs_slice, a_prev, a_prev2, coefs, mu):
+    feat = build_feat_vec(obs_slice, a_prev, a_prev2, mu, add_bias=True)
+    front = float(feat @ coefs["front"]["coef"])
+    top = float(feat @ coefs["top"]["coef"])
+    G_obs, G_a_prev, G_a_prev2 = apply_G_raw(obs_slice, a_prev, a_prev2)
+    feat_G = build_feat_vec(G_obs, G_a_prev, G_a_prev2, mu, add_bias=True)
+    bottom = -float(feat_G @ coefs["top"]["coef"])
+    return np.array([front, bottom, top], dtype=np.float64)
+
+
+def run(re_code, sample_interval, device_id, output_dir):
+    mu = 2.0 / re_code
+    label = f"Re{re_code}_si{sample_interval}"
+    os.makedirs(output_dir, exist_ok=True)
+
+    coefs = load_coefs(V2_RESULTS)
+    cuda_cfg, field_cfg = load_legacy_configs(CONFIG_DIR)
+    field_cfg = field_cfg._replace(viscosity=float(nu_from_re(re_code, u0=U0)))
+    ff = FlowField(field_cfg, cuda_cfg, device_id=device_id)
+
+    target_states, _ = build_karman_cloak_env(ff, u0=U0, l0=20.0,
+        sample_interval=sample_interval, fifo_len=FIFO_LEN, data_type=DATA_TYPE)
+    norm = add_pinball(ff, l0=20.0, u0=U0, sample_interval=sample_interval,
+        fifo_len=FIFO_LEN, data_type=DATA_TYPE, action_bias=ACTION_BIAS)
+
+    ff.restore_ddf();
+    ff.apply_ddf()
+    fifo = deque(maxlen=FIFO_LEN)
+    bias_action = scale_action(np.zeros(3, dtype=np.float32), scale=ACTION_SCALE,
+                                 bias=ACTION_BIAS, u0=U0, n_total_bodies=7)
+    for _ in range(FIFO_LEN):
+        ff.run(sample_interval, bias_action)
+        fifo.append(ff.obs.copy()[2:14])
+
+    sens_sc = []
+    a_prev = action_to_physical(np.zeros((1,3), dtype=np.float32),
+                                 scale=ACTION_SCALE, bias=ACTION_BIAS, u0=U0).flatten()
+    a_prev2 = a_prev.copy()
+    n_steps = 100
+
+    for _ in range(n_steps):
+        obs = fifo[-1] if len(fifo) > 0 else np.zeros(12, dtype=np.float32)
+        omega = predict(obs, a_prev, a_prev2, coefs, mu)
+        norm_a = (omega / U0 - np.array(ACTION_BIAS, dtype=np.float64)) / ACTION_SCALE
+        norm_a = np.clip(norm_a, -1.0, 1.0).astype(np.float32)
+        action_arr = scale_action(norm_a, scale=ACTION_SCALE, bias=ACTION_BIAS, u0=U0, n_total_bodies=7)
+        ff.run(sample_interval, action_arr)
+        obs_new = ff.obs.copy()[2:14]
+        fifo.append(obs_new)
+        sens_sc.append(obs_new[0:6])
+        a_prev2 = a_prev.copy()
+        a_prev = omega.copy()
+
+    sens_arr = np.array(sens_sc, dtype=np.float32)
+    sim = compute_similarity(target_states, sens_arr, CONV_LEN)
+    print(f"  {label}: similarity={sim:.4f}")
+
+    del ff
+    return sim
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--device", type=int, default=2)
+    args = ap.parse_args()
+
+    out_dir = os.path.join(_PROJ, "src", "analysis_cloak", "scenes", "karman", "closed_loop")
+    os.makedirs(out_dir, exist_ok=True)
+
+    intervals = [800, 400, 200]
+    results = {}
+    for si in intervals:
+        sim = run(RE_CODE, si, args.device, out_dir)
+        results[f"si{si}"] = sim
+
+    print(f"\nRe200 frequency test results:")
+    for si, sim in results.items():
+        print(f"  SAMPLE_INTERVAL={si}: similarity={sim:.4f}")
+
+    with open(os.path.join(out_dir, "re200_freq_test.json"), "w") as f:
+        json.dump(results, f, indent=2)
+
+
+if __name__ == "__main__":
+    main()

src/analysis_cloak/scenes/karman/sindy/karman_sindy.json

@@ -0,0 +1,508 @@
+{
+  "scene": "karman",
+  "re_codes": "default",
+  "n_samples_front": 444,
+  "n_features_front": 21,
+  "n_features_rear": 22,
+  "feature_names_front": [
+    "u_m",
+    "u_a",
+    "u_c",
+    "v_a",
+    "Cd_tot",
+    "Cd_rear",
+    "Cl_tot",
+    "Cl_diff",
+    "sin_ua",
+    "cos_ua",
+    "aF_lag1",
+    "aB_lag1",
+    "aT_lag1",
+    "daF",
+    "daB",
+    "daT",
+    "mu",
+    "mu_u_a",
+    "mu_v_a",
+    "mu_Cd_tot",
+    "mu_Cl_diff"
+  ],
+  "feature_names_rear": [
+    "bias",
+    "u_m",
+    "u_a",
+    "u_c",
+    "v_a",
+    "Cd_tot",
+    "Cd_rear",
+    "Cl_tot",
+    "Cl_diff",
+    "sin_ua",
+    "cos_ua",
+    "aF_lag1",
+    "aB_lag1",
+    "aT_lag1",
+    "daF",
+    "daB",
+    "daT",
+    "mu",
+    "mu_u_a",
+    "mu_v_a",
+    "mu_Cd_tot",
+    "mu_Cl_diff"
+  ],
+  "front": {
+    "results": [
+      {
+        "threshold": 0.0,
+        "nz": 21,
+        "r2": 0.9654966682363757,
+        "mae": 0.0023056666760656796
+      },
+      {
+        "threshold": 0.001,
+        "nz": 5,
+        "r2": 0.9536016197206115,
+        "mae": 0.002601817745080991
+      },
+      {
+        "threshold": 0.002,
+        "nz": 2,
+        "r2": 0.9452383376955145,
+        "mae": 0.00274020474447065
+      },
+      {
+        "threshold": 0.005,
+        "nz": 2,
+        "r2": 0.9452383376955145,
+        "mae": 0.00274020474447065
+      },
+      {
+        "threshold": 0.01,
+        "nz": 1,
+        "r2": 0.860607207574008,
+        "mae": 0.005171636101202507
+      },
+      {
+        "threshold": 0.015,
+        "nz": 0,
+        "r2": -0.025600612306448944,
+        "mae": 0.01601045471490235
+      },
+      {
+        "threshold": 0.02,
+        "nz": 0,
+        "r2": -0.025600612306448944,
+        "mae": 0.01601045471490235
+      },
+      {
+        "threshold": 0.03,
+        "nz": 0,
+        "r2": -0.025600612306448944,
+        "mae": 0.01601045471490235
+      },
+      {
+        "threshold": 0.05,
+        "nz": 0,
+        "r2": -0.025600612306448944,
+        "mae": 0.01601045471490235
+      },
+      {
+        "threshold": 0.1,
+        "nz": 0,
+        "r2": -0.025600612306448944,
+        "mae": 0.01601045471490235
+      }
+    ],
+    "best": {
+      "threshold": 0.0,
+      "nz": 21,
+      "r2": 0.9654966682363757,
+      "mae": 0.0023056666760656796
+    },
+    "best_coef": [
+      -5.192955717959975e-05,
+      2.8758845410456916e-05,
+      -1.1774957671598127e-05,
+      -3.25172225327354e-05,
+      0.0015201286832842583,
+      0.0003656613747736437,
+      -0.0007681231453227206,
+      0.0003090074931666537,
+      1.2582646790399684e-07,
+      0.0002743780546501911,
+      0.007096991322989564,
+      -0.001425750496064129,
+      0.0006433749857293151,
+      0.008791801878378852,
+      0.0028160283947971055,
+      -0.0005095282162885374,
+      -0.16160246819614302,
+      0.0007252560276568708,
+      -0.002241307134772526,
+      -0.021184890828600162,
+      -0.021767971799948535
+    ],
+    "sparsity_curve": [
+      [
+        0.0,
+        21,
+        0.9654966682363757
+      ],
+      [
+        0.001,
+        5,
+        0.9536016197206115
+      ],
+      [
+        0.002,
+        2,
+        0.9452383376955145
+      ],
+      [
+        0.005,
+        2,
+        0.9452383376955145
+      ],
+      [
+        0.01,
+        1,
+        0.860607207574008
+      ],
+      [
+        0.015,
+        0,
+        -0.025600612306448944
+      ],
+      [
+        0.02,
+        0,
+        -0.025600612306448944
+      ],
+      [
+        0.03,
+        0,
+        -0.025600612306448944
+      ],
+      [
+        0.05,
+        0,
+        -0.025600612306448944
+      ],
+      [
+        0.1,
+        0,
+        -0.025600612306448944
+      ]
+    ]
+  },
+  "top": {
+    "results": [
+      {
+        "threshold": 0.0,
+        "nz": 22,
+        "r2": 0.862596324781397,
+        "mae": 0.00633210084008296
+      },
+      {
+        "threshold": 0.001,
+        "nz": 19,
+        "r2": 0.8613618595140851,
+        "mae": 0.006368110213095571
+      },
+      {
+        "threshold": 0.002,
+        "nz": 14,
+        "r2": 0.8493750057676241,
+        "mae": 0.006730015193486602
+      },
+      {
+        "threshold": 0.005,
+        "nz": 7,
+        "r2": 0.7827214013687178,
+        "mae": 0.00802796108799867
+      },
+      {
+        "threshold": 0.01,
+        "nz": 1,
+        "r2": 0.6121198810123357,
+        "mae": 0.009530874364852419
+      },
+      {
+        "threshold": 0.015,
+        "nz": 1,
+        "r2": 0.6121198810123357,
+        "mae": 0.009530874364852419
+      },
+      {
+        "threshold": 0.02,
+        "nz": 1,
+        "r2": 3.654743174763553e-12,
+        "mae": 0.0173810294687437
+      },
+      {
+        "threshold": 0.03,
+        "nz": 1,
+        "r2": 3.654743174763553e-12,
+        "mae": 0.0173810294687437
+      },
+      {
+        "threshold": 0.05,
+        "nz": 0,
+        "r2": -2.2359943125676613,
+        "mae": 0.039575029794999335
+      },
+      {
+        "threshold": 0.1,
+        "nz": 0,
+        "r2": -2.2359943125676613,
+        "mae": 0.039575029794999335
+      }
+    ],
+    "best": {
+      "threshold": 0.0,
+      "nz": 22,
+      "r2": 0.862596324781397,
+      "mae": 0.00633210084008296
+    },
+    "best_coef": [
+      -0.05500806404528806,
+      0.0007420012135347702,
+      -0.0005289839138368902,
+      -7.059719059238487e-05,
+      0.0006778963140888031,
+      -0.001096838965444243,
+      -0.0006586342747236175,
+      0.0034452827223076256,
+      -0.0015323585728228434,
+      -0.0006424234277769932,
+      -0.0007755764497972763,
+      0.005024202346778029,
+      0.0034193717761402237,
+      0.00640250610361064,
+      -0.005852277491977138,
+      -0.003193207096374315,
+      0.0032222577962603585,
+      -0.35037148676340113,
+      0.023157523040313266,
+      -0.04322885440841332,
+      -0.050453986820807865,
+      -0.051262980383116864
+    ],
+    "sparsity_curve": [
+      [
+        0.0,
+        22,
+        0.862596324781397
+      ],
+      [
+        0.001,
+        19,
+        0.8613618595140851
+      ],
+      [
+        0.002,
+        14,
+        0.8493750057676241
+      ],
+      [
+        0.005,
+        7,
+        0.7827214013687178
+      ],
+      [
+        0.01,
+        1,
+        0.6121198810123357
+      ],
+      [
+        0.015,
+        1,
+        0.6121198810123357
+      ],
+      [
+        0.02,
+        1,
+        3.654743174763553e-12
+      ],
+      [
+        0.03,
+        1,
+        3.654743174763553e-12
+      ],
+      [
+        0.05,
+        0,
+        -2.2359943125676613
+      ],
+      [
+        0.1,
+        0,
+        -2.2359943125676613
+      ]
+    ]
+  },
+  "bottom": {
+    "results": [
+      {
+        "threshold": 0.0,
+        "nz": 22,
+        "r2": 0.8993440589380792,
+        "mae": 0.004870578129840853
+      },
+      {
+        "threshold": 0.001,
+        "nz": 10,
+        "r2": 0.8959720170147872,
+        "mae": 0.004940764682366889
+      },
+      {
+        "threshold": 0.002,
+        "nz": 8,
+        "r2": 0.8924474832818312,
+        "mae": 0.004917054661924924
+      },
+      {
+        "threshold": 0.005,
+        "nz": 5,
+        "r2": 0.8580026242147389,
+        "mae": 0.0059864202818160055
+      },
+      {
+        "threshold": 0.01,
+        "nz": 1,
+        "r2": 0.7104836293852221,
+        "mae": 0.008387153194050426
+      },
+      {
+        "threshold": 0.015,
+        "nz": 1,
+        "r2": 0.7104836293852221,
+        "mae": 0.008387153194050426
+      },
+      {
+        "threshold": 0.02,
+        "nz": 1,
+        "r2": 0.7104836293852221,
+        "mae": 0.008387153194050426
+      },
+      {
+        "threshold": 0.03,
+        "nz": 0,
+        "r2": -2.8272225894084078,
+        "mae": 0.038829327024821496
+      },
+      {
+        "threshold": 0.05,
+        "nz": 0,
+        "r2": -2.8272225894084078,
+        "mae": 0.038829327024821496
+      },
+      {
+        "threshold": 0.1,
+        "nz": 0,
+        "r2": -2.8272225894084078,
+        "mae": 0.038829327024821496
+      }
+    ],
+    "best": {
+      "threshold": 0.0,
+      "nz": 22,
+      "r2": 0.8993440589380792,
+      "mae": 0.004870578129840853
+    },
+    "best_coef": [
+      -0.010075042034336805,
+      0.000127456261090308,
+      -0.00018640871260677575,
+      -1.0786662376718973e-05,
+      0.00013209953181097446,
+      -0.0029808562650467663,
+      -0.0003882575275073206,
+      0.0021351638754212236,
+      -0.0005317242032502552,
+      -1.4526187037145631e-05,
+      -0.0004792609214251783,
+      0.0035849480411721288,
+      0.009840224256264653,
+      -0.0008193716182580219,
+      -0.005477208879386436,
+      0.00248443011612523,
+      -0.001596550946452102,
+      0.10495659563156284,
+      0.0036966535058393694,
+      -0.006256407760146263,
+      0.05741274816660643,
+      0.028241944772701748
+    ],
+    "sparsity_curve": [
+      [
+        0.0,
+        22,
+        0.8993440589380792
+      ],
+      [
+        0.001,
+        10,
+        0.8959720170147872
+      ],
+      [
+        0.002,
+        8,
+        0.8924474832818312
+      ],
+      [
+        0.005,
+        5,
+        0.8580026242147389
+      ],
+      [
+        0.01,
+        1,
+        0.7104836293852221
+      ],
+      [
+        0.015,
+        1,
+        0.7104836293852221
+      ],
+      [
+        0.02,
+        1,
+        0.7104836293852221
+      ],
+      [
+        0.03,
+        0,
+        -2.8272225894084078
+      ],
+      [
+        0.05,
+        0,
+        -2.8272225894084078
+      ],
+      [
+        0.1,
+        0,
+        -2.8272225894084078
+      ]
+    ]
+  },
+  "scene_info": [
+    {
+      "re_code": 50,
+      "mu": 0.04,
+      "n_samples": 148
+    },
+    {
+      "re_code": 100,
+      "mu": 0.02,
+      "n_samples": 148
+    },
+    {
+      "re_code": 200,
+      "mu": 0.01,
+      "n_samples": 148
+    }
+  ]
+}

src/analysis_cloak/scenes/karman/sr/karman_sr_pareto.json

@@ -0,0 +1,94 @@
+{
+  "scene": "karman",
+  "channels": [
+    {
+      "channel": "front",
+      "best_r2": 0.9654966682363757,
+      "best_nz": 21,
+      "pareto": [
+        {
+          "nz": 0,
+          "r2": -0.025600612306448944
+        },
+        {
+          "nz": 1,
+          "r2": 0.860607207574008
+        },
+        {
+          "nz": 2,
+          "r2": 0.9452383376955145
+        },
+        {
+          "nz": 5,
+          "r2": 0.9536016197206115
+        },
+        {
+          "nz": 21,
+          "r2": 0.9654966682363757
+        }
+      ]
+    },
+    {
+      "channel": "top",
+      "best_r2": 0.862596324781397,
+      "best_nz": 22,
+      "pareto": [
+        {
+          "nz": 0,
+          "r2": -2.2359943125676613
+        },
+        {
+          "nz": 1,
+          "r2": 0.6121198810123357
+        },
+        {
+          "nz": 7,
+          "r2": 0.7827214013687178
+        },
+        {
+          "nz": 14,
+          "r2": 0.8493750057676241
+        },
+        {
+          "nz": 19,
+          "r2": 0.8613618595140851
+        },
+        {
+          "nz": 22,
+          "r2": 0.862596324781397
+        }
+      ]
+    },
+    {
+      "channel": "bottom",
+      "best_r2": 0.8993440589380792,
+      "best_nz": 22,
+      "pareto": [
+        {
+          "nz": 0,
+          "r2": -2.8272225894084078
+        },
+        {
+          "nz": 1,
+          "r2": 0.7104836293852221
+        },
+        {
+          "nz": 5,
+          "r2": 0.8580026242147389
+        },
+        {
+          "nz": 8,
+          "r2": 0.8924474832818312
+        },
+        {
+          "nz": 10,
+          "r2": 0.8959720170147872
+        },
+        {
+          "nz": 22,
+          "r2": 0.8993440589380792
+        }
+      ]
+    }
+  ]
+}

src/analysis_cloak/scenes/steady/closed_loop/gen_steady_data.py

@@ -0,0 +1,170 @@
+"""Generate steady cloak data.
+
+Steady cloak uses open-loop constant rotation (no PPO model).
+The environment has pinball cylinders but no disturbance cylinder.
+Target is clean parabolic inflow (constant sensor values).
+
+Usage:
+    conda run -n pycuda_3_10 python gen_steady_data.py --device 2
+"""
+import argparse
+import os
+import sys
+from collections import deque
+
+import numpy as np
+
+_PROJ = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", "..", "..", ".."))
+if _PROJ not in sys.path:
+    sys.path.insert(0, _PROJ)
+from LegacyCelerisLab import FlowField
+from LegacyCelerisLab import utils as legacy_utils
+
+# Point to analysis_crossre configs
+CONFIG_DIR = os.path.join(_PROJ, "src", "analysis_crossre", "configs")
+OUTPUT_DIR = os.path.join(_PROJ, "src", "analysis_cloak", "scenes", "steady", "closed_loop")
+
+U0 = 0.01
+L0 = 20
+SAMPLE_INTERVAL = 800
+FIFO_LEN = 150
+DATA_TYPE = np.float32
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--device", type=int, default=2)
+    ap.add_argument("--action-top", type=float, default=5.1, help="Top cylinder omega factor")
+    ap.add_argument("--action-bottom", type=float, default=-5.1, help="Bottom cylinder omega factor")
+    ap.add_argument("--n-steps", type=int, default=200)
+    args = ap.parse_args()
+
+    os.makedirs(OUTPUT_DIR, exist_ok=True)
+
+    cuda_cfg = legacy_utils.load_cuda_config(os.path.join(CONFIG_DIR, "config_cuda.json"))
+    field_cfg = legacy_utils.load_flow_field_config(os.path.join(CONFIG_DIR, "config_flowfield.json"))
+
+    ff = FlowField(field_cfg, cuda_cfg, device_id=args.device)
+    NY = ff.FIELD_SHAPE[1]
+    NX = ff.FIELD_SHAPE[0]
+
+    # Step 1: Add only pinball cylinders (NO disturbance cylinder)
+    # Front cylinder
+    ff.add_cylinder((30 * L0, (NY - 1) / 2, 0), L0 / 2)
+    # Bottom cylinder
+    ff.add_cylinder((31.3 * L0, (NY - 1) / 2 - 0.75 * L0, 0), L0 / 2)
+    # Top cylinder
+    ff.add_cylinder((31.3 * L0, (NY - 1) / 2 + 0.75 * L0, 0), L0 / 2)
+    # 3 sensors at x=40*L0
+    ff.add_sensor((40 * L0, (NY - 1) / 2 + 2 * L0, 0), L0 / 4)
+    ff.add_sensor((40 * L0, (NY - 1) / 2, 0), L0 / 4)
+    ff.add_sensor((40 * L0, (NY - 1) / 2 - 2 * L0, 0), L0 / 4)
+
+    n_bodies = ff.obs.size // 2
+    print(f"Bodies: {n_bodies} (3 pinball + 3 sensors)")
+
+    # Step 2: Stabilize with zero action
+    stabilize_steps = int(4 * NX / U0)
+    print(f"Stabilising ({stabilize_steps} steps)...")
+    ff.run(stabilize_steps, np.zeros(n_bodies, dtype=DATA_TYPE))
+    ff.get_ddf()
+    ff.save_ddf()
+
+    # Step 3: Record target (steady inflow, no pinball) - we already have clean inflow as target
+    # For steady cloak, target is just the mean of clean parabolic inflow
+    # But since we built env WITH pinball, we need target separately
+    # Actually for steady cloak, target is just the inlet profile at sensor positions
+    # Let's compute it: run with all bodies but minimal disturbance
+    # The "target" is simply the flow that would exist without pinball
+    # Since this is a parabolic channel, the sensors would read the undisturbed parabolic profile
+
+    # For simplicity, record the initial steady-state sensor values as target
+    ff.restore_ddf()
+    ff.apply_ddf()
+    target_list = []
+    for i in range(FIFO_LEN):
+        ff.run(SAMPLE_INTERVAL, np.zeros(n_bodies, dtype=DATA_TYPE))
+        obs_slice = ff.obs.copy()
+        # obs for 6 bodies: [sensor0(2), sensor1(2), sensor2(2), cyl0(2), cyl1(2), cyl2(2)]
+        # We only want sensor values: indices 0..5
+        target_list.append(obs_slice[0:6].copy())
+
+    target_states = np.array(target_list, dtype=np.float32)
+    target_mean = np.mean(target_states, axis=0)
+    print(f"Target mean (steady inflow at sensors): {target_mean}")
+
+    # Step 4: Run with constant rotation
+    ff.restore_ddf()
+    ff.apply_ddf()
+
+    constant_action = np.zeros(n_bodies, dtype=DATA_TYPE)
+    constant_action[n_bodies - 3] = 0.0 * U0                    # front
+    constant_action[n_bodies - 2] = float(args.action_bottom * U0)  # bottom
+    constant_action[n_bodies - 1] = float(args.action_top * U0)     # top
+    print(f"Constant action: {constant_action}")
+
+    # Stabilize to the controlled state
+    print("Running controlled steady state...")
+    for i in range(FIFO_LEN):
+        ff.run(SAMPLE_INTERVAL, constant_action)
+
+    # Record controlled data
+    sensors_list = []
+    forces_list = []
+    actions_list = []
+
+    for step in range(args.n_steps):
+        ff.run(SAMPLE_INTERVAL, constant_action)
+        obs_slice = ff.obs.copy()
+        sensors_list.append(obs_slice[0:6].copy())
+        forces_list.append(obs_slice[6:12].copy())  # pinball forces are at indices 6-11
+        actions_list.append(constant_action[n_bodies - 3:n_bodies].copy())
+
+    sensors_arr = np.array(sensors_list, dtype=np.float32)
+    forces_arr = np.array(forces_list, dtype=np.float32)
+    actions_arr = np.array(actions_list, dtype=np.float32)
+
+    print(f"Sensors shape: {sensors_arr.shape}")
+    print(f"Forces shape: {forces_arr.shape}")
+    print(f"Sensor mean (controlled): {np.mean(sensors_arr, axis=0)}")
+    print(f"Force mean (controlled): {np.mean(forces_arr, axis=0)}")
+
+    # Save
+    out_path = os.path.join(OUTPUT_DIR, "steady_data.npz")
+    np.savez(out_path, sensors=sensors_arr, forces=forces_arr,
+             actions=actions_arr, target_states=target_states,
+             action_constant=constant_action)
+    print(f"Saved: {out_path}")
+
+    # Also save vorticity of final state
+    ff.get_ddf()
+    ddf = ff.ddf.copy().reshape((9, NY, NX)).transpose(2, 1, 0)
+    ux = (ddf[:, :, 1] + ddf[:, :, 5] + ddf[:, :, 8] - ddf[:, :, 3] - ddf[:, :, 6] - ddf[:, :, 7]) / U0
+    uy = (ddf[:, :, 2] + ddf[:, :, 5] + ddf[:, :, 6] - ddf[:, :, 4] - ddf[:, :, 7] - ddf[:, :, 8]) / U0
+    omega = np.gradient(uy, axis=1) - np.gradient(ux, axis=0)
+
+    try:
+        import matplotlib
+        matplotlib.use("Agg")
+        import matplotlib.pyplot as plt
+        abs_o = np.abs(omega[np.isfinite(omega)])
+        vmax = float(np.percentile(abs_o, 99.5)) if abs_o.size > 0 else 1.0
+        if vmax <= 0:
+            vmax = 1.0
+        fig, ax = plt.subplots(figsize=(12, 5))
+        im = ax.imshow(omega, origin="lower", aspect="equal", cmap="RdBu_r",
+                       vmin=-vmax, vmax=vmax, extent=(0, NX - 1, 0, NY - 1))
+        ax.set_title(f"Steady cloak: action=[0, {args.action_bottom}, {args.action_top}]*U0")
+        fig.colorbar(im, ax=ax, fraction=0.046, pad=0.04)
+        fig.savefig(os.path.join(OUTPUT_DIR, "vorticity_steady.png"), dpi=150, bbox_inches="tight")
+        plt.close(fig)
+        print(f"Vorticity saved to {OUTPUT_DIR}/vorticity_steady.png")
+    except ImportError:
+        print("matplotlib not available, skipping vorticity PNG")
+
+    del ff
+    print("Done")
+
+
+if __name__ == "__main__":
+    main()

src/analysis_cloak/scenes/steady/sindy/steady_sindy.json

@@ -0,0 +1,498 @@
+{
+  "scene": "steady",
+  "re_codes": "default",
+  "n_samples_front": 198,
+  "n_features_front": 21,
+  "n_features_rear": 22,
+  "feature_names_front": [
+    "u_m",
+    "u_a",
+    "u_c",
+    "v_a",
+    "Cd_tot",
+    "Cd_rear",
+    "Cl_tot",
+    "Cl_diff",
+    "sin_ua",
+    "cos_ua",
+    "aF_lag1",
+    "aB_lag1",
+    "aT_lag1",
+    "daF",
+    "daB",
+    "daT",
+    "mu",
+    "mu_u_a",
+    "mu_v_a",
+    "mu_Cd_tot",
+    "mu_Cl_diff"
+  ],
+  "feature_names_rear": [
+    "bias",
+    "u_m",
+    "u_a",
+    "u_c",
+    "v_a",
+    "Cd_tot",
+    "Cd_rear",
+    "Cl_tot",
+    "Cl_diff",
+    "sin_ua",
+    "cos_ua",
+    "aF_lag1",
+    "aB_lag1",
+    "aT_lag1",
+    "daF",
+    "daB",
+    "daT",
+    "mu",
+    "mu_u_a",
+    "mu_v_a",
+    "mu_Cd_tot",
+    "mu_Cl_diff"
+  ],
+  "front": {
+    "results": [
+      {
+        "threshold": 0.0,
+        "nz": 0,
+        "r2": 1.0,
+        "mae": 0.0
+      },
+      {
+        "threshold": 0.001,
+        "nz": 0,
+        "r2": 1.0,
+        "mae": 0.0
+      },
+      {
+        "threshold": 0.002,
+        "nz": 0,
+        "r2": 1.0,
+        "mae": 0.0
+      },
+      {
+        "threshold": 0.005,
+        "nz": 0,
+        "r2": 1.0,
+        "mae": 0.0
+      },
+      {
+        "threshold": 0.01,
+        "nz": 0,
+        "r2": 1.0,
+        "mae": 0.0
+      },
+      {
+        "threshold": 0.015,
+        "nz": 0,
+        "r2": 1.0,
+        "mae": 0.0
+      },
+      {
+        "threshold": 0.02,
+        "nz": 0,
+        "r2": 1.0,
+        "mae": 0.0
+      },
+      {
+        "threshold": 0.03,
+        "nz": 0,
+        "r2": 1.0,
+        "mae": 0.0
+      },
+      {
+        "threshold": 0.05,
+        "nz": 0,
+        "r2": 1.0,
+        "mae": 0.0
+      },
+      {
+        "threshold": 0.1,
+        "nz": 0,
+        "r2": 1.0,
+        "mae": 0.0
+      }
+    ],
+    "best": {
+      "threshold": 0.0,
+      "nz": 0,
+      "r2": 1.0,
+      "mae": 0.0
+    },
+    "best_coef": [
+      0.0,
+      0.0,
+      0.0,
+      0.0,
+      0.0,
+      0.0,
+      0.0,
+      0.0,
+      0.0,
+      0.0,
+      0.0,
+      0.0,
+      0.0,
+      0.0,
+      0.0,
+      0.0,
+      0.0,
+      0.0,
+      0.0,
+      0.0,
+      0.0
+    ],
+    "sparsity_curve": [
+      [
+        0.0,
+        0,
+        1.0
+      ],
+      [
+        0.001,
+        0,
+        1.0
+      ],
+      [
+        0.002,
+        0,
+        1.0
+      ],
+      [
+        0.005,
+        0,
+        1.0
+      ],
+      [
+        0.01,
+        0,
+        1.0
+      ],
+      [
+        0.015,
+        0,
+        1.0
+      ],
+      [
+        0.02,
+        0,
+        1.0
+      ],
+      [
+        0.03,
+        0,
+        1.0
+      ],
+      [
+        0.05,
+        0,
+        1.0
+      ],
+      [
+        0.1,
+        0,
+        1.0
+      ]
+    ]
+  },
+  "top": {
+    "results": [
+      {
+        "threshold": 0.0,
+        "nz": 10,
+        "r2": 0.9583284280391652,
+        "mae": 1.15718787598632e-08
+      },
+      {
+        "threshold": 0.001,
+        "nz": 0,
+        "r2": -514997980738.5937,
+        "mae": 0.050999999046325684
+      },
+      {
+        "threshold": 0.002,
+        "nz": 0,
+        "r2": -514997980738.5937,
+        "mae": 0.050999999046325684
+      },
+      {
+        "threshold": 0.005,
+        "nz": 0,
+        "r2": -514997980738.5937,
+        "mae": 0.050999999046325684
+      },
+      {
+        "threshold": 0.01,
+        "nz": 0,
+        "r2": -514997980738.5937,
+        "mae": 0.050999999046325684
+      },
+      {
+        "threshold": 0.015,
+        "nz": 0,
+        "r2": -514997980738.5937,
+        "mae": 0.050999999046325684
+      },
+      {
+        "threshold": 0.02,
+        "nz": 0,
+        "r2": -514997980738.5937,
+        "mae": 0.050999999046325684
+      },
+      {
+        "threshold": 0.03,
+        "nz": 0,
+        "r2": -514997980738.5937,
+        "mae": 0.050999999046325684
+      },
+      {
+        "threshold": 0.05,
+        "nz": 0,
+        "r2": -514997980738.5937,
+        "mae": 0.050999999046325684
+      },
+      {
+        "threshold": 0.1,
+        "nz": 0,
+        "r2": -514997980738.5937,
+        "mae": 0.050999999046325684
+      }
+    ],
+    "best": {
+      "threshold": 0.0,
+      "nz": 10,
+      "r2": 0.9583284280391652,
+      "mae": 1.15718787598632e-08
+    },
+    "best_coef": [
+      9.472058267524708e-09,
+      -0.0002241008167953442,
+      -0.003224155981542969,
+      7.459967868655183e-05,
+      0.0002720854703143245,
+      -1.1691407051761946e-10,
+      9.171553339138634e-11,
+      -6.477660414852548e-10,
+      -5.860206010691412e-11,
+      -0.0009623592127892139,
+      0.05095243656815282,
+      0.0,
+      -4.8247913174868025e-08,
+      4.8247908281752745e-08,
+      0.0,
+      0.0,
+      0.0,
+      1.8886475698738897e-10,
+      -0.16119707097288422,
+      0.013584418707664971,
+      -4.12272941645026e-09,
+      -2.9297936037658187e-09
+    ],
+    "sparsity_curve": [
+      [
+        0.0,
+        10,
+        0.9583284280391652
+      ],
+      [
+        0.001,
+        0,
+        -514997980738.5937
+      ],
+      [
+        0.002,
+        0,
+        -514997980738.5937
+      ],
+      [
+        0.005,
+        0,
+        -514997980738.5937
+      ],
+      [
+        0.01,
+        0,
+        -514997980738.5937
+      ],
+      [
+        0.015,
+        0,
+        -514997980738.5937
+      ],
+      [
+        0.02,
+        0,
+        -514997980738.5937
+      ],
+      [
+        0.03,
+        0,
+        -514997980738.5937
+      ],
+      [
+        0.05,
+        0,
+        -514997980738.5937
+      ],
+      [
+        0.1,
+        0,
+        -514997980738.5937
+      ]
+    ]
+  },
+  "bottom": {
+    "results": [
+      {
+        "threshold": 0.0,
+        "nz": 10,
+        "r2": 0.9583284280391652,
+        "mae": 1.15718787598632e-08
+      },
+      {
+        "threshold": 0.001,
+        "nz": 0,
+        "r2": -514997980738.5937,
+        "mae": 0.050999999046325684
+      },
+      {
+        "threshold": 0.002,
+        "nz": 0,
+        "r2": -514997980738.5937,
+        "mae": 0.050999999046325684
+      },
+      {
+        "threshold": 0.005,
+        "nz": 0,
+        "r2": -514997980738.5937,
+        "mae": 0.050999999046325684
+      },
+      {
+        "threshold": 0.01,
+        "nz": 0,
+        "r2": -514997980738.5937,
+        "mae": 0.050999999046325684
+      },
+      {
+        "threshold": 0.015,
+        "nz": 0,
+        "r2": -514997980738.5937,
+        "mae": 0.050999999046325684
+      },
+      {
+        "threshold": 0.02,
+        "nz": 0,
+        "r2": -514997980738.5937,
+        "mae": 0.050999999046325684
+      },
+      {
+        "threshold": 0.03,
+        "nz": 0,
+        "r2": -514997980738.5937,
+        "mae": 0.050999999046325684
+      },
+      {
+        "threshold": 0.05,
+        "nz": 0,
+        "r2": -514997980738.5937,
+        "mae": 0.050999999046325684
+      },
+      {
+        "threshold": 0.1,
+        "nz": 0,
+        "r2": -514997980738.5937,
+        "mae": 0.050999999046325684
+      }
+    ],
+    "best": {
+      "threshold": 0.0,
+      "nz": 10,
+      "r2": 0.9583284280391652,
+      "mae": 1.15718787598632e-08
+    },
+    "best_coef": [
+      -9.472058267524708e-09,
+      0.0002241008167953442,
+      0.003224155981542969,
+      -7.459967868655183e-05,
+      -0.0002720854703143245,
+      1.1691407051761946e-10,
+      -9.171553339138634e-11,
+      6.477660414852548e-10,
+      5.860206010691412e-11,
+      0.0009623592127892139,
+      -0.05095243656815282,
+      0.0,
+      4.8247913174868025e-08,
+      -4.8247908281752745e-08,
+      0.0,
+      0.0,
+      0.0,
+      -1.8886475698738897e-10,
+      0.16119707097288422,
+      -0.013584418707664971,
+      4.12272941645026e-09,
+      2.9297936037658187e-09
+    ],
+    "sparsity_curve": [
+      [
+        0.0,
+        10,
+        0.9583284280391652
+      ],
+      [
+        0.001,
+        0,
+        -514997980738.5937
+      ],
+      [
+        0.002,
+        0,
+        -514997980738.5937
+      ],
+      [
+        0.005,
+        0,
+        -514997980738.5937
+      ],
+      [
+        0.01,
+        0,
+        -514997980738.5937
+      ],
+      [
+        0.015,
+        0,
+        -514997980738.5937
+      ],
+      [
+        0.02,
+        0,
+        -514997980738.5937
+      ],
+      [
+        0.03,
+        0,
+        -514997980738.5937
+      ],
+      [
+        0.05,
+        0,
+        -514997980738.5937
+      ],
+      [
+        0.1,
+        0,
+        -514997980738.5937
+      ]
+    ]
+  },
+  "scene_info": [
+    {
+      "re_code": 100,
+      "mu": 0.02,
+      "n_samples": 198
+    }
+  ]
+}

src/analysis_cloak/scenes/steady/sr/steady_sr_pareto.json

@@ -0,0 +1,46 @@
+{
+  "scene": "steady",
+  "channels": [
+    {
+      "channel": "front",
+      "best_r2": 1.0,
+      "best_nz": 0,
+      "pareto": [
+        {
+          "nz": 0,
+          "r2": 1.0
+        }
+      ]
+    },
+    {
+      "channel": "top",
+      "best_r2": 0.9583284280391652,
+      "best_nz": 10,
+      "pareto": [
+        {
+          "nz": 0,
+          "r2": -514997980738.5937
+        },
+        {
+          "nz": 10,
+          "r2": 0.9583284280391652
+        }
+      ]
+    },
+    {
+      "channel": "bottom",
+      "best_r2": 0.9583284280391652,
+      "best_nz": 10,
+      "pareto": [
+        {
+          "nz": 0,
+          "r2": -514997980738.5937
+        },
+        {
+          "nz": 10,
+          "r2": 0.9583284280391652
+        }
+      ]
+    }
+  ]
+}

src/analysis_crossre/analysis_notes.md

@@ -0,0 +1,405 @@
+当前这条线的目标，已经不再是“继续把 Kármán cloak 的跨 \(Re_D\) 拟合做得更精致”，而是：**把所有 cloak 任务纳入同一受约束分析框架，用 SINDy 与 SR 并行探索 shared backbone 的几种可能结构。** 这里的关键词不是“立刻统一”，而是“先分开拟合、横向比较、再判断共享到什么程度”。对 coder 来说，接下来最重要的不是继续沿着单一版本号推进，而是切换到**探索型工作流**。
+
+## 一句话总目标
+
+\[
+\boxed{
+\text{对所有 cloak 场景，在统一变量、统一对称规则、尽量时间尺度显式化的前提下，分别做 SINDy 与 SR，再比较公式、support 与闭环表现，从而识别 shared backbone、scene-specific activation 与 time-scale effects。}
+}
+\]
+
+## 现在已经比较确定的结论
+
+| 结论 | 当前状态 | 对后续工作的含义 |
+|---|---|---|
+| Kármán cloak 跨 \(Re_D\) 统一骨架存在 | 已确认 | 可作为第一批强证据，不必再单线深挖很久 |
+| 控制律满足镜像等变结构 | 已确认 | 所有 cloak 后续都应沿用这套 \(G\) 规则 |
+| front 不需要 bias | 已确认 | front 默认 odd 结构 |
+| rear shared-head 有价值 | 已确认 | rear 默认优先尝试共享头，而不是无约束独立 |
+| 无量纲化不是问题根源 | 已确认 | 变量统一应继续保留 |
+| 所有 cloak 是否共享同一骨架 | 未知 | 当前最核心的新问题 |
+| 采样周期是否掩盖了高 Re 或某些 cloak 的潜力 | 未知 | 要纳入时间尺度探索线，而不是忽略 |
+
+## 思路转变
+
+之前的工作方式更像：
+
+1. 选一个场景
+2. 试一个版本
+3. 比较 one-step 与闭环
+4. 再改下一个版本
+
+这个方式在“证明跨 Re 骨架存在”阶段是有效的，但接下来不够用了。现在需要转成：
+
+1. 先统一所有场景共享的变量与约束
+2. 每个场景分别做 SINDy 与 SR
+3. 输出可横向比较的结果包
+4. 再在比较结果上判断哪些是 backbone，哪些是场景特有项
+
+也就是说，**版本号思路要让位给实验矩阵思路**。
+
+## 后续要探索的几种结构可能
+
+后面的代码与结果组织，不应默认只有一种真相，而要明确服务于几种可能。
+
+### 可能性 A
+
+所有 cloak 共享同一个核心骨架，只是系数不同。
+
+### 可能性 B
+
+所有 cloak 共享同一批核心项，但不同场景会激活不同附加项。
+
+### 可能性 C
+
+表面上不同 cloak 的 support 不同，但经过时间尺度显式化后会明显收敛。
+
+### 可能性 D
+
+cloak family 不是单一骨架，而是分成若干子家族，例如 steady/Kármán 一类，单涡/erase 一类。
+
+后续计划必须让每种可能都能被检验，而不是在一开始就把工作锁死在某个预设答案上。
+
+## 新的执行总框架
+
+对 coder 来说，接下来最实用的组织方式是三条并行主线。
+
+| 线 | 目标 | 输出 |
+|---|---|---|
+| A. 统一表征线 | 统一变量、约束、时间尺度写法 | 所有场景共享的 feature builder |
+| B. 分场景拟合线 | 每个 cloak 分别做 SINDy 与 SR | 每个场景的 support、公式、闭环表现 |
+| C. 横向比较线 | 比较场景之间的共性与差异 | overlap 表、shared-backbone 假设检验 |
+
+注意：这三条线不是先后串行，而是 A 先到可用、B 尽快开始、C 随第一批结果启动。
+
+## 具体执行路线图
+
+## 阶段 0
+
+## 固定统一接口
+
+这一阶段的目标不是新结果，而是防止后面每个场景又各写一套特征逻辑。
+
+### 0.1 统一 primitive variables
+
+所有 cloak 场景统一输出以下 primitive variables：
+
+- 无量纲 sensor：\(\hat u, \hat v\)
+- 力系数：\(C_D, C_L\)
+- 无量纲控制：\(\alpha\)
+- lagged \(\alpha\)
+- action increment 或其时间尺度显式化版本
+- \(\mu=1/Re_D\)
+- 场景元数据：scene id、Re、control interval、target type
+
+### 0.2 固定正确的 \(G\) 算子
+
+所有场景都用同一套 \(G\) 规则：
+
+\[
+(\alpha_F,\alpha_T,\alpha_B) \mapsto (-\alpha_F,-\alpha_B,-\alpha_T)
+\]
+
+且其 lag、increment、sensor、force 的符号规则必须与此保持一致。coder 后续不能再为某个单独场景临时改 \(G\)。
+
+### 0.3 时间尺度先显式化，不急于一步到位
+
+当前不要求立刻找到最终完美的时间尺度写法，但要求先把离散 cadence 从“隐变量”变成“显变量”。最低要求：
+
+- 每个场景记录 control interval \(\Delta t_c\)
+- lag 与 \(\Delta a\) 的定义显式绑定 \(\Delta t_c\)
+- 后续比较不同场景、不同采样率时，不允许再把“1 个采样步”当成无条件可比的量
+
+### 0.4 统一 feature builder
+
+统一生成三类特征：
+
+| 层级 | 内容 | 用途 |
+|---|---|---|
+| core | 无量纲 sensor、\(C_D,C_L\)、\(\alpha^-\)、\(\Delta\alpha^-\)、\(\mu\) | 所有模型共用 |
+| derived | 对称/反对称组合、总量/差量 | SINDy 主库 |
+| time-scale | 显式含 \(\Delta t_c\) 的增量或导数近似 | 采样率影响分析 |
+
+这一阶段结束的标志不是拟合结果，而是：**所有 cloak 场景可以通过同一个 builder 产生可比较特征。**
+
+## 阶段 1
+
+## 所有 cloak 分开做第一轮 SINDy
+
+这一步是当前最先应该全面展开的。
+
+### 场景优先级
+
+建议按两层推进，不要求一次所有场景做到同等深度。
+
+#### 第一层重点场景
+
+- Kármán cloak
+- steady cloak
+
+这两个场景要做完整输出：
+
+- front odd + rear shared-head 约束 SINDy
+- one-step
+- 关键闭环
+- support 稳定性
+
+#### 第二层扩展场景
+
+- 单涡 cloak
+- erase
+- 其他已有 cloak
+
+这批先做轻量版：
+
+- 同一变量空间下的 separate fit
+- one-step
+- support 与公式形态
+- 必要时再补闭环
+
+### 每个场景必须输出什么
+
+每个场景第一轮 SINDy 结果，必须统一输出下面这些文件或表：
+
+| 输出 | 说明 |
+|---|---|
+| best support | 最优 support 列表 |
+| sparsity curve | 稀疏度-误差曲线 |
+| front / rear 主项表 | 各通道的主导项与系数 |
+| one-step metrics | R²、RMSE |
+| selected closed-loop metric | similarity 或等价指标 |
+| support stability | 对 threshold / window / bootstrap 的稳定性 |
+
+### 约束默认值
+
+除非某个场景明确被数据否定，否则第一轮都默认：
+
+- front no-bias
+- front odd structure
+- rear shared-head
+- correct \(G\) consistency
+
+也就是说，现在不再把“独立三通道”当默认，而是把“有结构约束”当默认。
+
+## 阶段 2
+
+## 所有 cloak 分开做第一轮 SR
+
+SR 现在与 SINDy 同步启动，但它的任务是“受限压缩”，不是自由乱搜。
+
+### SR 输入规则
+
+SR 只能使用：
+
+- 阶段 0 的统一变量
+- 阶段 1 的 SINDy 已筛出主项及其邻近项
+- 受限运算集合
+
+建议 SR 运算集合仍限制为：
+
+- 加减乘
+- protected divide
+- 少量 square
+- 如确有必要，再有限放开 tanh
+
+暂不允许：
+
+- raw trig 乱搜
+- 高次幂
+- 指数
+- 深层嵌套
+
+### 每个场景 SR 必须输出什么
+
+| 输出 | 说明 |
+|---|---|
+| shortest acceptable formula | 最短可接受公式 |
+| pareto front | 复杂度 vs 误差 |
+| 与 SINDy 支持集的关系 | 是否压缩、是否改写、是否合并了主项 |
+| 闭环表现 | 至少对最佳 SR 公式做一版关键闭环 |
+
+SR 的第一轮目标不是直接找到最终公式，而是回答：
+
+- 某些场景是否能被更短闭式描述
+- 某些场景之间是否出现同形公式
+- 某些 SINDy 重要项是否在 SR 中被统一吸收
+
+## 阶段 3
+
+## 横向比较与 shared-backbone 检验
+
+当第一批场景的 SINDy 和 SR 都有结果后，马上进入横向比较，不要等所有场景都做完才比较。
+
+### 3.1 support overlap 分析
+
+至少做下面三种 overlap：
+
+- Kármán vs steady
+- Kármán vs 单涡
+- steady vs 单涡
+
+比较结果建议分成三类：
+
+| 类别 | 含义 |
+|---|---|
+| shared core | 多数场景共同出现 |
+| scene-enhanced | 多场景可见，但某场景更强 |
+| scene-specific | 只在个别场景出现 |
+
+### 3.2 SR 公式形态比较
+
+不能只比 support，还要比公式结构。例如检查：
+
+- 是否都包含同类 force feedback 核心
+- 是否都包含同类 memory 核心
+- 是否只是在某些场景多出周期项或瞬态项
+
+### 3.3 shared-backbone 假设检验
+
+当横向比较有了第一批证据后，再分别检验：
+
+- steady 是否是 Kármán 的子模型
+- 单涡是否是 core + history augmentation
+- 是否存在所有 cloak 共用的最小 core
+- 是否更适合分成 2~3 个子家族
+
+注意：这一步才开始认真讨论“共享到什么程度”，不是一开始就联合拟合总公式。
+
+## 阶段 4
+
+## 时间尺度探索线
+
+这条线现在应并行启动，但不必抢在全部场景前面。
+
+### 当前目标
+
+不是立即得到采样率最终结论，而是先做两件事：
+
+1. 让现有特征显式包含 \(\Delta t_c\)
+2. 看显式化后，不同场景的 support 是否更收敛
+
+### 第一批测试建议
+
+先在最关键两个场景上做：
+
+- Kármán cloak
+- steady cloak
+
+对比：
+
+- 旧的 discrete lag / \(\Delta a\)
+- 显式带 \(\Delta t_c\) 的版本
+
+看：
+
+- support 是否变化
+- SR 公式是否更收敛
+- 不同采样率下是否更容易迁移
+
+这条线的定位是：**逐步把采样率实现方式从物理骨架里剥离出来。**
+
+## coder 现在最应该换掉的习惯
+
+下面几条是执行层面的明确要求。
+
+### 不再做的事
+
+- 不再只围绕 Kármán across Re 单线深挖
+- 不再把版本号升级当成主要组织方式
+- 不再只看 one-step 就判断某条线值不值得做
+- 不再在 raw feature 上做自由 SR
+
+### 接下来默认要做的事
+
+- 所有 cloak 进入同一 builder
+- 每个场景都做 separate SINDy + separate SR
+- 每个结果都输出 support、公式、闭环三类信息
+- 结果出来后立即做横向比较
+
+## 建议的文件与结果组织方式
+
+建议从“按版本存结果”改成“按场景 × 方法存结果”。
+
+### 建议目录
+
+```text
+analysis_cloak/
+  common/
+    feature_builder.py
+    symmetry.py
+    time_scale.py
+  scenes/
+    karman/
+      sindy/
+      sr/
+      closed_loop/
+    steady/
+      sindy/
+      sr/
+      closed_loop/
+    monopole/
+      sindy/
+      sr/
+      closed_loop/
+    erase/
+      sindy/
+      sr/
+      closed_loop/
+  comparisons/
+    support_overlap/
+    formula_shape/
+    shared_backbone_tests/
+```
+
+### 每个场景的统一结果表
+
+每个场景至少生成一张 summary 表，包含：
+
+| method | sparsity | one-step | closed-loop | key terms | notes |
+|---|---:|---:|---:|---|---|
+| SINDy |  |  |  |  |  |
+| SR |  |  |  |  |  |
+
+这样后面比较时不会再陷入“某个版本某次试验表现不错，但很难横向放一起看”的状态。
+
+## 最小可执行计划
+
+如果 coder 需要一个最小可执行版本，按下面顺序做即可。
+
+### 本轮必须完成
+
+1. 统一所有 cloak 的 feature builder
+2. 跑 Kármán 与 steady 的第一轮 separate SINDy
+3. 跑 Kármán 与 steady 的第一轮受限 SR
+4. 输出 Kármán vs steady 的 support overlap 与公式形态比较
+
+### 下一轮扩展
+
+5. 把单涡 cloak 纳入同样流程
+6. 对 lag / \(\Delta a\) 做 \(\Delta t_c\) 显式化版本
+7. 检查显式化前后 support 是否更收敛
+
+### 再下一轮
+
+8. 开始 shared-backbone hypothesis tests
+9. 决定是“统一骨架 + 场景调制”，还是“若干子家族骨架”
+10. 再决定是否需要拟联合总公式
+
+## 当前工作的直接收束
+
+因此，接下来给 coder 的总原则应明确改写为：
+
+\[
+\boxed{
+\text{当前阶段的重点不是继续优化某一个跨 Re 版本，而是切换到场景化探索：所有 cloak 先分开做 SINDy 与 SR，再横向比较 support、公式与闭环，从而判断 shared backbone 到底成立到什么程度。}
+}
+\]
+
+这意味着后续真正要回答的问题已经变成：
+
+- 哪些项是所有 cloak 的 shared core
+- 哪些项是 Kármán、steady、单涡等场景的激活差异
+- 时间尺度写法会不会改变这种比较结果
+- SR 能否把若干场景的公式压缩成更统一的形态
+
+只有这样，后面的统一控制律才不会停留在“跨 Re 的局部现象”，而会真正推进到你现在更关心的问题：**cloak family 的物理骨架到底是什么。**

src/analysis_crossre/configs/config_cuda.json

@@ -0,0 +1,9 @@
+{
+    "multi_gpu": false,
+    "gpu_connection": "NVLink",
+    "required_cuda_capability": "7.0",
+    "threads_per_block": 128,
+    "X_1U": 128,
+    "Y_1U": 32,
+    "Z_1U": 1
+}

src/analysis_crossre/configs/config_flowfield.json

@@ -0,0 +1,13 @@
+{
+    "data_type": "FP32",
+    "dimensionality": 2,
+    "lattice": 9,
+    "field_dim_in_U": [10, 16, 1],
+    "viscosity": 0.004,
+    "velocity": 0.01,
+    "boundary_conditions": {
+        "x": ["parabolic", "outflow"],
+        "y": ["noslip", "noslip"],
+        "z": ["none", "none"]
+    }
+}

src/analysis_crossre/scripts/cfg.py

@@ -0,0 +1,91 @@
+# analysis_crossre/scripts/cfg.py
+"""Configuration constants for the cross-Re Karman cloak analysis."""
+
+import os
+from typing import List, Dict, Tuple
+
+# -- Paths -------------------------------------------------------------------
+_PROJ_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+ANALYSIS_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+CONFIG_DIR = os.path.join(ANALYSIS_DIR, "configs")
+MODEL_DIR = os.path.join(_PROJ_ROOT, "models")
+OUTPUT_DIR = os.path.join(_PROJ_ROOT, "output", "analysis_crossre")
+LEGACY_CFD_DIR = os.path.join(_PROJ_ROOT, "LegacyCelerisLab")
+
+# -- GPU config --------------------------------------------------------------
+DEVICE_ID = 0        # default, override via --device flag
+
+# -- Legacy CFD config paths -------------------------------------------------
+CONFIG_CUDA = os.path.join(CONFIG_DIR, "config_cuda.json")
+CONFIG_FLOWFIELD_BASE = os.path.join(CONFIG_DIR, "config_flowfield.json")
+
+# -- Physics constants -------------------------------------------------------
+U0 = 0.01            # inlet velocity (lattice units)
+D_CYL = 20.0         # single cylinder diameter (lattice units)
+D_REF = 40.0         # reference length = 2 * D (used for code "Re")
+L0 = 20.0            # base length unit (lattice)
+
+# -- Geometry (Karman cloak standard, all in lattice units) ------------------
+# Legacy grid: 1280 x 512
+NX = 1280
+NY = 512
+CENTER_Y = (NY - 1) / 2.0
+
+# Disturbance cylinder
+DIST_CENTER = (10.0 * L0, CENTER_Y)   # (200, 255.5)
+DIST_RADIUS = L0                       # 20
+
+# Downstream sensors (at x = 40*L0)
+SENSOR_RADIUS = L0 / 4                 # 5
+SENSOR_CENTERS = [
+    (40.0 * L0, CENTER_Y + 2.0 * L0),   # sensor0 (top)
+    (40.0 * L0, CENTER_Y),             # sensor1 (mid)
+    (40.0 * L0, CENTER_Y - 2.0 * L0),   # sensor2 (bottom)
+]
+
+# Pinball cylinders
+PINBALL_RADIUS = L0 / 2                # 10
+FRONT_CENTER = (30.0 * L0, CENTER_Y)   # (600, 255.5)
+BOTTOM_CENTER = (31.3 * L0, CENTER_Y - 0.75 * L0)  # (626, 240.5)
+TOP_CENTER = (31.3 * L0, CENTER_Y + 0.75 * L0)     # (626, 270.5)
+
+# -- Sampling parameters ----------------------------------------------------
+SAMPLE_INTERVAL = 800
+FIFO_LEN = 150
+CONV_LEN = 30
+STABILIZE_STEPS = int(4 * NX / U0)
+
+# -- DRL parameters ----------------------------------------------------------
+S_DIM = 12    # sensor[6] + force[6]
+A_DIM = 3
+ACTION_SCALE = 8.0
+ACTION_BIAS = [0.0, -4.0, 4.0]    # front, bottom, top (multiply by U0 later)
+
+# -- Re definition ----------------------------------------------------------
+# "Re_code" uses reference length 2*D (D_REF = 40), matching model file naming.
+# The true physical Reynolds number is Re_D = Re_code / 2.
+#   Re_code=100 -> Re_D=50 (default case)
+def nu_from_re(re_code: float) -> float:
+    """Calculate kinematic viscosity from code Reynolds number."""
+    return U0 * D_REF / re_code
+
+# Re cases: (re_code, model_name)  -- None for validation cases with no model
+RE_CASES_TRAIN: List[Tuple[int, str]] = [
+    (50,  "d1a3o12_re50"),
+    (100, "d1a3o12_re100"),
+    (200, "d1a3o12_re200"),
+    (400, "d1a3o12_re400"),
+]
+
+RE_CASES_VALIDATION: List[int] = [35, 70, 150]
+ALL_RE_CODES: List[int] = [c[0] for c in RE_CASES_TRAIN] + RE_CASES_VALIDATION
+
+RE_LABEL_MAP: Dict[int, str] = {
+    50: "Re50 (Re_D=25)",
+    100: "Re100 (Re_D=50)",
+    200: "Re200 (Re_D=100)",
+    400: "Re400 (Re_D=200)",
+    35: "Re35 (Re_D=17.5)",
+    70: "Re70 (Re_D=35)",
+    150: "Re150 (Re_D=75)",
+}

src/analysis_crossre/scripts/phase1_infer.py

@@ -0,0 +1,329 @@
+# analysis_crossre/scripts/phase1_infer.py
+"""Phase 1: verify legacy-CFD + PPO inference across Karman cloak Re cases.
+
+Usage::
+
+    conda run -n pycuda_3_10 python phase1_infer.py \\
+        --re 100 --device 0
+
+    conda run -n pycuda_3_10 python phase1_infer.py \\
+        --re all --device 2
+
+Output for each Re case under ``output/analysis_crossre/re{re_code}/``:
+
+- ``config.json`` — runtime parameters
+- ``norm.json`` — normalisation factors
+- ``target.npz`` — target sensor signal (disturbance only, no pinball)
+- ``uncontrolled.npz`` — sensor / force / obs time series (zero-action)
+- ``controlled.npz`` — sensor / force / obs / action time series (PPO)
+- ``vorticity_uncontrolled.png`` — final-step vorticity, uncontrolled
+- ``vorticity_controlled.png`` — final-step vorticity, controlled
+- ``rewards.npz`` — step-by-step reward for controlled rollout
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+from collections import deque
+
+import numpy as np
+
+# Add workspace root so LegacyCelerisLab is importable
+_PROJ = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+if _PROJ not in sys.path:
+    sys.path.insert(0, _PROJ)
+
+from LegacyCelerisLab import FlowField  # noqa: E402
+
+from utils import (  # noqa: E402
+    nu_from_re,
+    load_legacy_configs,
+    build_karman_cloak_env,
+    add_pinball,
+    build_observation,
+    scale_action,
+    load_ppo_model,
+    save_vorticity_png,
+    vorticity_from_ddf,
+    compute_similarity,
+    ACTION_SMOOTH_WEIGHT,
+)
+from cfg import (  # noqa: E402
+    CONFIG_DIR,
+    CONFIG_CUDA,
+    CONFIG_FLOWFIELD_BASE,
+    OUTPUT_DIR,
+    MODEL_DIR,
+    SAMPLE_INTERVAL,
+    FIFO_LEN,
+    CONV_LEN,
+    S_DIM,
+    A_DIM,
+    ACTION_SCALE,
+    ACTION_BIAS,
+    U0,
+    STABILIZE_STEPS,
+    RE_CASES_TRAIN,
+    RE_CASES_VALIDATION,
+    RE_LABEL_MAP,
+)
+
+DATA_TYPE = np.float32
+
+
+def run_single_re(
+    re_code: int,
+    model_path: Optional[str],
+    device_id: int,
+    output_root: str,
+    *,
+    n_infer_steps: int = 200,
+) -> dict:
+    """Run full inference pipeline for one Re case.
+
+    Parameters
+    ----------
+    re_code : int
+        Code Reynolds number (reference length = 2D).
+    model_path : str or None
+        Path to PPO .zip file. None = only uncontrolled runs.
+    device_id : int
+        GPU device ID.
+    output_root : str
+        Root output directory for this case.
+    n_infer_steps : int
+        Number of inference steps (each = SAMPLE_INTERVAL LBM steps).
+
+    Returns summary dict with similarity scores etc.
+    """
+    os.makedirs(output_root, exist_ok=True)
+
+    # -- 0. Prepare config ---------------------------------------------------
+    nu = nu_from_re(re_code, u0=U0)
+    label = RE_LABEL_MAP.get(re_code, f"Re{re_code}")
+    print(f"\n{'='*60}")
+    print(f"Case: {label}   viscosity={nu:.6f}   device={device_id}")
+    print(f"{'='*60}")
+
+    # Save run config
+    with open(os.path.join(output_root, "config.json"), "w") as f:
+        json.dump({
+            "re_code": re_code,
+            "nu": nu,
+            "u0": U0,
+            "sample_interval": SAMPLE_INTERVAL,
+            "fifo_len": FIFO_LEN,
+            "conv_len": CONV_LEN,
+            "device_id": device_id,
+            "model_path": model_path,
+        }, f, indent=2)
+
+    # -- 1. Load legacy CFD configs, adjust viscosity ------------------------
+    cuda_cfg, field_cfg = load_legacy_configs(CONFIG_DIR)
+    # Override viscosity for this Re
+    field_cfg = field_cfg._replace(viscosity=float(nu))
+
+    # -- 2. Build flow field + dist + sensors, record target -----------------
+    ff = FlowField(field_cfg, cuda_cfg, device_id=device_id)
+    target_states, env_info = build_karman_cloak_env(
+        ff, u0=U0, l0=20.0, sample_interval=SAMPLE_INTERVAL,
+        fifo_len=FIFO_LEN, data_type=DATA_TYPE,
+    )
+    np.savez(os.path.join(output_root, "target.npz"),
+             target_states=target_states)
+
+    # -- 3. Add pinball, compute norm, bias rollout --------------------------
+    norm = add_pinball(
+        ff, l0=20.0, u0=U0, sample_interval=SAMPLE_INTERVAL,
+        fifo_len=FIFO_LEN, data_type=DATA_TYPE,
+        action_bias=ACTION_BIAS,
+    )
+    save_states = norm.pop("save_states", None)
+
+    # Save norm (without save_states which is a big array)
+    norm_for_json = {k: v for k, v in norm.items() if not isinstance(v, np.ndarray)}
+    with open(os.path.join(output_root, "norm.json"), "w") as f:
+        json.dump(norm_for_json, f, indent=2)
+    print(f"  norm saved to {output_root}/norm.json")
+
+    # -- 4. Uncontrolled rollout ---------------------------------------------
+    print("  uncontrolled rollout ...")
+    ff.restore_ddf()
+    ff.apply_ddf()
+    fifo = deque(maxlen=FIFO_LEN)
+    sens_list, forc_list, obs_list = [], [], []
+
+    for step in range(n_infer_steps):
+        ff.run(SAMPLE_INTERVAL, np.zeros(7, dtype=DATA_TYPE))
+        obs_slice = ff.obs.copy()[2:14]
+        fifo.append(obs_slice)
+        sens_list.append(obs_slice[0:6])
+        forc_list.append(obs_slice[6:12])
+        obs = build_observation(obs_slice, norm)
+        obs_list.append(obs)
+
+    np.savez(os.path.join(output_root, "uncontrolled.npz"),
+             sensors=np.array(sens_list, dtype=np.float32),
+             forces=np.array(forc_list, dtype=np.float32),
+             obs=np.array(obs_list, dtype=np.float32))
+
+    # Vorticity at final step
+    omega_unc = vorticity_from_ddf(ff, u0=U0)
+    save_vorticity_png(
+        os.path.join(output_root, "vorticity_uncontrolled.png"),
+        omega_unc,
+        title=f"{label} uncontrolled",
+    )
+    # Also save macro field snapshot
+    macro_unc = {"ux": [], "uy": [], "rho": []}  # placeholder; vorticity PNG is enough for Phase 1
+
+    # -- 5. Controlled rollout (if model available) --------------------------
+    result = {"re_code": re_code, "uncontrolled": True, "controlled": False}
+
+    if model_path is not None and os.path.isfile(model_path):
+        print(f"  loading model: {model_path}")
+        model = load_ppo_model(model_path, device=f"cuda:{device_id}")
+        model.set_random_seed(0)
+
+        print(f"  controlled rollout ({n_infer_steps} steps) ...")
+        ff.restore_ddf()
+        ff.apply_ddf()
+        # Re-bias the FIFO (as in env.__init__)
+        bias_action = scale_action(
+            np.array([0.0, 0.0, 0.0], dtype=np.float32),
+            scale=ACTION_SCALE, bias=ACTION_BIAS, u0=U0, n_total_bodies=7,
+        )
+        for i in range(FIFO_LEN):
+            ff.context.push()
+            try:
+                ff.run(SAMPLE_INTERVAL, bias_action)
+            finally:
+                ff.context.pop()
+            fifo.append(ff.obs.copy()[2:14])
+
+        sens_list_c, forc_list_c, obs_list_c = [], [], []
+        action_list_c, reward_list_c = [], []
+
+        obs = np.zeros(S_DIM, dtype=np.float32)
+
+        for step in range(n_infer_steps):
+            action, _states = model.predict(obs, deterministic=True)
+            action = action.astype(np.float32).flatten()
+            action_list_c.append(action.copy())
+
+            # Convert to legacy action array
+            action_arr = scale_action(
+                action, scale=ACTION_SCALE, bias=ACTION_BIAS,
+                u0=U0, n_total_bodies=7,
+            )
+
+            # Run CFD with proper context management (PyTorch shadows legacy ctx)
+            ff.context.push()
+            try:
+                ff.run(SAMPLE_INTERVAL, action_arr)
+            finally:
+                ff.context.pop()
+
+            obs_slice = ff.obs.copy()[2:14]
+            fifo.append(obs_slice)
+            sens_list_c.append(obs_slice[0:6])
+            forc_list_c.append(obs_slice[6:12])
+            obs = build_observation(obs_slice, norm)
+            obs_list_c.append(obs)
+
+            # Compute reward (matching env logic)
+            states_arr = np.array(list(fifo), dtype=np.float32)
+            if len(states_arr) >= CONV_LEN:
+                forces = states_arr[-1, 6:12] / norm["force_norm_fact"]
+                cd = float((forces[0] + forces[2] + forces[4]) / 3.0)
+                cl = float((forces[1] + forces[3] + forces[5]) / 3.0)
+                sim = compute_similarity(target_states, states_arr[:, 0:6], CONV_LEN)
+                r_cd = np.exp(-abs(cd * 20.0))
+                r_cl = np.exp(-abs(cl * 80.0))
+                r_sim = np.exp(-10.0 * abs(sim - 1.0))
+                reward = min(0.3 * r_cd + 0.4 * r_cl + 0.3 * r_sim, 1.0)
+                reward_list_c.append(float(reward))
+            else:
+                reward_list_c.append(0.0)
+
+        np.savez(os.path.join(output_root, "controlled.npz"),
+                 sensors=np.array(sens_list_c, dtype=np.float32),
+                 forces=np.array(forc_list_c, dtype=np.float32),
+                 obs=np.array(obs_list_c, dtype=np.float32),
+                 actions=np.array(action_list_c, dtype=np.float32),
+                 rewards=np.array(reward_list_c, dtype=np.float32))
+
+        # Vorticity at final controlled step
+        omega_con = vorticity_from_ddf(ff, u0=U0)
+        save_vorticity_png(
+            os.path.join(output_root, "vorticity_controlled.png"),
+            omega_con,
+            title=f"{label} controlled (PPO)",
+        )
+
+        avg_reward = float(np.mean(reward_list_c[-100:])) if len(reward_list_c) >= 100 else float(np.mean(reward_list_c))
+        sim_score = compute_similarity(
+            target_states, np.array(sens_list_c, dtype=np.float32), CONV_LEN
+        )
+        result["controlled"] = True
+        result["avg_reward_last100"] = avg_reward
+        result["similarity"] = sim_score
+        print(f"  avg_reward(last100)={avg_reward:.4f}  similarity={sim_score:.4f}")
+    else:
+        print(f"  no model for Re{re_code}, skipping controlled rollout")
+
+    # -- 6. Cleanup ----------------------------------------------------------
+    del ff
+
+    # Save result summary
+    with open(os.path.join(output_root, "result.json"), "w") as f:
+        json.dump(result, f, indent=2)
+
+    return result
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Phase 1: cross-Re Karman cloak inference")
+    ap.add_argument("--re", type=str, default="100",
+                    help='Re case: 50,100,200,400, or "all", or "validation"')
+    ap.add_argument("--device", type=int, default=0, help="GPU device ID")
+    ap.add_argument("--steps", type=int, default=200,
+                    help="Number of inference steps per rollout")
+    args = ap.parse_args()
+
+    # Select Re list
+    selection = args.re.lower()
+    if selection == "all":
+        re_list = [c[0] for c in RE_CASES_TRAIN]
+    elif selection == "validation":
+        re_list = RE_CASES_VALIDATION
+    else:
+        re_list = [int(selection)]
+
+    t_start = time.time()
+
+    for re_code in re_list:
+        # Find model path
+        model_path = None
+        for rc, mn in RE_CASES_TRAIN:
+            if rc == re_code:
+                model_path = os.path.join(MODEL_DIR, "old", f"{mn}.zip")
+                break
+
+        out_dir = os.path.join(OUTPUT_DIR, f"re{re_code}")
+        result = run_single_re(
+            re_code, model_path, args.device, out_dir,
+            n_infer_steps=args.steps,
+        )
+        print(f"  Done: re{re_code}  -> {out_dir}")
+
+    elapsed = time.time() - t_start
+    print(f"\nTotal time: {elapsed:.1f}s")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

src/analysis_crossre/scripts/utils.py

@@ -0,0 +1,851 @@
+# analysis_crossre/scripts/utils.py
+"""Shared utilities for the cross-Re Karman cloak analysis.
+
+All functions use the LegacyCelerisLab (old) CFD API via ``from LegacyCelerisLab import FlowField``.
+Must be run inside ``conda run -n pycuda_3_10``.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from collections import deque
+from typing import Any, Dict, List, Optional, Tuple
+
+import numpy as np
+
+# -- Import legacy CFD -------------------------------------------------------
+# LegacyCelerisLab lives at the repo root; analysis scripts are at
+# src/analysis_crossre/scripts/.  We need repo root on sys.path.
+_REPO = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+if _REPO not in sys.path:
+    sys.path.insert(0, _REPO)
+
+from LegacyCelerisLab import FlowField  # noqa: E402
+from LegacyCelerisLab import utils as legacy_utils  # noqa: E402
+
+# ---------------------------------------------------------------------------
+# Action-smoothing constant (legacy run() internal)
+# ---------------------------------------------------------------------------
+ACTION_SMOOTH_WEIGHT = 0.1  # used by FlowField.run() internally
+
+
+def nu_from_re(re_code: float, u0: float = 0.01, d_ref: float = 40.0) -> float:
+    """Return kinematic viscosity for a given code Reynolds number.
+
+    ``re_code`` uses reference length *2*D* = 40.0 (matching model file naming).
+    """
+    return u0 * d_ref / re_code
+
+
+def load_legacy_configs(config_dir: str) -> Tuple[Any, Any]:
+    """Load and return legacy (cuda_config, field_config) from *config_dir*."""
+    cuda_cfg = legacy_utils.load_cuda_config(
+        os.path.join(config_dir, "config_cuda.json")
+    )
+    field_cfg = legacy_utils.load_flow_field_config(
+        os.path.join(config_dir, "config_flowfield.json")
+    )
+    return cuda_cfg, field_cfg
+
+
+# ---------------------------------------------------------------------------
+# Environment helpers – follow env_karman_cloak_standard.py exactly
+# ---------------------------------------------------------------------------
+
+def build_karman_cloak_env(
+    flow_field: FlowField,
+    *,
+    u0: float,
+    l0: float,
+    sample_interval: int,
+    fifo_len: int,
+    data_type: type,
+) -> Tuple[np.ndarray, dict]:
+    """Phase 0-1: add dist-cylinder & 3 sensors, stabilize, record target.
+
+    Steps (mirrors env.__init__ lines 64-86):
+
+    1. add dist_cylinder (id=0)
+    2. add 3 sensors  (id=1,2,3)
+    3. stabilize run(4*NX/U0, zero-action[4])
+    4. record FIFO_LEN × run(SAMPLE_INTERVAL, zero[4]),  collect obs[2:8]
+
+    Returns
+    -------
+    target_states : ndarray (FIFO_LEN, 6)  — sensor0/1/2 ux,uy
+    info : dict with n_objects, NX, NY
+    """
+    n_objects_before = flow_field.flag.size  # not used, just a marker
+
+    # dist cylinder
+    center = (10.0 * l0, (flow_field.FIELD_SHAPE[1] - 1) / 2, 0.0)
+    flow_field.add_cylinder(center, l0)
+
+    # sensors
+    for y_off in [2.0, 0.0, -2.0]:
+        sc = (40.0 * l0, (flow_field.FIELD_SHAPE[1] - 1) / 2 + y_off * l0, 0.0)
+        flow_field.add_sensor(sc, l0 / 4.0)
+
+    n_obj = flow_field.obs.size // 2  # obs is (n_obj, DIM) flat
+    print(f"  bodies before pinball: {n_obj}")
+
+    # stabilize
+    stabilize_steps = int(4 * flow_field.FIELD_SHAPE[0] / u0)
+    print(f"  stabilising ({stabilize_steps} steps)...")
+    flow_field.run(stabilize_steps, np.zeros(n_obj, dtype=data_type))
+
+    # record target (only sensor signals = obs[2:8])
+    target_states = np.empty((0, 6), dtype=data_type)
+    for i in range(fifo_len):
+        flow_field.run(sample_interval, np.zeros(n_obj, dtype=data_type))
+        new_state = flow_field.obs.copy()[2:8]  # sensor0+1+2 velocities
+        target_states = np.vstack((target_states, new_state))
+
+    print(f"  target recorded: {target_states.shape}")
+    return target_states, {"n_objects": n_obj, "NX": flow_field.FIELD_SHAPE[0],
+                           "NY": flow_field.FIELD_SHAPE[1]}
+
+
+def add_pinball(
+    flow_field: FlowField,
+    *,
+    l0: float,
+    u0: float,
+    sample_interval: int,
+    fifo_len: int,
+    data_type: type,
+    action_bias: Optional[Tuple[float, float, float]] = None,
+) -> dict:
+    """Phase 2-3: add pinball cylinders, stabilize, compute norm, bias rollout.
+
+    Steps (mirrors env.__init__ lines 88-117):
+
+    1. add front, bottom, top cylinders (id=4,5,6)
+    2. stabilize run(4*NX/U0, zero-action[7])
+    3. get_ddf() + save_ddf()  (checkpoint of stabilised state)
+    4. FIFO_LEN × run(SAMPLE_INTERVAL, zero[7]) → compute norm
+    5. apply_ddf() (restore pre-bias state)
+    6. FIFO_LEN × run(SAMPLE_INTERVAL, bias-action[7]) → save_states
+    7. apply_ddf()
+
+    Returns dict with norm values.
+    """
+    if action_bias is None:
+        action_bias = (0.0, -4.0, 4.0)  # default cloak bias: front=0, bottom=-4U0, top=4U0
+
+    u0_float = float(u0)
+    n_obj_before = flow_field.obs.size // 2
+
+    # add 3 pinball cylinders
+    ny = flow_field.FIELD_SHAPE[1]
+    centers = [
+        (30.0 * l0, (ny - 1) / 2, 0.0),
+        (31.3 * l0, (ny - 1) / 2 + 0.75 * l0, 0.0),
+        (31.3 * l0, (ny - 1) / 2 - 0.75 * l0, 0.0),
+    ]
+    for c in centers:
+        flow_field.add_cylinder(c, l0 / 2.0)
+
+    n_obj = flow_field.obs.size // 2
+    print(f"  bodies after pinball: {n_obj}")
+
+    # stabilize
+    stabilize_steps = int(4 * flow_field.FIELD_SHAPE[0] / u0_float)
+    print(f"  stabilising pinball ({stabilize_steps} steps)...")
+    flow_field.run(stabilize_steps, np.zeros(n_obj, dtype=data_type))
+
+    # checkpoint DDF
+    flow_field.get_ddf()
+    flow_field.save_ddf()
+
+    # --- norm phase (zero-action) ---
+    fifo = deque(maxlen=fifo_len)
+    for i in range(fifo_len):
+        flow_field.run(sample_interval, np.zeros(n_obj, dtype=data_type))
+        fifo.append(flow_field.obs.copy()[2:14])  # sensor[6]+force[6]
+
+    temp_states = np.array(fifo, dtype=data_type)
+    force_norm_fact = 6.0 * float(np.max(np.abs(temp_states[:, 6:12])))
+    sens_deviation = np.mean(temp_states[:, 0:6], axis=0).astype(data_type)
+    sens_norm_fact = np.zeros(6, dtype=data_type)
+    for i in range(6):
+        sens_norm_fact[i] = 5.0 * float(np.max(np.abs(temp_states[:, i] - sens_deviation[i])))
+
+    print(f"  norm: force_norm_fact={force_norm_fact:.6f}")
+    print(f"  norm: sens_deviation={sens_deviation}")
+    print(f"  norm: sens_norm_fact={sens_norm_fact}")
+
+    # --- bias-action rollout ---
+    flow_field.apply_ddf()
+    bias = np.zeros(n_obj, dtype=data_type)
+    bias[n_obj - 3] = float(action_bias[0] * u0_float)       # front
+    bias[n_obj - 2] = float(action_bias[1] * u0_float)       # bottom
+    bias[n_obj - 1] = float(action_bias[2] * u0_float)       # top
+    print(f"  bias action: {bias}")
+
+    fifo.clear()
+    for i in range(fifo_len):
+        flow_field.run(sample_interval, bias)
+        fifo.append(flow_field.obs.copy()[2:14])
+
+    save_states = np.array(list(fifo), dtype=data_type)
+    flow_field.apply_ddf()
+
+    return {
+        "force_norm_fact": force_norm_fact,
+        "sens_deviation": sens_deviation.tolist(),
+        "sens_norm_fact": sens_norm_fact.tolist(),
+        "action_bias": list(action_bias),
+        "save_states": save_states,
+    }
+
+
+def build_observation(
+    obs_slice: np.ndarray,
+    norm: dict,
+) -> np.ndarray:
+    """Assemble normalised DRL observation (12-dim) from a single obs[2:14] slice.
+
+    ``obs_slice`` is 12-element: sensor[0:6] + force[6:12].
+
+    Returns clipped 12-dim array in [-1, 1].
+    """
+    forces = obs_slice[6:12] / norm["force_norm_fact"]
+    sens = (obs_slice[0:6] - norm["sens_deviation"]) / norm["sens_norm_fact"]
+    obs = np.clip(np.hstack([forces, sens]), -1.0, 1.0).astype(np.float32)
+    return obs
+
+
+def action_to_physical(
+    action_norm: np.ndarray,
+    *,
+    scale: float = 8.0,
+    bias: Tuple[float, float, float] = (0.0, -4.0, 4.0),
+    u0: float = 0.01,
+) -> np.ndarray:
+    """Convert normalized action [-1,1] to physical omega (lattice units).
+
+    physical_omega[i] = (action_norm[i] * scale + bias[i]) * u0
+    """
+    action_norm = np.asarray(action_norm, dtype=np.float64).reshape(-1, 3)
+    bias_arr = np.array(bias, dtype=np.float64)
+    return (action_norm * scale + bias_arr) * u0
+
+
+def scale_action(
+    action_norm: np.ndarray,
+    *,
+    scale: float = 8.0,
+    bias: Tuple[float, float, float] = (0.0, -4.0, 4.0),
+    u0: float = 0.01,
+    n_total_bodies: int = 7,
+) -> np.ndarray:
+    """Convert normalised action ([-1,1]^3) to legacy CFD action array.
+
+    Returns array of length *n_total_bodies* with cylinders' omegas at the
+    last 3 slots.
+    """
+    a = np.zeros(n_total_bodies, dtype=np.float32)
+    omega = (np.array(action_norm, dtype=np.float32) * scale + np.array(bias, dtype=np.float32)) * u0
+    a[n_total_bodies - 3:] = omega
+    return a
+
+
+# ---------------------------------------------------------------------------
+# Vorticity & field export
+# ---------------------------------------------------------------------------
+
+def vorticity_from_ddf(flow_field: FlowField, u0: float) -> np.ndarray:
+    """Compute z-vorticity from current DDF on host."""
+    flow_field.get_ddf()
+    ddf = flow_field.ddf.copy().reshape((9, flow_field.FIELD_SHAPE[1], flow_field.FIELD_SHAPE[0])).transpose(2, 1, 0)
+    ux = (ddf[:, :, 1] + ddf[:, :, 5] + ddf[:, :, 8] - ddf[:, :, 3] - ddf[:, :, 6] - ddf[:, :, 7]) / u0
+    uy = (ddf[:, :, 2] + ddf[:, :, 5] + ddf[:, :, 6] - ddf[:, :, 4] - ddf[:, :, 7] - ddf[:, :, 8]) / u0
+    # vorticity = dv/dx - du/dy
+    omega = np.gradient(uy, axis=1) - np.gradient(ux, axis=0)
+    return omega.astype(np.float64)
+
+
+def save_vorticity_png(path: str, omega: np.ndarray, title: str = ""):
+    """Save vorticity field as a PNG with symmetric colour bar."""
+    import matplotlib
+    matplotlib.use("Agg")
+    import matplotlib.pyplot as plt
+
+    abs_o = np.abs(omega[np.isfinite(omega)])
+    vmax = float(np.percentile(abs_o, 99.5)) if abs_o.size > 0 else 1.0
+    if vmax <= 0:
+        vmax = 1.0
+
+    ny, nx = omega.shape
+    fig, ax = plt.subplots(figsize=(min(18, max(8, nx / 60)), min(10, max(3, ny / 40))))
+    im = ax.imshow(omega, origin="lower", aspect="equal", cmap="RdBu_r",
+                   vmin=-vmax, vmax=vmax, extent=(0, nx - 1, 0, ny - 1))
+    ax.set_xlabel("x (lattice)")
+    ax.set_ylabel("y (lattice)")
+    if title:
+        ax.set_title(title)
+    fig.colorbar(im, ax=ax, fraction=0.046, pad=0.04, label=r"$\omega_z$")
+    fig.tight_layout()
+    fig.savefig(path, dpi=150, bbox_inches="tight")
+    plt.close(fig)
+
+
+# ---------------------------------------------------------------------------
+# DTW similarity
+# ---------------------------------------------------------------------------
+
+def calc_lag(target: np.ndarray, state: np.ndarray) -> int:
+    """Find lag that maximises cross-correlation between two 1-D signals."""
+    t = target - np.mean(target)
+    s = state - np.mean(state)
+    corr = np.correlate(t, s, mode="full")
+    lags = np.arange(-len(target) + 1, len(target))
+    return int(lags[np.argmax(corr)])
+
+
+def calc_dtw_sim(target: np.ndarray, state: np.ndarray) -> float:
+    """DTW-based similarity: 1 - (DTW distance / len(target)).
+
+    Both are 1-D arrays of possibly different lengths.
+    """
+    n, m = len(target), len(state)
+    dtw = np.full((n + 1, m + 1), np.inf)
+    dtw[0, 0] = 0.0
+    for i in range(1, n + 1):
+        for j in range(1, m + 1):
+            cost = abs(float(target[i - 1]) - float(state[j - 1]))
+            dtw[i, j] = cost + min(dtw[i - 1, j], dtw[i, j - 1], dtw[i - 1, j - 1])
+    return float(1.0 - dtw[n, m] / n)
+
+
+def compute_similarity(
+    target_states: np.ndarray,
+    state_series: np.ndarray,
+    conv_len: int,
+) -> float:
+    """Compute lag-compensated DTW similarity over *conv_len* window.
+
+    Matches the reward logic in env_karman_cloak_standard.step().
+    """
+    # lag from middle sensor
+    ref = target_states[conv_len:2 * conv_len, 1]
+    cur = state_series[-conv_len:, 1]
+    lag = calc_lag(ref, cur)
+
+    sim_sum = 0.0
+    for i in range(6):  # 6 sensor dimensions
+        target_seq = np.roll(target_states[:, i], -lag)[conv_len:2 * conv_len]
+        state_seq = state_series[-conv_len:, i]
+        sim_sum += calc_dtw_sim(target_seq, state_seq) / 6.0
+    return float(sim_sum)
+
+
+# ---------------------------------------------------------------------------
+# Dummy env for loading SB3 models
+# ---------------------------------------------------------------------------
+
+def create_dummy_env(s_dim: int = 12, a_dim: int = 3):
+    """Return a gym.Env with correct observation/action spaces for model loading."""
+    import gymnasium as gym
+    from gymnasium import spaces
+
+    class DummyEnv(gym.Env):
+        def __init__(self):
+            super().__init__()
+            self.observation_space = spaces.Box(low=-1, high=1, shape=(s_dim,), dtype=np.float32)
+            self.action_space = spaces.Box(low=-1, high=1, shape=(a_dim,), dtype=np.float32)
+
+        def reset(self, seed=None):
+            return np.zeros(s_dim, dtype=np.float32), {}
+
+        def step(self, action):
+            return np.zeros(s_dim, dtype=np.float32), 0.0, False, False, {}
+
+        def render(self): pass
+
+    return DummyEnv()
+
+
+def load_ppo_model(model_path: str, device: str = "cuda:0", s_dim: int = 12, a_dim: int = 3):
+    """Load a PPO model with Sin activation."""
+    import torch
+    from torch.nn import Module
+    from stable_baselines3 import PPO
+
+    class Sin(Module):
+        def forward(self, x):
+            return torch.sin(x)
+
+    dummy_env = create_dummy_env(s_dim, a_dim)
+    model = PPO.load(model_path, env=dummy_env, device=device)
+    return model
+
+
+# ---------------------------------------------------------------------------
+# SINDy feature library – all in physical units
+# ---------------------------------------------------------------------------
+
+def build_sindy_feature_library(
+    n_sensor: int = 6,
+    n_force: int = 6,
+) -> list:
+    """Return list of feature names for SINDy regression (for reference).
+
+    Features are built on-the-fly in ``build_sindy_features()``.
+    """
+    names = []
+    # bias
+    names.append("bias")
+    # raw sensor velocities (6 channels)
+    for i in range(n_sensor):
+        names.append(f"s{i}")
+    # raw forces (6 channels)
+    for i in range(n_force):
+        names.append(f"f{i}")
+    return names
+
+
+def build_sindy_features(
+    sensors: np.ndarray,    # (T, 6)  raw sensor velocities
+    forces: np.ndarray,     # (T, 6)  raw forces
+    actions_prev: np.ndarray,  # (T, 3)  previous-step physical omegas (ch0_lag1)
+    include_extra: bool = True,
+) -> np.ndarray:
+    """Construct feature matrix Theta(t) for SINDy.
+    
+    All quantities are in physical lattice units (not DRL-normalised).
+
+    Base library (always included):
+        bias(1), s0..s5, f0..f5
+
+    Extra features (if ``include_extra=True``, default):
+        sin(pi*s0), cos(pi*s0),     # phase info from middle sensor u
+        ds0..ds5,                    # forward difference of sensor signals
+        a0_lag1, a1_lag1, a2_lag1   # previous-step action (memory)
+
+    Returns
+    -------
+    Theta : (T, n_features) array
+    """
+    T = sensors.shape[0]
+    cols = []
+
+    # 1. bias
+    cols.append(np.ones(T, dtype=np.float64))
+
+    # 2. raw sensors (6)
+    for i in range(6):
+        cols.append(sensors[:, i].astype(np.float64))
+
+    # 3. raw forces (6)
+    for i in range(6):
+        cols.append(forces[:, i].astype(np.float64))
+
+    # 4. sin/cos of middle-sensor u-velocity (phase info)
+    s0 = sensors[:, 0].astype(np.float64)  # sensor0_ux
+    cols.append(np.sin(np.pi * s0))
+    cols.append(np.cos(np.pi * s0))
+
+    # 5. sensor differences
+    for i in range(6):
+        diff = np.diff(sensors[:, i].astype(np.float64), prepend=sensors[0, i])
+        cols.append(diff)
+
+    # 6. previous action (lag-1 memory)
+    cols.append(actions_prev[:, 0].astype(np.float64))  # ch0
+    cols.append(actions_prev[:, 1].astype(np.float64))  # ch1
+    cols.append(actions_prev[:, 2].astype(np.float64))  # ch2
+
+    Theta = np.column_stack(cols)
+    return Theta
+
+
+def get_sindy_feature_names(include_extra: bool = True) -> list:
+    """Return list of feature names matching ``build_sindy_features()`` output."""
+    names = ["bias"]
+    for i in range(6):
+        names.append(f"s{i}")
+    for i in range(6):
+        names.append(f"f{i}")
+    if include_extra:
+        names += ["sin_s0", "cos_s0"]
+        for i in range(6):
+            names.append(f"ds{i}")
+        names += ["a0_lag1", "a1_lag1", "a2_lag1"]
+    return names
+
+
+SINDY_DEFAULT_FEATURE_NAMES = get_sindy_feature_names(include_extra=True)
+
+
+def fit_channel(
+    Theta: np.ndarray,
+    y: np.ndarray,
+    thresholds: list,
+    alpha: float = 1e-4,
+    max_iter: int = 25,
+) -> tuple:
+    """Fit a single channel (one cylinder) with STLSQ threshold grid.
+
+    Returns
+    -------
+    rows : list of dict per threshold
+    best : dict with best threshold entry
+    """
+    import pysindy as ps
+
+    # Normalise features for thresholding stability
+    std = np.std(Theta, axis=0)
+    std = np.where(std < 1e-8, 1.0, std)
+    Theta_s = Theta / std
+
+    best = None
+    rows = []
+    for th in thresholds:
+        opt = ps.STLSQ(threshold=th, alpha=alpha, max_iter=max_iter)
+        opt.fit(Theta_s, y)
+        coef = np.asarray(opt.coef_, dtype=np.float64).flatten() / std
+        y_pred = Theta @ coef
+        ssr = float(np.sum((y - y_pred) ** 2))
+        sst = float(np.sum((y - np.mean(y)) ** 2) + 1e-12)
+        r2 = 1.0 - ssr / sst
+        mae = float(np.mean(np.abs(y - y_pred)))
+        nz = int(np.sum(np.abs(coef) > 1e-8))
+        entry = {"threshold": float(th), "nz": nz, "r2": r2, "mae": mae, "coef": coef}
+        rows.append(entry)
+        if best is None or r2 > best["r2"]:
+            best = entry
+    return rows, best
+
+
+def print_control_law(feature_names: list, coef: np.ndarray, channel_label: str = "ch"):
+    """Pretty-print a sparse control law."""
+    terms = []
+    for i, c in enumerate(coef):
+        if abs(c) > 1e-8:
+            terms.append(f"{c:.6f} * {feature_names[i]}")
+    print(f"  {channel_label}:  {' + '.join(terms)}")
+    nz = sum(1 for c in coef if abs(c) > 1e-8)
+    print(f"       non-zero terms: {nz}")
+
+
+# ---------------------------------------------------------------------------
+# Physics-guided feature library (v2 — replaces raw obs features)
+# ---------------------------------------------------------------------------
+
+def compute_physical_symbols(
+    sensors: np.ndarray,  # (T, 6)  [s0_ux, s0_uy, s1_ux, s1_uy, s2_ux, s2_uy]
+    forces: np.ndarray,   # (T, 6)  [cyl0_fx, cyl0_fy, cyl1_fx, cyl1_fy, cyl2_fx, cyl2_fy]
+    actions_prev: np.ndarray,  # (T, 3)  previous-step physical omega
+    actions_prev2: np.ndarray, # (T, 3)  omega(t-2), for delta terms
+) -> dict:
+    """Compute physics-guided symbols from raw CFD data.
+
+    Returns a dict of 1-D arrays (T,) keyed by symbol name.
+    """
+    T = sensors.shape[0]
+    s = sensors.astype(np.float64)
+    f = forces.astype(np.float64)
+    a_prev = np.asarray(actions_prev, dtype=np.float64)
+    a_prev2 = np.asarray(actions_prev2, dtype=np.float64)
+
+    # -- sensor symbols ----------------------------------------------------
+    # streamwise
+    u0, u1, u2 = s[:, 0], s[:, 2], s[:, 4]
+    # cross-stream
+    v0, v1, v2 = s[:, 1], s[:, 3], s[:, 5]
+
+    sym = {}
+
+    sym["u_m"] = (u0 + u1 + u2) / 3.0      # mean wake deficit
+    sym["u_a"] = (u2 - u0) / 2.0            # antisymmetric (vortex street)
+    sym["u_c"] = u1.copy()                   # centreline streamwise
+    sym["u_curv"] = u0 - 2.0 * u1 + u2      # transverse curvature
+
+    sym["v_m"] = (v0 + v1 + v2) / 3.0       # mean cross-stream
+    sym["v_a"] = (v2 - v0) / 2.0             # antisymmetric cross
+    sym["v_c"] = v1.copy()                   # centre cross
+    sym["v_curv"] = v0 - 2.0 * v1 + v2      # cross curvature
+
+    # vortex phase encoding (keep on u_a which captures asymmetry)
+    sym["sin_ua"] = np.sin(np.pi * sym["u_a"])
+    sym["cos_ua"] = np.cos(np.pi * sym["u_a"])
+
+    # -- force symbols -----------------------------------------------------
+    # cylinders: [front_fx, front_fy, bottom_fx, bottom_fy, top_fx, top_fy]
+    fx_front, fy_front = f[:, 0], f[:, 1]
+    fx_bot,   fy_bot   = f[:, 2], f[:, 3]
+    fx_top,   fy_top   = f[:, 4], f[:, 5]
+
+    sym["Fx_tot"]  = fx_front + fx_bot + fx_top
+    sym["Fx_rear"] = fx_bot + fx_top
+    sym["Fx_diff"] = fx_top - fx_bot
+
+    sym["Fy_tot"]  = fy_front + fy_bot + fy_top
+    sym["Fy_rear"] = fy_bot + fy_top
+    sym["Fy_diff"] = fy_top - fy_bot
+
+    # -- memory symbols ----------------------------------------------------
+    sym["a0_lag1"] = a_prev[:, 0]
+    sym["a1_lag1"] = a_prev[:, 1]
+    sym["a2_lag1"] = a_prev[:, 2]
+
+    sym["da0"] = a_prev[:, 0] - a_prev2[:, 0]
+    sym["da1"] = a_prev[:, 1] - a_prev2[:, 1]
+    sym["da2"] = a_prev[:, 2] - a_prev2[:, 2]
+
+    return sym
+
+
+# Which physical symbols to always include in the base library
+PHYSICAL_BASE_SYMBOLS = [
+    "bias",
+    "u_m", "u_a", "u_c",
+    "v_a",
+    "Fx_tot", "Fx_rear", "Fy_tot", "Fy_diff",
+    "sin_ua", "cos_ua",
+    "a0_lag1", "a1_lag1", "a2_lag1",
+    "da0", "da1", "da2",
+]
+
+# Which symbols get mu modulation
+PHYSICAL_MU_SYMBOLS = [
+    "u_a", "v_a", "Fx_tot", "Fy_diff", "Fy_tot",
+]
+
+
+def build_physical_features(
+    sensors: np.ndarray,
+    forces: np.ndarray,
+    actions_prev: np.ndarray,
+    actions_prev2: np.ndarray,
+    mu: float = 0.0,
+    include_mu: bool = True,
+) -> tuple:
+    """Construct physics-guided feature matrix.
+
+    Returns
+    -------
+    Theta : (T, n_feat) ndarray
+    names : list of feature names
+    """
+    sym = compute_physical_symbols(sensors, forces, actions_prev, actions_prev2)
+    T = sensors.shape[0]
+    cols = []
+    names = []
+
+    # 1. bias
+    cols.append(np.ones(T, dtype=np.float64))
+    names.append("bias")
+
+    # 2. base physical symbols
+    for key in PHYSICAL_BASE_SYMBOLS[1:]:  # skip "bias" since we already added it
+        if key in sym:
+            cols.append(sym[key])
+            names.append(key)
+
+    # 3. mu and mu-modulated terms
+    if include_mu and mu > 0:
+        cols.append(np.full(T, mu, dtype=np.float64))
+        names.append("mu")
+        for key in PHYSICAL_MU_SYMBOLS:
+            if key in sym:
+                cols.append(sym[key] * mu)
+                names.append(f"mu_{key}")
+
+    Theta = np.column_stack(cols)
+    return Theta, names
+
+
+def get_physical_feature_names(mu: float = 0.0, include_mu: bool = True) -> list:
+    """Return feature names matching ``build_physical_features()``."""
+    names = ["bias"] + PHYSICAL_BASE_SYMBOLS[1:]
+    if include_mu and mu > 0:
+        names.append("mu")
+        for key in PHYSICAL_MU_SYMBOLS:
+            names.append(f"mu_{key}")
+    return names
+
+
+# ---------------------------------------------------------------------------
+# Dimensionless conversion and G operator (v3)
+# ---------------------------------------------------------------------------
+
+def compute_dimensionless(
+    sensors: np.ndarray,  # (T, 6) raw lattice [s0_ux, s0_uy, s1_ux, s1_uy, s2_ux, s2_uy]
+    forces: np.ndarray,   # (T, 6) raw lattice [cyl0_fx, cyl0_fy, cyl1_fx, cyl1_fy, cyl2_fx, cyl2_fy]
+    u0: float = 0.01,
+    d: float = 20.0,
+    rho: float = 1.0,
+) -> dict:
+    """Convert raw lattice CFD data to dimensionless physical quantities.
+
+    Returns dict with keys:
+        u_hat_B, u_hat_C, u_hat_T : nondim streamwise velocity at 3 sensors
+        v_hat_B, v_hat_C, v_hat_T : nondim crosswise velocity
+        Cd_F, Cd_T, Cd_B          : drag coefficient per cylinder
+        Cl_F, Cl_T, Cl_B          : lift coefficient per cylinder
+    """
+    T = sensors.shape[0]
+    s = sensors.astype(np.float64)
+    f = forces.astype(np.float64)
+
+    # Sensor velocity ordering from legacy env: [sensor0_ux, sensor0_uy, sensor1_ux, sensor1_uy, sensor2_ux, sensor2_uy]
+    # Sensor positions: sensor0=top(y=+2L0), sensor1=mid(y=0), sensor2=bottom(y=-2L0)
+    # So top = sensor0 = s[:,0:2], mid = sensor1 = s[:,2:4], bottom = sensor2 = s[:,4:6]
+    # Per G-operator convention: B=bottom=sensor2, C=centre=sensor1, T=top=sensor0
+    u_hat_T = s[:, 0] / u0   # top
+    v_hat_T = s[:, 1] / u0
+    u_hat_C = s[:, 2] / u0   # centre
+    v_hat_C = s[:, 3] / u0
+    u_hat_B = s[:, 4] / u0   # bottom
+    v_hat_B = s[:, 5] / u0
+
+    # Force ordering: [front_fx, front_fy, bottom_fx, bottom_fy, top_fx, top_fy]
+    # front=cyl0, bottom=cyl1, top=cyl2
+    Cd_F = 2.0 * f[:, 0] / (rho * u0**2 * d)
+    Cl_F = 2.0 * f[:, 1] / (rho * u0**2 * d)
+    Cd_B = 2.0 * f[:, 2] / (rho * u0**2 * d)  # bottom
+    Cl_B = 2.0 * f[:, 3] / (rho * u0**2 * d)
+    Cd_T = 2.0 * f[:, 4] / (rho * u0**2 * d)  # top
+    Cl_T = 2.0 * f[:, 5] / (rho * u0**2 * d)
+
+    return {
+        "u_hat_B": u_hat_B, "u_hat_C": u_hat_C, "u_hat_T": u_hat_T,
+        "v_hat_B": v_hat_B, "v_hat_C": v_hat_C, "v_hat_T": v_hat_T,
+        "Cd_F": Cd_F, "Cd_T": Cd_T, "Cd_B": Cd_B,
+        "Cl_F": Cl_F, "Cl_T": Cl_T, "Cl_B": Cl_B,
+    }
+
+
+def apply_G_x(
+    u_hat_B: np.ndarray, u_hat_C: np.ndarray, u_hat_T: np.ndarray,
+    v_hat_B: np.ndarray, v_hat_C: np.ndarray, v_hat_T: np.ndarray,
+    Cd_F: np.ndarray, Cd_T: np.ndarray, Cd_B: np.ndarray,
+    Cl_F: np.ndarray, Cl_T: np.ndarray, Cl_B: np.ndarray,
+    aF_lag1: np.ndarray, aT_lag1: np.ndarray, aB_lag1: np.ndarray,
+    daF: np.ndarray, daT: np.ndarray, daB: np.ndarray,
+):
+    """Apply mirror operator G to input state.
+
+    CORRECTED: all rotation-related quantities (action, lag, delta)
+    change sign under mirror (y -> -y).
+
+    G flips y -> -y:
+    - u_x: reorder only (B<->T), no sign change
+    - v_y: reorder (B<->T) AND sign change
+    - Cd: no sign change, B<->T
+    - Cl: sign change, B<->T
+    - aF: sign change
+    - aT <-> aB (swap AND sign change on the swapped values)
+    - da: same as a
+
+    Returns dict with same keys as inputs, values are G-transformed.
+    """
+    return {
+        "u_hat_B": u_hat_T, "u_hat_C": u_hat_C, "u_hat_T": u_hat_B,
+        "v_hat_B": -v_hat_T, "v_hat_C": -v_hat_C, "v_hat_T": -v_hat_B,
+        "Cd_F": Cd_F, "Cd_T": Cd_B, "Cd_B": Cd_T,
+        "Cl_F": -Cl_F, "Cl_T": -Cl_B, "Cl_B": -Cl_T,
+        "aF_lag1": -aF_lag1, "aT_lag1": -aB_lag1, "aB_lag1": -aT_lag1,
+        "daF": -daF, "daT": -daB, "daB": -daT,
+    }
+
+
+def apply_G_alpha(alpha: np.ndarray) -> np.ndarray:
+    """Apply G to output action: [aF, aT, aB] -> [-aF, -aB, -aT]."""
+    return np.array([-alpha[0], -alpha[2], -alpha[1]], dtype=alpha.dtype)
+
+
+# ---------------------------------------------------------------------------
+# v3 physical symbols (dimensionless + equivariant-compatible)
+# ---------------------------------------------------------------------------
+
+def compute_v3_symbols(
+    dim: dict,          # from compute_dimensionless()
+    actions_prev: np.ndarray,   # (T, 3) physical omega(t-1)
+    actions_prev2: np.ndarray,  # (T, 3) physical omega(t-2)
+    mu: float,
+    include_mu: bool = True,
+) -> tuple:
+    """Compute v3 physics-guided symbols from dimensionless quantities.
+
+    Returns
+    -------
+    Theta_front : np.ndarray (T, n_feat_front) — no bias column
+    Theta_top   : np.ndarray (T, n_feat_top)   — with bias column
+    names       : list  (common feature names, first is "bias" for top)
+    """
+    T = actions_prev.shape[0]
+
+    # Sensor combinations (nondim)
+    u_B, u_C, u_T = dim["u_hat_B"], dim["u_hat_C"], dim["u_hat_T"]
+    v_B, v_C, v_T = dim["v_hat_B"], dim["v_hat_C"], dim["v_hat_T"]
+
+    u_m = (u_B + u_C + u_T) / 3.0
+    u_a = (u_T - u_B) / 2.0   # antisymmetric (T - B)
+    u_c = u_C.copy()
+    v_a = (v_T - v_B) / 2.0   # antisymmetric (T - B)
+
+    # Force combinations (dimensionless Cd/Cl)
+    Cd_F, Cd_T, Cd_B = dim["Cd_F"], dim["Cd_T"], dim["Cd_B"]
+    Cl_F, Cl_T, Cl_B = dim["Cl_F"], dim["Cl_T"], dim["Cl_B"]
+
+    Cd_tot = Cd_F + Cd_T + Cd_B
+    Cd_rear = Cd_T + Cd_B
+    Cl_tot = Cl_F + Cl_T + Cl_B
+    Cl_diff = Cl_T - Cl_B
+
+    # Phase
+    sin_ua = np.sin(np.pi * u_a)
+    cos_ua = np.cos(np.pi * u_a)
+
+    # Memory (all 3 cylinders now that we dropped exchange equivariance)
+    aF_lag1 = actions_prev[:, 0]
+    aB_lag1 = actions_prev[:, 1]
+    aT_lag1 = actions_prev[:, 2]
+    daF = actions_prev[:, 0] - actions_prev2[:, 0]
+    daB = actions_prev[:, 1] - actions_prev2[:, 1]
+    daT = actions_prev[:, 2] - actions_prev2[:, 2]
+
+    # Base features (common to all cylinders)
+    base_feats = {
+        "u_m": u_m, "u_a": u_a, "u_c": u_c, "v_a": v_a,
+        "Cd_tot": Cd_tot, "Cd_rear": Cd_rear,
+        "Cl_tot": Cl_tot, "Cl_diff": Cl_diff,
+        "sin_ua": sin_ua, "cos_ua": cos_ua,
+        "aF_lag1": aF_lag1, "aB_lag1": aB_lag1, "aT_lag1": aT_lag1,
+        "daF": daF, "daB": daB, "daT": daT,
+    }
+
+    # Build feature arrays
+    base_names = list(base_feats.keys())
+    cols_base = [base_feats[k] for k in base_names]
+
+    # Mu modulation
+    mu_names = []
+    if include_mu and mu > 0:
+        mu_feats = {
+            "mu": np.full(T, mu, dtype=np.float64),
+            "mu_u_a": u_a * mu,
+            "mu_v_a": v_a * mu,
+            "mu_Cd_tot": Cd_tot * mu,
+            "mu_Cl_diff": Cl_diff * mu,
+        }
+        mu_names = list(mu_feats.keys())
+        cols_mu = [mu_feats[k] for k in mu_names]
+    else:
+        cols_mu = []
+
+    # Front model: NO bias
+    Theta_front = np.column_stack(cols_base + cols_mu)
+
+    # Top model: WITH bias
+    cols_top = [np.ones(T, dtype=np.float64)] + cols_base + cols_mu
+
+    Theta_top = np.column_stack(cols_top)
+    names = ["bias"] + base_names + mu_names
+
+    return Theta_front, Theta_top, names

src/analysis_crossre/steady_cloak_plan.md

@@ -0,0 +1,121 @@
+# Steady Cloak Analysis Plan
+
+## Objective
+
+Extend the Karman cloak unified control framework to steady cloak, testing whether the same physical skeleton (features, symmetry, front no-bias, rear shared-head) applies across different cloak tasks.
+
+## Data Availability Check
+
+### Trained Models
+
+Looking at the models directory and legacy training scripts:
+
+| Model | Task | Status |
+|-------|------|--------|
+| d1a3o12_re50/re100/re200/re400 | Karman cloak | Phase 1 data exists |
+| d1a3o12_250326 | Karman cloak (Re100) | Same as re100 |
+| d1a3o12_250421_* | Reduced obs Karman | Different env |
+| d1a3o14_250525_imit_* | Illusion | Different task |
+| d1a3o12_250729_erase_* | Erase | Different task |
+
+**No dedicated steady cloak model found in models/.**
+
+The steady cloak results in the Confirmation report (Section 4.1) used the same d1a3o12_re100 architecture but trained from scratch with steady inflow target.
+
+### Key Differences: Steady vs Karman Cloak
+
+| Aspect | Karman Cloak | Steady Cloak |
+|--------|-------------|--------------|
+| Upstream disturbance | Cylinder (D=20) generating Karman vortex street | None (clean parabolic inflow) |
+| Target signal | 3-sensor time series of undisturbed vortex street | Constant mean inlet velocity |
+| Sensor output | Periodic (oscillating around mean) | Steady (near-constant) |
+| PPO model | Re50-400 series | Unknown model name |
+| Sample interval | 800 | Likely same |
+| Action bias | [0, -4U0, +4U0] | Likely [0, 0, 0] or different |
+
+### Feature Implications for Steady Cloak
+
+When target is steady inflow:
+- `u_a` (antisymmetric velocity) -> ~0 (symmetry at mean)
+- `v_a` -> ~0
+- `sin_ua`, `cos_ua` -> ~0 (no oscillation to encode)
+- `Fy_tot`, `Fy_diff` -> ~0 (no lift oscillation)
+- `Fx_tot`, `Fx_rear` -> non-zero (base drag)
+- Memory terms -> non-zero (action smoothing still needed)
+- Mu modulation -> applicable
+
+**Many sensor-side features vanish!** This means the steady cloak likely relies mainly on force feedback + memory, not sensor feedback. This is a critical structural difference.
+
+### Hypothesis
+
+If the shared cloak skeleton exists, then:
+1. The feature set for steady cloak should be a SUBSET of Karman cloak features
+2. Force feedback + memory terms should be present in both
+3. Sensor asymmetry terms (u_a, v_a, sin/cos) are Karman-specific
+4. Front no-bias and rear shared-head should still apply
+
+## Execution Steps
+
+### Step 1: Identify/Obtain Steady Cloak Model
+
+**Action**: Check if steady cloak model exists under a different name, or was trained as part of the d1a3o12_250326 series.
+
+**Look for**:
+- Legacy training scripts that train with steady target (no disturbance cylinder)
+- In `legacy_train/` check for any script that uses `env_karman_cloak_standard.py` or similar but without the disturbance cylinder
+
+### Step 2: Phase 1 Inference (Steady)
+
+If model found, run Phase 1 inference for steady cloak (similar to `phase1_infer.py` but with steady target):
+
+1. Build env WITHOUT disturbance cylinder
+2. Record target: clean parabolic inflow (constant sensor values)
+3. Add pinball
+4. Compute norm
+5. Run uncontrolled + controlled (PPO) rollout
+
+**If no model exists**: 
+- Option A: Train a steady cloak PPO from scratch (1-2 days GPU time)
+- Option B: Use the existing d1a3o12_re100 model with steady target - test if the Karman cloak model generalizes to steady inflow
+- Option C: Use open-loop control from the report (discovered constant rotation)
+
+Option B is fastest: test `d1a3o12_re100` with steady inflow, record performance. If similarity > 0.8, the model transfers.
+
+### Step 3: Feature Support Analysis
+
+Compare active features between steady and Karman cloak:
+
+1. Fit SINDy on steady cloak data with same feature library
+2. Compare support set (which features have non-zero coefficients)
+3. Check G equivariance (should still hold)
+4. Check front no-bias (should still hold)
+5. Test rear shared-head (v23 structure)
+
+### Step 4: Cross-task Unified Fit
+
+If supports overlap:
+1. Stack steady + Karman + (optionally) vortex data
+2. Fit unified model with task-modulated parameters
+3. Test in closed-loop
+
+## Resource Requirements
+
+| Step | Data needed | CFD inference | GPU time |
+|------|------------|---------------|----------|
+| 1 | None | No | ~0 |
+| 2 | Steady model | Yes (~200s/Re) | ~3min |
+| 3 | Steady rollout NPZ | No | ~0 |
+| 4 | All NPZ data | No | ~1min |
+
+## Risk Assessment
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|-----------|
+| No steady cloak model exists | HIGH | HIGH | Option B (transfer Karman model) |
+| Steady cloak uses different obs/action scaling | MEDIUM | MEDIUM | Check norm.json before fitting |
+| Sensor features vanish (u_a, v_a ~0) | CERTAIN | LOW | This is expected; force+memory should dominate |
+| G equivariance test fails for steady | LOW | MEDIUM | Steady flow is symmetric by construction |
+
+## Next Step
+
+Begin with Step 1: find the steady cloak model. Check `d1a3o12_250326.zip` and any other models. If none found, test `d1a3o12_re100.zip` on steady inflow as Option B.

src/config.py

@@ -1,125 +0,0 @@
-"""
-Configuration management for DynamisLab.
-
-Handles loading of CelerisLab configurations and project settings.
-"""
-
-import os
-import sys
-from pathlib import Path
-from typing import Optional, Tuple
-
-# Determine project root directory
-_current_file = Path(__file__).resolve()
-_project_root = _current_file.parent.parent.parent  # Go up to DynamisLabNew/
-
-# Configuration directory (relative to project root)
-CONFIG_DIR = _project_root / 'configs'
-
-# Output directories
-MODELS_DIR = _project_root / 'models'
-OUTPUT_DIR = _project_root / 'output'
-TENSORBOARD_DIR = _project_root / 'tensorboard'
-
-# Create output directories if they don't exist
-MODELS_DIR.mkdir(exist_ok=True)
-OUTPUT_DIR.mkdir(exist_ok=True)
-TENSORBOARD_DIR.mkdir(exist_ok=True)
-
-
-def setup_celeris_import() -> None:
-    """
-    Setup CelerisLab import path.
-    
-    Assumes CelerisLab is either:
-    1. Installed as a package (pip install CelerisLab)
-    2. Available as a git submodule in project root
-    3. Available via PYTHONPATH environment variable
-    """
-    try:
-        # Try to import CelerisLab (it might be installed)
-        import CelerisLab
-        return
-    except ImportError:
-        pass
-    
-    # Check for CelerisLab as submodule
-    celeris_submodule = _project_root / 'CelerisLab' / 'src'
-    if celeris_submodule.exists():
-        sys.path.insert(0, str(celeris_submodule))
-        return
-    
-    # If still not found, raise error with helpful message
-    raise ImportError(
-        "CelerisLab not found. Please either:\n"
-        "  1. Install it: pip install -e ../CelerisLab\n"
-        "  2. Add as git submodule: git submodule add <url> CelerisLab\n"
-        "  3. Set PYTHONPATH to include CelerisLab src directory"
-    )
-
-
-def load_celeris_configs(
-    cuda_config_path: Optional[str] = None,
-    field_config_path: Optional[str] = None
-) -> Tuple:
-    """
-    Load CelerisLab configurations.
-    
-    Args:
-        cuda_config_path: Optional path to CUDA config. If None, uses CONFIG_DIR.
-        field_config_path: Optional path to field config. If None, uses CONFIG_DIR.
-    
-    Returns:
-        Tuple of (config_cuda, config_field)
-    """
-    # Setup CelerisLab import
-    setup_celeris_import()
-    
-    from CelerisLab import utils
-    
-    # Set environment variable to point to our configs
-    os.environ['CELERISLAB_CONFIG_DIR'] = str(CONFIG_DIR)
-    
-    # Load configurations - CelerisLab will find them automatically
-    if cuda_config_path is None:
-        config_cuda = utils.load_cuda_config()
-    else:
-        config_cuda = utils.load_cuda_config(cuda_config_path)
-    
-    if field_config_path is None:
-        config_field = utils.load_flow_field_config()
-    else:
-        config_field = utils.load_flow_field_config(field_config_path)
-    
-    return config_cuda, config_field
-
-
-def get_model_path(model_name: str) -> Path:
-    """Get full path for a model file."""
-    return MODELS_DIR / f"{model_name}.zip"
-
-
-def get_tensorboard_logdir(run_name: str) -> Path:
-    """Get TensorBoard log directory for a run."""
-    logdir = TENSORBOARD_DIR / run_name
-    logdir.mkdir(exist_ok=True)
-    return logdir
-
-
-def get_output_path(filename: str) -> Path:
-    """Get full path for an output file."""
-    return OUTPUT_DIR / filename
-
-
-# Expose project paths for convenience
-__all__ = [
-    'CONFIG_DIR',
-    'MODELS_DIR',
-    'OUTPUT_DIR',
-    'TENSORBOARD_DIR',
-    'setup_celeris_import',
-    'load_celeris_configs',
-    'get_model_path',
-    'get_tensorboard_logdir',
-    'get_output_path',
-]

src/drl_pinball/__init__.py

@@ -0,0 +1 @@
+

src/drl_pinball/knowledge.md

@@ -0,0 +1,890 @@
+# DynamisLab Comprehensive Knowledge Document
+
+> **Project**: Active hydrodynamic cloaking and illusion using Deep Reinforcement Learning (DRL) on a fluidic pinball.
+> **Solver**: GPU-accelerated Lattice Boltzmann Method (LBM, D2Q9, MRT)
+> **DRL**: PPO with Sin activation, Stable-Baselines3
+
+---
+
+## 1. Grid Configuration
+
+### 1.1 Legacy Grid
+
+Two config files are multiplied to produce the actual lattice:
+
+| Config | Base (1U) | Multiplier (field_dim_in_U) | Result |
+|--------|-----------|----------------------------|--------|
+| `config_cuda.json` | X_1U=128, Y_1U=32, Z_1U=1 | — | — |
+| `config_flowfield.json` | — | field_dim_in_U=[10, 16, 1] | — |
+| **Actual grid** | — | — | **nx=1280, ny=512, nz=1** |
+
+`L0=20` is the base length unit. The "U" grid units (128, 32) are chosen to align with CUDA SM count on the GPU.
+
+### 1.2 New Grid (CelerisLab)
+
+| Config File | nx | ny | nz |
+|------------|----|----|-----|
+| `config_lbm_pinball.json` | 1280 | 512 | 1 |
+
+The new grid is **identical** to the legacy grid. `L0=20` remains the base length unit.
+
+### 1.3 Config File Locations
+
+- Legacy configs: `configs/legacy_configs/config_cuda.json`, `config_flowfield.json`
+- New config: `configs/config_lbm_pinball.json`
+- Body config: `configs/config_body.json`
+- Reference: `configs/CONFIG.md` (full config schema documentation)
+
+---
+
+## 2. Reynolds Number Definition
+
+**Critical**: The project uses two different Re definitions.
+
+| Symbol | Reference Length | Formula | Default Value |
+|--------|-----------------|---------|---------------|
+| Re_D (report/paper) | Single cylinder diameter D=20 | U0·D/ν | 0.01×20/0.004 = **50** |
+| Re (code) | 2×D = 40 | U0·(2D)/ν | 0.01×40/0.004 = **100** |
+
+**Key mappings**:
+
+- Confirmation report `Re_D = 50` ↔ code `Re=100`
+- Code `re100` models → physical `Re_D=50`
+- Code `re50` models → physical `Re_D=25`
+- Upstream disturbance cylinder (diameter = L0×1 = 20) → Re=U0×20/ν=50 (single diameter definition)
+
+### 2.1 Re via Viscosity
+
+| Code Name | Viscosity ν | Re (code, 2D ref) | Re_D (report) |
+|-----------|-------------|-------------------|---------------|
+| re50 | 0.008 | 50 | 25 |
+| re100 | 0.004 | 100 | 50 |
+| re200 | 0.002 | 200 | 100 |
+| re400 | 0.001 | 400 | 200 |
+
+Formula: `Re = U0 * ref_length / ν` where ref_length = 2D = 40 for code Re.
+
+---
+
+## 3. Boundary Conditions
+
+Both legacy and new simulations use the same boundary configuration:
+
+| Boundary | Condition | Details |
+|----------|-----------|---------|
+| Inlet (x=0) | **Parabolic profile**, Zou-He local scheme | u_x parabolic, u_y=0 |
+| Outlet (x=64D) | Convective / NEQ extrapolation | `neq_extrap` mode, backflow clamp enabled |
+| Top/Bottom walls (y=±12.8D) | **Bounce-back** (no-slip) | `y_wall_bc: "bounce_back"` |
+| Cylinder surfaces | Ghost-node interpolation with prescribed rotational velocity | u_wall = a·(-sinθ, cosθ)^T |
+
+**Note**: The `config_lbm_pinball.json` explicitly uses `y_wall_bc: "bounce_back"`, which is equivalent to the legacy no-slip walls. The validation config `run_kan99b` uses `free_slip`, so be careful to use the correct config.
+
+**Fixed parameters**:
+- U0 = 0.01 (inlet center velocity, lattice units)
+- ν = 0.004 (default for Re=100 code)
+- ρ = 1.0
+- Collision: MRT
+- Streaming: esopull
+- Data type: FP32
+
+---
+
+## 4. Complete Old-to-New API Conversion Table
+
+| Feature | Old API (FlowField, LegacyCelerisLab) | New API (Simulation, CelerisLab) |
+|---------|--------------------------------------|----------------------------------|
+| **Force reading** | `obs[i]` after `run()` = per-step average (internal ÷N) | `read_force(id)` = N-step cumulative sum; **must divide by N** |
+| **Sensor reading** | `obs[i]` after `run()` = per-step average (internal ÷N) | `read_sensor(id, normalize=True)` = raw sum ÷ cell_count; **must still divide by N** |
+| **Action setting** | `run(N, action_array)` — objects indexed by order in single array | `set_body(id, omega=value)` — each cylinder set separately |
+| **Action smoothing** | Built-in exponential smoothing (weight=0.1) | None — implement manual `ActionSmoother` if needed |
+| **Checkpoint/save** | `save_ddf()` / `restore_ddf()` / `apply_ddf()` (host memory) | `snapshot()` / `restore()` (memory) or `save_checkpoint(path)` / `load_checkpoint(path)` (HDF5) |
+| **Initialization** | Constructor `FlowField(config_field, config_cuda, device_id)` auto-initializes | `Simulation(config)` then call `initialize()` separately |
+| **Field output** | `save_field()` writes Tecplot `.dat` | `get_macroscopic()` returns numpy arrays |
+| **Object addition** | `add_cylinder()`, `add_sensor()` on FlowField | Objects defined in `config_body.json` or added before `initialize()` |
+| **Vortex addition** | `add_vortex(center, radius, strength, ...)` | Unknown — check API |
+| **Numeric error check** | `flow_field.has_numeric_error()`, `flow_field.last_error_flag` | Manual implementation needed |
+| **Context management** | `flow_field.context.push()` / `.pop()` | Stream management via API |
+
+### 4.1 Conversion Formulas
+
+```python
+# Old API (per-step average):
+flow_field.run(SAMPLE_INTERVAL, action_array)
+obs = flow_field.obs  # already per-step average
+
+# New API (must divide by N):
+sim.bodies.zero_force_segment_async(stream)
+sim.bodies.zero_sensor_segment_async(stream)
+sim.run(SAMPLE_INTERVAL)
+fx_per_step = sim.read_force(body_id)[0] / SAMPLE_INTERVAL
+fy_per_step = sim.read_force(body_id)[1] / SAMPLE_INTERVAL
+ux_per_step = sim.read_sensor(sensor_id)[0] / SAMPLE_INTERVAL
+uy_per_step = sim.read_sensor(sensor_id)[1] / SAMPLE_INTERVAL
+```
+
+---
+
+## 5. Per-Scene Geometry Map
+
+All coordinates in `L0=20` lattice units. Multiply by `L0` to get lattice coordinates unless otherwise noted.
+- `CENTER_Y = (NY-1)/2 = 255.5` (lattice units)
+- `NY = 512`, `NX = 1280`
+
+### 5.1 Karman Cloak / Erase / ReducedObs (Standard Pinball Layout)
+
+| Object | Position (L0 units) | Position (lattice) | Radius (L0) | Radius (lattice) |
+|--------|---------------------|--------------------|-------------|------------------|
+| Disturbance cylinder (upstream) | (10, CENTER_Y/L0, 0) | (200, 255.5, 0) | 1.0×L0 | 20 |
+| Sensors (3x) | x=40, y=CENTER_Y/L0 + [2, 0, -2] | x=800 | L0/4 | 5 |
+| Pinball front | (30, CENTER_Y/L0, 0) | (600, 255.5, 0) | L0/2 | 10 |
+| Pinball bottom | (31.3, CENTER_Y/L0 − 0.75, 0) | (626, 240.5, 0) | L0/2 | 10 |
+| Pinball top | (31.3, CENTER_Y/L0 + 0.75, 0) | (626, 270.5, 0) | L0/2 | 10 |
+
+**Object order in legacy API** (for cloak/erase/reduce_obs):
+1. sensor0 (top, y=CENTER_Y+2*L0)
+2. sensor1 (center, y=CENTER_Y)
+3. sensor2 (bottom, y=CENTER_Y-2*L0)
+4. dist_cylinder (upstream disturbance)
+5. pinball_front
+6. pinball_bottom
+7. pinball_top
+
+### 5.2 Illusion (Imit) Layout
+
+**Target cylinder (recorded separately)**:
+
+| Object | Position (L0 units) | Radius |
+|--------|---------------------|--------|
+| Target cylinder | (20, CENTER_Y/L0, 0) | [0.75, 1.0, 1.5]×L0 (varies) |
+| Sensors (3x) | x=30, y=CENTER_Y/L0 + [2, 0, -2] | L0/4 |
+
+**Pinball + sensors** (trained env):
+
+| Object | Position (L0 units) | Radius |
+|--------|---------------------|--------|
+| Sensors (3x) | x=30, y=CENTER_Y/L0 + [2, 0, -2] | L0/4 |
+| Pinball front | (19, CENTER_Y/L0, 0) | L0/2 |
+| Pinball bottom | (20.3, CENTER_Y/L0 + 0.75, 0) | L0/2 |
+| Pinball top | (20.3, CENTER_Y/L0 − 0.75, 0) | L0/2 |
+
+**Object order** (illusion, 6 objects — no disturbance cylinder):
+1. sensor0 (top, y=CENTER_Y+2*L0)
+2. sensor1 (center, y=CENTER_Y)
+3. sensor2 (bottom, y=CENTER_Y-2*L0)
+4. pinball_front
+5. pinball_bottom
+6. pinball_top
+
+Action array: `temp[3:6] = (action*8 + [0, -2, 2]) * U0`
+
+### 5.3 Vortex Layout
+
+**Target phase** (sensors + vortex, no pinball):
+
+| Object | Position (L0 units) | Radius |
+|--------|---------------------|--------|
+| Sensors (3x) | x=40, y=CENTER_Y/L0 + [2, 0, -2] | L0/4 |
+| Vortex | (10, CENTER_Y/L0, 0) | 2×L0 |
+
+**Pinball phase** (sensors + pinball + vortex):
+
+| Object | Position (L0 units) | Radius |
+|--------|---------------------|--------|
+| Sensors (3x) | x=40 | L0/4 |
+| Pinball front | (30, CENTER_Y/L0, 0) | L0/2 |
+| Pinball bottom | (31.3, CENTER_Y/L0 + 0.75, 0) | L0/2 |
+| Pinball top | (31.3, CENTER_Y/L0 − 0.75, 0) | L0/2 |
+| Vortex | (15, CENTER_Y/L0, 0) | 2×L0 |
+
+**Vortex types**:
+- **Lamb dipole**: strength=0.5×U0, type="lamb"
+- **Taylor monopole**: strength=0.03×U0, type="taylor"
+
+**MAX_STEPS = 150** (transient event — not infinite like other scenes)
+
+**Object order** (vortex, 6 objects — no disturbance cylinder):
+1. sensor0 (top)
+2. sensor1 (center)
+3. sensor2 (bottom)
+4. pinball_front
+5. pinball_bottom
+6. pinball_top
+
+Action array: `temp[3:6] = (action*4 + [0, -4, 4]) * U0`
+
+---
+
+## 6. Per-Scene Action Scaling
+
+Each scene maps the normalized DRL action (range [-1, 1]) to physical angular velocity ω (U0 multiples):
+
+| Scene | Formula (ω/U0) | Scale | Bias | Physical range [front, bottom, top] |
+|-------|---------------|-------|------|-------------------------------------|
+| **Cloak (Karman)** | `action×8 + [0, -4, 4]` | 8 | [0, -4, 4] | front: [-8,8], bottom: [-12,4], top: [-4,12] |
+| **Erase** | `action×8 + [0, -8, 8]` | 8 | [0, -8, 8] | front: [-8,8], bottom: [-16,0], top: [0,16] |
+| **Illusion (Imit)** | `action×8 + [0, -2, 2]` | 8 | [0, -2, 2] | front: [-8,8], bottom: [-10,6], top: [-6,10] |
+| **Vortex** | `action×4 + [0, -4, 4]` | 4 | [0, -4, 4] | front: [-4,4], bottom: [-8,0], top: [0,8] |
+
+**Final omega in lattice units**: Multiply the result by `U0=0.01`.
+
+**Example** (Cloak, action=[1, 1, 1]):
+```
+ω_front = (1*8 + 0) * 0.01 = 0.08
+ω_bottom = (1*8 + (-4)) * 0.01 = 0.04
+ω_top = (1*8 + 4) * 0.01 = 0.12
+```
+
+**Example** (Cloak, action=[0, 0, 0] — the bias actions):
+```
+ω_front = 0
+ω_bottom = -4 * 0.01 = -0.04
+ω_top = 4 * 0.01 = 0.04
+```
+
+### 6.1 Action Smoothing (Legacy Only)
+
+Legacy `FlowField.run()` has **built-in exponential smoothing**:
+```python
+action_pinned = (1 - weight) * action_pinned + weight * action_target
+# weight = 0.1
+```
+This means the actual applied ω smoothly transitions toward the target. The new API has **no built-in smoothing** — implement `ActionSmoother` manually if needed for numerical stability.
+
+---
+
+## 7. Norm Semantics
+
+The normalization values are computed during environment initialization and **must be identical during inference**. They are model-specific and cannot be reused across different scenarios.
+
+### 7.1 Norm Collection Procedure (Standard Pattern)
+
+```python
+# Phase 1: Zero-action rollout
+for i in range(FIFO_LEN):
+    flow_field.run(SAMPLE_INTERVAL, zero_action)  # 4 or 7 objects depending on phase
+    fifo_states.append(flow_field.obs[sensor_select])  # e.g. [2:14] skips dist_cyl
+
+# Phase 2: Compute normalization factors
+temp_states = np.array(fifo_states)  # shape: (FIFO_LEN, N_sensors+N_forces)
+
+force_norm_fact = 6 * max(|forces|)           # forces = temp_states[:, 6:12]
+for i in range(6):
+    sens_deviation[i] = mean(sensor_i)         # sensor_i = temp_states[:, i]
+    sens_norm_fact[i] = 5 * max(|sensor_i - mean|)
+
+# Phase 3: Bias-action rollout (for FIFO initialization)
+flow_field.apply_ddf()  # restore checkpoint
+for i in range(FIFO_LEN):
+    flow_field.run(SAMPLE_INTERVAL, bias_action)
+    fifo_states.append(...)
+save_states = fifo_states.copy()
+```
+
+### 7.2 Norm Format
+
+```python
+norm = {
+    "force_norm_fact": float,         # scalar = 6 * max(|forces|)
+    "sens_deviation": [6 floats],     # mean per sensor channel
+    "sens_norm_fact": [6 floats],     # 5 * max(|sensor - deviation|) per channel
+    "save_states": ndarray,           # FIFO_LEN × N_obs array after bias rollout
+    "action_bias": [b_front, b_bottom, b_top],  # e.g. [0.0, -4.0, 4.0]
+    "n_obj_total": int                # total objects in flow field
+}
+```
+
+### 7.3 Scene-Specific Norm Variations
+
+| Scene | force_norm_fact formula | sens_norm_fact factor | Obs slice (from fifo) |
+|-------|------------------------|----------------------|----------------------|
+| Cloak (standard) | `6 * max(\|forces\|)` | 5 | `obs[2:14]` (skip 2 dist_cyl sensor channels) |
+| Erase | `100 * max(\|forces\|)` | 10 | `obs[0:14]` (full 14, incl. dist force) |
+| Illusion | `6 * max(\|forces\|)` | 5 | `obs[0:12]` (full 12) |
+| Vortex | `6 * max(\|forces\|)` | 5 | `obs[0:12]` (full 12) |
+| ReducedObs | `10 * max(\|forces\|)` | 5 | `obs[2:14]` |
+
+### 7.4 Observation Normalization (per step)
+
+```python
+# cloak/standard:
+forces = obs_slice[6:12] / force_norm_fact
+sens = (obs_slice[0:6] - sens_deviation) / sens_norm_fact
+observation = clip(hstack([forces, sens]), -1, 1)
+
+# erase:
+forces = obs_slice[6:14] / force_norm_fact  # Note: 8 force values (includes dist_cylinder)
+# But only forces[2:8] (pinball forces) are used in observation
+sens = (obs_slice[0:6] - sens_deviation) / sens_norm_fact
+```
+
+### 7.5 L0 Units vs Lattice Coordinates
+
+Multiple sources define positions in L0 units; multiply by L0=20 to get lattice (pixel) coordinates.
+
+| Description | L0 units | Lattice (pixels) |
+|-------------|----------|-------------------|
+| Grid size | — | 1280 × 512 |
+| Center Y (CENTER_Y) | — | (512-1)/2 = 255.5 |
+| Disturbance cylinder x | 10×L0 → 10 | 200 |
+| Sensor x (cloak/erase/vortex/reduce) | 40×L0 → 40 | 800 |
+| Sensor x (illusion) | 30×L0 → 30 | 600 |
+| Pinball front x (cloak/erase/vortex/reduce) | 30×L0 | 600 |
+| Pinball front x (illusion) | 19×L0 | 380 |
+| Pinball bottom/top x (cloak/erase/vortex/reduce) | 31.3×L0 | 626 |
+| Pinball bottom/top x (illusion) | 20.3×L0 | 406 |
+| Pinball radius (all) | L0/2 | 10 |
+| Sensor radius (all) | L0/4 | 5 |
+| Disturbance cylinder radius (cloak/erase) | L0 | 20 |
+| Vortex radius | 2×L0 | 40 |
+| Target cylinder radius (illusion) | [0.75, 1.0, 1.5]×L0 | [15, 20, 30] |
+
+---
+
+## 8. Per-Scene Running Parameters
+
+| Parameter | Cloak | Erase | Illusion | Vortex | ReducedObs |
+|-----------|-------|-------|----------|--------|------------|
+| S_DIM | 12 | 12 | 14 | 12 | varies (3→2) |
+| A_DIM | 3 | 3 | 3 | 3 | 3 |
+| SAMPLE_INTERVAL | 800 | 600 | varies | 800 | 800 |
+| FIFO_LEN | 150 | 150 | 150 | 150 | 150 |
+| CONV_LEN | 30 | 36 | 36 | 30 | 36 |
+| MAX_STEPS | 500 | 500 | 500 | **150** | 500 |
+| T0 | 1000 | 1000 | 1000 | 1000 | 1000 |
+| Objects in env | 7 | 7 | 6 | 6 | 7 |
+| Has disturbance cyl | Yes | Yes | No | No | Yes |
+| DRL training initial model | — (scratch) | `d1a3o12_250326_erase` | — (scratch) | `d1a3o12_re100` | — (scratch) |
+
+### 8.1 Reward Functions
+
+**Cloak (Karman)**:
+```python
+reward_cd = exp(-|cd * 20|)       # cd = (Σforces_fx) / 3
+reward_cl = exp(-|cl * 80|)       # cl = (Σforces_fy) / 3
+reward_sim = exp(-10 * |sim - 1|) # sim = DTW-based similarity
+reward = min(0.3*reward_cd + 0.4*reward_cl + 0.3*reward_sim, 1.0)
+```
+
+**Erase**:
+```python
+# Target = clean inflow mean (steady), not the noisy vortex street
+reward_u = exp(-|diff_u * 40|)    # diff of current vs target sensor u
+reward_v = 0.7*exp(-|amp_v*20|) + 0.3*exp(-|diff_v*20|)
+reward_sim = similarities         # raw DTW similarity (not exponentiated)
+reward = min(0.4*reward_u + 0.4*reward_v + 0.2*reward_sim, 1.0)
+```
+
+**Illusion**:
+```python
+# Target forces from harmonics reconstruction of target cylinder
+reward_cd = exp(-|(cd - cd_target) * 10|)
+reward_cl = exp(-|(cl - cl_target) * 10|)
+reward_sim = exp(-10 * |sim - 1|)
+reward = min(0.3*reward_cd + 0.3*reward_cl + 0.4*reward_sim, 1.0)
+```
+
+**Vortex**:
+```python
+reward_cd = exp(-|cd * 20|)
+reward_cl = exp(-|cl * 80|)
+reward_sim = exp(-10 * |sim - 1|)
+reward = min(0.2*reward_cd + 0.3*reward_cl + 0.5*reward_sim, 1.0)
+```
+
+---
+
+## 9. Old API Obs Layout
+
+### 9.1 Cloak (Karman) / Standard Env — 7 Objects
+
+Object addition order:
+1. Disturbance cylinder (id=0)
+2. Sensor0 / top (id=1)
+3. Sensor1 / center (id=2)
+4. Sensor2 / bottom (id=3)
+5. Pinball front (id=4)
+6. Pinball bottom (id=5)
+7. Pinball top (id=6)
+
+**`flow_field.obs` array** (14 values = 7 objects × 2):
+```
+obs[0:2]   = dist_cylinder force (fx, fy)     — ignored in training
+obs[2:4]   = sensor0 velocity (ux, uy)
+obs[4:6]   = sensor1 velocity (ux, uy)
+obs[6:8]   = sensor2 velocity (ux, uy)
+obs[8:10]  = front_pinball force (fx, fy)
+obs[10:12] = bottom_pinball force (fx, fy)
+obs[12:14] = top_pinball force (fx, fy)
+```
+
+**Normalized observation** (after `obs[2:14]` slice):
+```
+obs_norm[0:6]   = sensor0_ux, sensor0_uy, sensor1_ux, sensor1_uy, sensor2_ux, sensor2_uy
+obs_norm[6:12]  = front_fx, front_fy, bottom_fx, bottom_fy, top_fx, top_fy
+```
+
+**Action array** (7 entries, n_objects=7):
+```
+temp[0:4] = 0 (sensors + dist_cylinder — ignored)
+temp[4]   = front omega
+temp[5]   = bottom omega
+temp[6]   = top omega
+```
+
+### 9.2 Erase Env — 7 Objects
+
+Same addition order as Cloak (disturbance cylinder radius=0.75*L0 instead of 1.0*L0).
+
+**`flow_field.obs` array** (14 values):
+```
+obs[0:2]   = dist_cylinder force (fx, fy)
+obs[2:4]   = sensor0 velocity (ux, uy)
+obs[4:6]   = sensor1 velocity (ux, uy)
+obs[6:8]   = sensor2 velocity (ux, uy)
+obs[8:10]  = front_pinball force (fx, fy)
+obs[10:12] = bottom_pinball force (fx, fy)
+obs[12:14] = top_pinball force (fx, fy)
+```
+
+**Normalized observation** (full `obs[0:14]` slice — include dist_cylinder forces):
+```
+forces = obs[6:14] / force_norm_fact    # 8 force values
+# But only forces[2:8] (pinball) used in step()
+sens = (obs[0:6] - sens_deviation) / sens_norm_fact
+```
+
+**Target recording** uses `obs[0:6]` (sensor only, no dist cylinder force), since erase has **no disturbance cylinder during target phase**.
+
+### 9.3 Illusion (Imit) Env — 6 Objects
+
+Object addition order (sensors first, then pinball):
+1. Sensor0 / top (id=0)
+2. Sensor1 / center (id=1)
+3. Sensor2 / bottom (id=2)
+4. Pinball front (id=3)
+5. Pinball bottom (id=4)
+6. Pinball top (id=5)
+
+**`flow_field.obs` array** (12 values):
+```
+obs[0:2]   = sensor0 velocity (ux, uy)
+obs[2:4]   = sensor1 velocity (ux, uy)
+obs[4:6]   = sensor2 velocity (ux, uy)
+obs[6:8]   = front_pinball force (fx, fy)
+obs[8:10]  = bottom_pinball force (fx, fy)
+obs[10:12] = top_pinball force (fx, fy)
+```
+
+**Normalized observation** (full `obs[0:12]`):
+```
+forces = obs[6:12] / force_norm_fact
+sens = (obs[0:6] - sens_deviation) / sens_norm_fact
+obs_norm = hstack([forces, sens])  # 12 values
+# Plus 2 additional: target_cd, target_cl → total 14 (S_DIM=14)
+```
+
+**Action array** (6 entries):
+```
+temp[0:3] = 0 (sensors — ignored)
+temp[3]   = front omega
+temp[4]   = bottom omega
+temp[5]   = top omega
+```
+
+**Target recording** uses `obs[0:8]` (3 sensor × 2 + 1 cylinder × 2 = 8 values from target cylinder + 3 sensors).
+
+### 9.4 Vortex Env — 6 Objects
+
+Same object order as Illusion (sensors + pinball, no disturbance cylinder).
+
+Same obs layout as Illusion (12 values, obs[0:12] used as-is).
+
+**Target recording**: In the target phase, `obs` has 3 sensors only (6 values, `obs[0:6]`).
+
+### 9.5 ReducedObs Env — 7 Objects
+
+Same geometry and object order as Karman Cloak (7 objects: dist_cyl + 3 sensors + 3 pinball).
+
+**Obs slice**: `obs[2:14]` (same as Cloak, skipping dist_cylinder forces).
+
+**Additional torque observation**: Some reduced-obs models also compute torque:
+```python
+obs_torque = (-obs[1] - obs[2]*√3/2 + obs[3]/2 + obs[4]*√3/2 + obs[5]/2) / torque_norm_fact
+```
+
+The observation layout varies by model name suffix:
+| Model name | S_DIM | Observation components |
+|-----------|-------|----------------------|
+| `forces02` | 3 | `[obs_torque, dist_fx, dist_fy]` (?) |
+| `total_force` | 3 | Total force components |
+| `torque+forces02` | 5 | torque + dist forces |
+| `torque+forces02+sens24` | 9 | torque + dist forces + sensors 2,4 |
+| `torque+forces04+sens04` | 5 | torque + forces + sensors |
+
+See `legacy_env_reduce_obs.py` line 191 for exact obs composition.
+
+---
+
+## 10. Complete Model Inventory
+
+All model `.zip` files are PPO policies with Sin activation and 64×64 hidden layers.
+
+### 10.1 `models/old/` — Original Training (Cloak, Various Re)
+
+| File | Env | S_DIM | A_DIM | Action Scale/Bias | Sample Interval | Re (code) | Description |
+|------|-----|-------|-------|-------------------|-----------------|-----------|-------------|
+| `d1a3o12_re50.zip` | Cloak | 12 | 3 | 8 / [0,-4,4] | 800 | 50 | Cloak at lower Re; base model |
+| `d1a3o12_re100.zip` | Cloak | 12 | 3 | 8 / [0,-4,4] | 800 | 100 | Cloak at Re=100 (ν=0.004); **most used base model** |
+| `d1a3o12_re200.zip` | Cloak | 12 | 3 | 8 / [0,-4,4] | 800 | 200 | Cloak at higher Re |
+| `d1a3o12_re400.zip` | Cloak | 12 | 3 | 8 / [0,-4,4] | 800 | 400 | Cloak at highest Re |
+| `vortex_lamb.zip` | Vortex | 12 | 3 | 4 / [0,-4,4] | 800 | 100 | Cloak of Lamb dipole vortex; **transfer** from re100 |
+| `vortex_taylor.zip` | Vortex | 12 | 3 | 4 / [0,-4,4] | 800 | 100 | Cloak of Taylor monopole vortex; **transfer** from re100 |
+
+**Naming convention** `d1a3o12`:
+- `d1` = 1 disturbance cylinder
+- `a3` = 3 actuators (pinball cylinders)
+- `o12` = 12 observations
+- `o14` = 14 observations (used for illusion, includes target forces)
+
+### 10.2 `models/250326/` — Re-trained Cloak
+
+| File | Env | S_DIM | A_DIM | Scale/Bias | Desc |
+|------|-----|-------|-------|------------|------|
+| `d1a3o12_250326.zip` | Cloak | 12 | 3 | 8 / [0,-4,4] | Re-trained from scratch; equivalent to re100 |
+
+### 10.3 `models/250329/` — No-offset Cloak
+
+| File | Env | S_DIM | A_DIM | Scale/Bias | Desc |
+|------|-----|-------|-------|------------|------|
+| `d0a3o12_250329_nooffset.zip` | Cloak | 12 | 3 | 8 / [0,0,0] | Disturbance-cylinder-free (d0), zero bias actions |
+
+### 10.4 `models/250421/` — Reduced Observation
+
+| File | Env | S_DIM | A_DIM | Scale/Bias | Desc |
+|------|-----|-------|-------|------------|------|
+| `d1a3o12_250421_forces02.zip` | ReducedObs | 3 | 3 | 8 / [0,-4,4] | Obs reduced to 3 values |
+| `d1a3o12_250421_torque+forces02.zip` | ReducedObs | 5 | 3 | 8 / [0,-4,4] | Torque + 2 force values |
+| `d1a3o12_250421_torque+forces02+sens24.zip` | ReducedObs | 9 | 3 | 8 / [0,-4,4] | Torque + forces + sensors |
+| `d1a3o12_250421_torque+forces04+sens04.zip` | ReducedObs | 5 | 3 | 8 / [0,-4,4] | Modified obs composition |
+| `d1a3o12_250421_torque+total_force.zip` | ReducedObs | 5 | 3 | 8 / [0,-4,4] | Torque + total force |
+| `d1a3o12_250421_total_force.zip` | ReducedObs | 3 | 3 | 8 / [0,-4,4] | Only total force |
+
+All trained from scratch (no transfer). Obs reduction experiments for experimental hardware simplification.
+
+### 10.5 `models/250525/` — Illusion (Imit)
+
+| File | Env | S_DIM | A_DIM | Scale/Bias | Target | Sample Interval |
+|------|-----|-------|-------|------------|--------|-----------------|
+| `d1a3o12_250525_imit_075L_1U.zip` | Illusion | 14 | 3 | 8 / [0,-2,2] | 0.75L cylinder, U0=0.01 | 600 |
+| `d1a3o12_250525_imit_1L_1U.zip` | Illusion | 14 | 3 | 8 / [0,-2,2] | 1.0L cylinder, U0=0.01 | 600 |
+| `d1a3o12_250525_imit_1L_1U_trans.zip` | Illusion | 14 | 3 | 8 / [0,-2,2] | 1.0L cylinder, U0=0.01 | 600 (transfer) |
+| `d1a3o14_250525_imit_075L_2U.zip` | Illusion | 14 | 3 | 8 / [0,-2,2] | 0.75L cylinder, 2×U0 | 600 |
+| `d1a3o14_250525_imit_075L_2U_1.zip` | Illusion | 14 | 3 | 8 / [0,-2,2] | 0.75L cylinder | ~600 |
+| `d1a3o14_250525_imit_075L_2U_400S.zip` | Illusion | 14 | 3 | 8 / [0,-2,2] | 0.75L cylinder | 400 |
+| `d1a3o14_250525_imit_15L_2U.zip` | Illusion | 14 | 3 | 8 / [0,-2,2] | 1.5L cylinder, 2×U0 | 600 |
+| `d1a3o14_250525_imit_1L_2U.zip` | Illusion | 14 | 3 | 8 / [0,-2,2] | 1.0L cylinder, 2×U0 | 600 |
+| `d1a3o14_250525_imit_1L_2U_1.zip` | Illusion | 14 | 3 | 8 / [0,-2,2] | 1.0L cylinder | ~600 |
+| `d1a3o14_250525_imit_1L_2U_400S_02Vis.zip` | Illusion | 14 | 3 | 8 / [0,-2,2] | 1.0L cylinder | 400 |
+| `d1a3o14_250525_imit_1L_2U_600S.zip` | Illusion | 14 | 3 | 8 / [0,-2,2] | 1.0L cylinder | 600 |
+| `d1a3o14_250525_imit_1L_2U_800S_08Vis.zip` | Illusion | 14 | 3 | 8 / [0,-2,2] | 1.0L cylinder | 800 |
+| `d1a3o14_250525_imit_1L_2U_1000S_08Vis.zip` | Illusion | 14 | 3 | 8 / [0,-2,2] | 1.0L cylinder | 1000 |
+
+**Naming conventions**:
+- `075L` = target cylinder diameter = 0.75×L0
+- `1L` = target cylinder diameter = 1.0×L0
+- `15L` = target cylinder diameter = 1.5×L0
+- `1U` = U0=0.01 (standard), `2U` = 2×U0=0.02
+- `400S` etc. = SAMPLE_INTERVAL
+- `02Vis` etc. = ν (viscosity) multiplier (e.g. 0.08×ν)
+- `trans` = transfer learning model
+- `_1` suffix = variant
+
+### 10.6 `models/250729/` — Erase & Re-cloak
+
+| File | Env | S_DIM | A_DIM | Scale/Bias | Base Model | Desc |
+|------|-----|-------|-------|------------|------------|------|
+| `d1a3o12_250729_250326_cloak_800S_02Vis.zip` | Cloak | 12 | 3 | 8 / [0,-4,4] | `d1a3o12_250326` | Re-cloak, 02×ν |
+| `d1a3o12_250729_250326_erase.zip` | Erase | 12 | 3 | 8 / [0,-8,8] | `d1a3o12_250326` | Erase, transfer from cloak |
+| `d1a3o12_250729_250326_erase_250804_20D_retrain2.zip` | Erase | 12 | 3 | 8 / [0,-8,8] | `erase` | Erase retrain, 20D delay |
+| `d1a3o12_250729_250326_erase_250804_20D_retrain3.zip` | Erase | 12 | 3 | 8 / [0,-8,8] | `erase` | Erase retrain v3 |
+
+Erase models: SAMPLE_INTERVAL=600, CONV_LEN=36 (vs 800/30 for cloak).
+
+---
+
+## 11. DRL Hyperparameters
+
+| Parameter | Value |
+|-----------|-------|
+| Algorithm | PPO (Stable-Baselines3 `PPO`) |
+| Policy network | `MlpPolicy` |
+| Hidden layers | 64 × 64 (both actor and critic) |
+| Activation function | **Sin** (custom `torch.nn.Module`) |
+| Optimizer | Adam |
+| Learning rate (actor) | 3×10⁻⁴ |
+| Learning rate (critic) | 4×10⁻⁴ |
+| Episode length | 600 T₀ (T₀ = D/U₀ = 2000 LBM steps) |
+| Action interval | 0.8 T₀ (one action per 0.8 flow-through times) |
+| Training timesteps/iteration | 360-400 (varies by scene) |
+| Total episodes | ~500 (varies; vortex uses ~100) |
+| Device | CUDA GPU (device_id varies) |
+| Deterministic inference | Yes (`use_deterministic=True`) |
+
+### 11.1 Custom Sin Activation
+
+```python
+class Sin(Module):
+    def __init__(self):
+        super().__init__()
+    def forward(self, x):
+        return torch.sin(x)
+```
+
+Used in place of Tanh/ReLU because trigonometric functions better preserve spectral fidelity for vortex-dominated flows. Networks are:
+
+```
+Input(s_t) → Linear(64) → Sin → Linear(64) → Sin → Linear(n_actions) → Output(a_t)
+```
+
+### 11.2 Time Scales
+
+| Quantity | LBM steps | Description |
+|----------|-----------|-------------|
+| T₀ = D/U₀ | 20/0.01 = 2000 | One flow-through time (single cylinder diameter) |
+| SAMPLE_INTERVAL | 600-800 | Steps between DRL actions |
+| Action interval | 0.8 T₀ | SAMPLE_INTERVAL / T₀ = 800/2000 = 0.4 ... actually 800/2000=0.4 |
+| Episode length | 600 T₀ = 1.2M steps | Total episode duration |
+
+**Correction**: The paper says "actuations per T₀ = 1.25" and "action interval = 0.8 T₀". This means SAMPLE_INTERVAL = 0.8×2000 = 1600 LBM steps? But the code says SAMPLE_INTERVAL=800. This is a discrepancy — note that the paper uses T₀ = D/U₀ and SAMPLE_INTERVAL=800, which gives 800/2000 = 0.4 T₀ = 2.5 actuations per T₀. The paper may use a different T₀ definition, or the hyperparameter table may be aspirational vs actual.
+
+---
+
+## 12. Target Signal & Illusion Harmonics
+
+### 12.1 Karman Cloak Target
+
+Recorded from: 1 disturbance cylinder + 3 sensors (no pinball).
+- 150 steps × SAMPLE_INTERVAL = 800 steps
+- `obs[2:8]` → 6 sensor channels stored
+- Stored in `target_states` (150, 6)
+
+### 12.2 Erase Target
+
+Recorded from: 3 sensors only (no disturbance cylinder).
+- 150 steps × SAMPLE_INTERVAL = 600 steps
+- `obs[0:6]` → 6 sensor channels stored
+- No periodic signal → target is mean only (clean inflow)
+
+### 12.3 Illusion Target + Harmonics
+
+Recorded from: 1 target cylinder + 3 sensors (no pinball).
+- 150 steps × SAMPLE_INTERVAL (varies)
+- `obs[0:8]` → 3 sensor (6) + 1 cylinder force (2) = 8 channels stored
+- **Harmonics analysis**: FFT over target_states extracts DC + top 5 frequency harmonics per channel
+- Stored as `target_harmonics`: list of dicts with `{dc, amps, freqs, phases}` per channel (8 channels total)
+- During training, target forces are reconstructed via `gen_target_states_at(step, harmonics)`
+
+### 12.4 Vortex Target
+
+Recorded from: 3 sensors + Lamb dipole or Taylor monopole (no pinball).
+- 150 steps × SAMPLE_INTERVAL = 800 steps
+- `obs[0:6]` → 6 sensor channels stored
+- Vortex is transient: target_states contains the evolving vortex signal
+
+---
+
+## 13. Training Strategies
+
+### 13.1 Training Loop Pattern (All Scenes)
+
+```python
+for i in range(total_episodes):           # 100-500
+    model.learn(total_timesteps=K)        # K = 360-1500
+    test_env = model.get_env()
+    test_obs = test_env.reset()
+    for step in range(eval_steps):        # 150-360
+        test_action, _ = model.predict(test_obs)
+        test_obs, reward, done, info = test_env.step(test_action)
+        list_reward.append(reward)
+    avg_reward = mean(list_reward[-tail:]) # last 100-180 steps
+    # Save if best
+    if avg_reward > max_reward:
+        model.save(...)
+```
+
+### 13.2 Transfer Learning
+
+| Source Model | Target Model | Method |
+|-------------|-------------|--------|
+| `d1a3o12_re100` (Cloak) | `vortex_lamb`, `vortex_taylor` | Transfer: loaded as base, retrained on vortex env |
+| `d1a3o12_250326` (Cloak) | Erase models | Transfer: loaded as base, retrained on erase env |
+| Erase base | Erase retrain models | Transfer: loaded from previously trained erase |
+| `d1a3o12_250525_imit_1L_2U_600S` | `..._1000S_08Vis` etc. | Transfer: varied SAMPLE_INTERVAL/viscosity |
+
+Base models are loaded via `PPO.load(path, env=new_env, device=...)` and then fine-tuned.
+
+### 13.3 Checkpoint & Reset Mechanism
+
+```python
+# During __init__:
+flow_field.run(...)                                   # stabilize
+flow_field.get_ddf()                                  # host ← GPU
+flow_field.save_ddf()                                 # save to host memory
+
+# During reset/restore:
+flow_field.restore_ddf()                              # restore from host memory
+flow_field.apply_ddf()                                # host → GPU
+```
+
+The restored state includes the stable pinball wake (with vortex for vortex scenes). The FIFO is re-initialized from `save_states`.
+
+---
+
+## 14. File Structure Reference
+
+```
+DynamisLab/
+├── configs/
+│   ├── config_lbm_pinball.json         # NEW LBM config (nx=1280, ny=512)
+│   ├── config_body.json                # Body/object definitions
+│   ├── CONFIG.md                       # Config schema documentation
+│   └── legacy_configs/
+│       ├── config_cuda.json            # Legacy CUDA config (X_1U=128, etc.)
+│       ├── config_flowfield.json       # Legacy flow field config
+│       └── config_gym.json             # Legacy gym config
+├── models/
+│   ├── old/                            # Original re100/re200/re400/re50 + vortex
+│   ├── 250326/                         # Re-trained cloak
+│   ├── 250329/                         # No-offset cloak
+│   ├── 250421/                         # Reduced observation
+│   ├── 250525/                         # Illusion (imit)
+│   └── 250729/                         # Erase + re-cloak
+├── src/
+│   ├── drl_pinball/
+│   │   ├── knowledge.md               ← THIS FILE
+│   │   ├── legacy_env/                 # Old-API environment classes
+│   │   │   ├── legacy_env_karman_cloak_standard.py
+│   │   │   ├── legacy_env_erase.py
+│   │   │   ├── legacy_env_imit.py
+│   │   │   ├── legacy_env_imit_target.py
+│   │   │   ├── legacy_env_vortex.py
+│   │   │   ├── legacy_env_reduce_obs.py
+│   │   │   └── legacy_karman_env.py    # Reference implementation (re100)
+│   │   ├── legacy_train/               # Training scripts
+│   │   │   ├── karman_cloak.py
+│   │   │   ├── erase.py
+│   │   │   ├── imit.py
+│   │   │   ├── vortex.py
+│   │   │   └── reduce_obs.py
+│   │   └── legacy_test/                # Test/evaluation scripts
+│   ├── analysis_crossre/               # Cross-Re analysis (SINDy, etc.)
+│   └── CelerisLab/ or LegacyCelerisLab/  # Solver libraries
+├── docs/
+│   ├── understanding_notes.md          # Earlier knowledge consolidation
+│   └── My_Confirmation/Chapters/       # LaTeX thesis chapters
+├── LegacyCelerisLab/                   # Old solver library
+└── output/                             # Field output, .pkl files
+```
+
+---
+
+## 15. Key Numerical Values Quick Reference
+
+| Quantity | Value | Notes |
+|----------|-------|-------|
+| NX | 1280 | Grid x-dimension |
+| NY | 512 | Grid y-dimension |
+| L0 | 20 | Base length unit (lattice) |
+| U0 | 0.01 | Centerline inlet velocity (lattice) |
+| ν (default) | 0.004 | Kinematic viscosity → Re=100 (code) |
+| T₀ = D/U₀ | 2000 | Flow-through time (single cylinder diameter) |
+| Reynolds (code) | Re = U0·(2D)/ν | Uses 2D reference |
+| Reynolds (report) | Re_D = U0·D/ν | Uses 1D reference |
+| SAMPLE_INTERVAL | 600-800 | Steps between DRL actions |
+| FIFO_LEN | 150 | History buffer length |
+| Action scale | 4 or 8 | Scene-dependent |
+| Action bias | varies | Scene-dependent |
+| Omega guard | [0.01, 1.99] | From config_lbm_pinball.json |
+
+### 15.1 Physics-to-Lattice Unit Relations
+
+```
+D (cylinder diameter) = 20 lattice units = 1.0 in L0 units
+Single cylinder Re: Re_D = U0 × D / ν = 0.01 × 20 / 0.004 = 50
+Code Re: Re_code = U0 × 2D / ν = 0.01 × 40 / 0.004 = 100
+```
+
+---
+
+## 16. Important Implementation Notes
+
+### 16.1 Obs Slice Differences
+
+The sensor indices in `obs` are **not** consistent across envs:
+- **Cloak/standard**: uses `obs[2:14]` — skips first 2 values (disturbance cylinder forces)
+- **Erase**: uses `obs[0:14]` — includes all values (disturbance cylinder forces are part of observation)
+- **Illusion/Vortex**: uses `obs[0:12]` — sensors(6) + pinball forces(6)
+
+### 16.2 Center Y Computation
+
+```python
+CENTER_Y = (NY - 1) / 2.0  # = 255.5 for NY=512
+```
+
+This is because NY is even (512), so center is between two lattice rows.
+
+### 16.3 Force Norm Factors
+
+These are scene-specific constants that must NOT be shared between scenes:
+
+| Scene | force_norm_fact | sens_norm_fact factor |
+|-------|----------------|----------------------|
+| Cloak/standard | `6 * max(|forces|)` | 5 |
+| Erase | `100 * max(|forces|)` | 10 |
+| Illusion | `6 * max(|forces|)` | 5 |
+| Vortex | `6 * max(|forces|)` | 5 |
+| ReducedObs | `10 * max(|forces|)` | 5 |
+
+### 16.4 Vortex Scene Termination
+
+The vortex env is the only scene with **bounded episodes**:
+- `MAX_STEPS = 150` (vs 500 for all other scenes)
+- `done = self.current_step >= MAX_STEPS`
+- This is because the vortex is a transient event that passes through the domain
+
+### 16.5 Experimental Setup (from thesis)
+
+- Water tunnel with towing platform (25cm width)
+- Custom force sensor integrating air bearing + 2D force sensor (semiconductor strain gauges)
+- Custom low-noise, high-precision data acquisition system
+- Planar PIV for flow field measurement
+- Current challenges: sensor noise from over-constraint/welding; rail manufacturing precision
+
+---
+
+## 17. Key Differences Between Legacy and New Solvers
+
+| Aspect | Legacy | New |
+|--------|--------|-----|
+| Solver name | `LegacyCelerisLab` / `CelerisLab` | `CelerisLab` (new) |
+| Main class | `FlowField(config_field, config_cuda, device_id)` | `Simulation(config)` |
+| Object setup | `add_cylinder()`, `add_sensor()` at runtime | Pre-defined in JSON or added before `initialize()` |
+| Checkpoint | `get_ddf()` / `save_ddf()` / `restore_ddf()` / `apply_ddf()` | `snapshot()` / `restore()` or save_checkpoint |
+| Force reading | Part of unified `obs` array | `read_force(body_id)` per body |
+| Sensor reading | Part of unified `obs` array | `read_sensor(body_id)` per body |
+| Torque reading | Not used in legacy (only in ReduceObs) | `read_torque(body_id)` |
+| Action smoothing | Built-in (weight=0.1) | None |
+| Action application | Single `run(N, action_array)` | `set_body(id, omega=val)` per body then `run(N)` |
+| Context management | `context.push()` / `.pop()` for CUDA isolation | Stream-based |
+
+### 17.1 Force/Sensor Value Correction
+
+The fundamental difference in how forces and sensors are accumulated:
+
+**Legacy**: `flow_field.run(N, action)` → internal loop averages over N steps → `obs` contains per-step averages.
+
+**New**: `sim.run(N)` → accelerators accumulate raw sums → `read_force(id)` gives N-step sum → **must divide by N**.
+
+---
+
+*End of comprehensive knowledge document. Last updated: 2026-06-05.*

src/drl_pinball/legacy_env/__init__.py

@@ -0,0 +1 @@
+

src/drl_pinball/legacy_env/legacy_env_erase.py

@@ -0,0 +1,304 @@
+# 这个是erase的env，用于训练和评估d1a3o12_250729_250326_erase系列模型
+# 上游扰流圆柱，场景与Karman_cloak_standard一致，
+# 但是目标是希望pinball后流场跟入口一致，即抹除扰流圆柱尾迹
+# 模型名中D代表信号延迟
+import gymnasium as gym
+import numpy as np
+from gymnasium import spaces
+import ctypes
+from collections import deque
+from typing import Tuple
+import sys
+import os
+import matplotlib.pyplot as plt
+import queue
+
+os.environ["OMP_NUM_THREADS"] = "1"
+os.environ["MKL_NUM_THREADS"] = "1"
+
+current_dir = os.path.dirname(os.path.abspath("__file__"))
+parent_dir = os.path.abspath(os.path.join(current_dir, os.pardir))
+sys.path.append(parent_dir)
+from CelerisLab import FlowField
+from CelerisLab import utils
+
+config_cuda = utils.load_cuda_config(
+    os.path.join(parent_dir, "configs", "config_cuda.json")
+)
+config_field = utils.load_flow_field_config(
+    os.path.join(parent_dir, "configs", "config_flowfield.json")
+)
+
+S_DIM, A_DIM = 12, 3
+U0 = config_field.velocity
+T0 = 1000
+SAMPLE_INTERVAL = 600
+FIFO_LEN = 150
+CONV_LEN = 36
+MAX_STEPS = 500
+if config_field.data_type == "FP32":
+    DATA_TYPE = np.float32
+else:
+    raise ValueError(f"Unsupported data type {config_field.data_type}.")
+
+
+class CustomEnv(gym.Env):
+    """Custom Environment that follows gym interface."""
+
+    metadata = {"render_modes": ["human"], "render_fps": T0 / SAMPLE_INTERVAL}
+
+    def __init__(self, device_id=0):
+        super().__init__()
+        self.action_space = spaces.Box(low=-1, high=1, shape=(A_DIM,), dtype=DATA_TYPE)
+        self.observation_space = spaces.Box(
+            low=-1, high=1, shape=(S_DIM,), dtype=DATA_TYPE
+        )
+        self.fifo_states = deque(maxlen=FIFO_LEN)
+        self.target_states = np.empty((0, 6), dtype=DATA_TYPE)
+        self.force_norm_fact = 1.0
+        self.sens_norm_fact = np.ones(6, dtype=DATA_TYPE)
+        self.sens_deviation = np.zeros(6, dtype=DATA_TYPE)
+        self.reward_u = 0.0
+        self.reward_v = 0.0
+        self.reward_sim = 0.0
+        self.current_step = 0
+
+        self.flow_field = FlowField(config_field, config_cuda, device_id)
+        L0 = 20
+        U0 = config_field.velocity
+        NX = self.flow_field.FIELD_SHAPE[0]
+        NY = self.flow_field.FIELD_SHAPE[1]
+
+        self.ddf_ave = np.zeros((NX, NY, 9), dtype=DATA_TYPE)
+        self.ddf_ave_cont = 0
+
+        # center: Tuple[float, float, float] = (10 * L0, (NY - 1) / 2, 0)
+        # self.flow_field.add_cylinder(center, L0)
+        center: Tuple[float, float, float] = (40 * L0, (NY - 1) / 2 + 2 * L0, 0)
+        self.flow_field.add_sensor(center, L0 / 4)
+        center: Tuple[float, float, float] = (40 * L0, (NY - 1) / 2, 0)
+        self.flow_field.add_sensor(center, L0 / 4)
+        center: Tuple[float, float, float] = (40 * L0, (NY - 1) / 2 - 2 * L0, 0)
+        self.flow_field.add_sensor(center, L0 / 4)
+        self.flow_field.run(int(2*NX/U0), np.zeros(3, dtype=DATA_TYPE))
+
+        for i in range(FIFO_LEN):
+            self.flow_field.run(SAMPLE_INTERVAL, np.zeros(3, dtype=DATA_TYPE))
+            new_state = self.flow_field.obs.copy()[0:6]
+            self.target_states = np.vstack((self.target_states, new_state))
+
+        self.target_sensors = np.mean(self.target_states, axis=0)
+
+        # self.flow_field.apply_ddf()
+        center: Tuple[float, float, float] = (10 * L0, (NY - 1) / 2, 0)
+        self.flow_field.add_cylinder(center, 0.75*L0)
+        center: Tuple[float, float, float] = (30 * L0, (NY - 1) / 2, 0)
+        self.flow_field.add_cylinder(center, L0 / 2)
+        center: Tuple[float, float, float] = (31.3 * L0, (NY - 1) / 2 + 0.75 * L0, 0)
+        self.flow_field.add_cylinder(center, L0 / 2)
+        center: Tuple[float, float, float] = (31.3 * L0, (NY - 1) / 2 - 0.75 * L0, 0)
+        self.flow_field.add_cylinder(center, L0 / 2)
+        self.flow_field.run(int(4*NX/U0), np.zeros(7, dtype=DATA_TYPE))
+        self.flow_field.get_ddf()
+        self.flow_field.save_ddf()
+
+        for i in range(FIFO_LEN):
+            self.flow_field.run(SAMPLE_INTERVAL, np.zeros(7, dtype=DATA_TYPE))
+            self.fifo_states.append(self.flow_field.obs.copy()[0:14])
+
+        temp_states = np.array(self.fifo_states)
+        self.force_norm_fact = 100 * np.max(np.abs(temp_states[:, 8:14]))
+
+        for i in range(6):
+            self.sens_deviation[i] = np.mean(temp_states[:, i])
+            self.sens_norm_fact[i] = 10 * np.max(np.abs(temp_states[:, i] - self.sens_deviation[i]))
+
+        self.flow_field.apply_ddf()
+
+        for i in range(FIFO_LEN):
+            self.flow_field.run(SAMPLE_INTERVAL, np.array([0.0, 0.0, 0.0, 0.0, 0.0, -8*U0, 8*U0], dtype=DATA_TYPE))
+            self.fifo_states.append(self.flow_field.obs.copy()[0:14])
+            
+        self.save_states = self.fifo_states.copy()
+        self.flow_field.apply_ddf()
+
+    def step(self, action):
+        assert self.action_space.contains(action), "%r (%s) invalid" % (
+            action,
+            type(action),
+        )
+
+        # barrier = threading.Barrier(2)
+        result_queue = queue.Queue()
+
+        def run_flow_field(action):
+            self.flow_field.context.push()
+            U0 = config_field.velocity
+            try:
+                temp = np.zeros(7, dtype=DATA_TYPE)
+                temp[4:7] = np.array((action*8+[0,-8,8])*U0, dtype=DATA_TYPE)
+                self.flow_field.run(SAMPLE_INTERVAL, temp)
+            finally:
+                self.flow_field.context.pop()
+            # barrier.wait()
+            self.fifo_states.append(self.flow_field.obs.copy()[0:14])
+
+        def proc_data():
+            states = np.array(self.fifo_states)
+            forces = states[-1, 6:14] / self.force_norm_fact
+            cd = (forces[2] + forces[4] + forces[6]) / 3
+            cl = (forces[3] + forces[5] + forces[7]) / 3
+            sens = (states[-1, 0:6] - self.sens_deviation) / self.sens_norm_fact
+            target_sens = (self.target_sensors - self.sens_deviation) / self.sens_norm_fact
+
+            similarities = 0.0
+
+            def calc_lag(target, state):
+                target_mean = np.mean(target)
+                state_mean = np.mean(state)
+
+                correlation = np.correlate(target - target_mean, state - state_mean, "full")
+                lags = np.arange(-len(target) + 1, len(target))
+                max_lag = lags[np.argmax(correlation)]
+                return max_lag
+                
+            def calc_sim(target, state):
+                # 计算幅值差异权重
+                target_std = np.std(target) if np.std(target) > 1e-8 else 1e-8
+                state_std = np.std(state) if np.std(state) > 1e-8 else 1e-8
+                amplitude_ratio = min(target_std, state_std) / max(target_std, state_std)
+                
+                # 计算均值差异
+                mean_diff = abs(np.mean(target) - np.mean(state))
+                max_scale = max(abs(np.mean(target)), abs(np.mean(state)), 1e-8)
+                mean_similarity = 1 / (1 + mean_diff / max_scale * 10)
+                
+                # DTW计算
+                n = len(target)
+                m = len(state)
+                
+                dtw_matrix = np.full((n + 1, m + 1), np.inf)
+                dtw_matrix[0, 0] = 0
+
+                for i in range(1, n + 1):
+                    for j in range(1, m + 1):
+                        cost = abs(target[i - 1] - state[j - 1])
+                        last_min = min(dtw_matrix[i - 1, j],
+                                    dtw_matrix[i, j - 1],
+                                    dtw_matrix[i - 1, j - 1])
+                        dtw_matrix[i, j] = cost + last_min
+                
+                # 改进的归一化方法
+                max_possible_cost = max(np.max(np.abs(target)), np.max(np.abs(state)), 1e-8)
+                dtw_distance = dtw_matrix[n, m] / (len(target) * max_possible_cost)
+                DTW_similarity = max(0, 1 - dtw_distance)
+                
+                # 综合相似度：形状相似度 * 幅值相似度 * 均值相似度
+                total_similarity = 0.8 * DTW_similarity + 0.1 * amplitude_ratio + 0.1 * mean_similarity
+                
+                return total_similarity
+
+            # id_sens = 1
+            # target_seq = self.target_states[CONV_LEN:2*CONV_LEN, id_sens]
+            target_seq = -states[CONV_LEN:2*CONV_LEN, 7]
+            # state_seq = states[-CONV_LEN:, id_sens]
+            state_seq = states[-CONV_LEN:, 9]
+            lag = calc_lag(target_seq, state_seq)
+
+            for i in range(0, 2):
+                target_seq = -np.roll(states[:, i+6], -lag)[CONV_LEN:2*CONV_LEN]
+                state_seq = states[-CONV_LEN:, i+8] + states[-CONV_LEN:, i+10] + states[-CONV_LEN:, i+12]
+                similarities += calc_sim(target_seq, state_seq) / 2
+
+            diff_u = (np.abs(sens[0] - target_sens[0]) + np.abs(sens[2] - target_sens[2]) + np.abs(sens[4] - target_sens[4]))/3
+            diff_v = (np.abs(sens[1] - target_sens[1]) + np.abs(sens[3] - target_sens[3]) + np.abs(sens[5] - target_sens[5]))/3
+            mean_u = np.mean(np.abs(states[:, 0] - self.target_sensors[0]) \
+                             + np.abs(states[:, 2] - self.target_sensors[2]) \
+                             + np.abs(states[:, 4] - self.target_sensors[4])) / self.sens_norm_fact[2]
+            amp_v = np.std(states[:, 1] + states[:, 3] + states[:, 5]) / self.sens_norm_fact[3]
+            self.reward_u = np.exp(-np.abs(diff_u * 40))
+            self.reward_v = 0.7 * np.exp(-np.abs(amp_v * 20)) + 0.3 * np.exp(-np.abs(diff_v * 20))
+            # self.reward_sim = np.exp(-50*np.abs(similarities - 1)**2)
+            self.reward_sim = similarities
+            reward = np.minimum(0.4 * self.reward_u + 0.4 * self.reward_v + 0.2 * self.reward_sim, 1.0)
+            result_queue.put((np.hstack([forces[2:8], sens]), reward))
+
+        run_flow_field(action)
+        proc_data()
+        observation, reward = result_queue.get()
+
+        truncated = bool(np.any(observation > 1) or np.any(observation < -1))
+        observation = np.clip(observation, -1, 1)
+        self.current_step += 1
+        # done = self.current_step >= MAX_STEPS
+        done = False
+        return observation, float(reward), done, truncated, {}
+    
+    def reset(self, seed=None):
+        self.flow_field.restore_ddf()
+        self.flow_field.apply_ddf()
+        self.fifo_states = self.save_states.copy()
+        self.current_step = 0
+        return np.zeros(S_DIM, dtype=np.float32), {}
+    
+    def render(self, mode="human"):
+        NX = self.flow_field.FIELD_SHAPE[0]
+        NY = self.flow_field.FIELD_SHAPE[1]
+        self.flow_field.get_ddf()
+        ddf_plot = self.flow_field.ddf.copy().reshape((9, NY, NX)).transpose(2, 1, 0)
+        ux = (ddf_plot[:, :, 1] + ddf_plot[:, :, 5] + ddf_plot[:, :, 8] - ddf_plot[:, :, 3] - ddf_plot[:, :, 6] - ddf_plot[:, :, 7]) / U0
+        uy = (ddf_plot[:, :, 2] + ddf_plot[:, :, 5] + ddf_plot[:, :, 6] - ddf_plot[:, :, 4] - ddf_plot[:, :, 7] - ddf_plot[:, :, 8]) / U0
+        speed = np.sqrt(ux**2 + uy**2)
+        plt.figure(figsize=(10, 5))
+        plt.imshow(speed.T, origin='lower', cmap='viridis', extent=[0, NX, 0, NY])
+        plt.colorbar(label='Speed')
+        plt.title('Scalar Velocity Field')
+        plt.xlabel('X')
+        plt.ylabel('Y')
+        plt.tight_layout()
+        plt.show()
+
+    def save_field(self, filename):
+        NX = self.flow_field.FIELD_SHAPE[0]
+        NY = self.flow_field.FIELD_SHAPE[1]
+        self.flow_field.get_ddf()
+        ddf_plot = self.flow_field.ddf.copy().reshape((9, NY, NX)).transpose(2, 1, 0)
+        flag_plot = self.flow_field.flag.copy().reshape((NY, NX)).transpose(1, 0)
+        ux = (ddf_plot[:, :, 1] + ddf_plot[:, :, 5] + ddf_plot[:, :, 8] - ddf_plot[:, :, 3] - ddf_plot[:, :, 6] - ddf_plot[:, :, 7]) / U0
+        uy = (ddf_plot[:, :, 2] + ddf_plot[:, :, 5] + ddf_plot[:, :, 6] - ddf_plot[:, :, 4] - ddf_plot[:, :, 7] - ddf_plot[:, :, 8]) / U0
+        with open(os.path.join(parent_dir, "output", filename), "w") as f:
+            f.write("Title= \"LBM 2D\"\r\n")
+            f.write("VARIABLES= \"X\",\"Y\",\"flag\",\"U\",\"V\",\r\n")
+            f.write(f"ZONE T= \"BOX\",I= {NX},J= {NY},F=POINT\r\n")
+            for j in range(NY):
+                for i in range(NX):
+                    f.write(f"{i},{j},{flag_plot[i, j]},{ux[i, j]},{uy[i, j]}\r\n")
+
+    def average_field(self, mode=["add", "save", "clear"], filename="average_field.dat"):
+        NX = self.flow_field.FIELD_SHAPE[0]
+        NY = self.flow_field.FIELD_SHAPE[1]
+        self.flow_field.get_ddf()
+        ddf_new = self.flow_field.ddf.copy().reshape((9, NY, NX)).transpose(2, 1, 0)
+        if "add" in mode:
+            self.ddf_ave = self.ddf_ave + ddf_new
+            self.ddf_ave_cont += 1
+        if "save" in mode:
+            if self.ddf_ave_cont == 0:
+                raise ValueError("No data to save. Please run 'add' mode first.")
+            ux = (self.ddf_ave[:, :, 1] + self.ddf_ave[:, :, 5] + self.ddf_ave[:, :, 8] - self.ddf_ave[:, :, 3] - self.ddf_ave[:, :, 6] - self.ddf_ave[:, :, 7]) / U0 / self.ddf_ave_cont
+            uy = (self.ddf_ave[:, :, 2] + self.ddf_ave[:, :, 5] + self.ddf_ave[:, :, 6] - self.ddf_ave[:, :, 4] - self.ddf_ave[:, :, 7] - self.ddf_ave[:, :, 8]) / U0 / self.ddf_ave_cont
+            flag_plot = self.flow_field.flag.copy().reshape((NY, NX)).transpose(1, 0)
+            with open(os.path.join(parent_dir, "output", filename), "w") as f:
+                f.write("Title= \"LBM 2D\"\r\n")
+                f.write("VARIABLES= \"X\",\"Y\",\"flag\",\"U\",\"V\",\r\n")
+                f.write(f"ZONE T= \"BOX\",I= {NX},J= {NY},F=POINT\r\n")
+                for j in range(NY):
+                    for i in range(NX):
+                        f.write(f"{i},{j},{flag_plot[i, j]},{ux[i, j]},{uy[i, j]}\r\n")
+            print(f"Average field amount: {self.ddf_ave_cont}")
+        if "clear" in mode:
+            self.ddf_ave = np.zeros((NX, NY, 9), dtype=DATA_TYPE)
+            self.ddf_ave_cont = 0
+
+    def close(self):
+        self.flow_field.__del__()

src/drl_pinball/legacy_env/legacy_env_imit.py

@@ -0,0 +1,318 @@
+# 这个是imit圆柱的env，用于训练和评估d1a3o14_250525_imit系列模型 
+# 上游干净来流，目标是pinball后流场跟设定尺寸圆柱一致
+# 模型名中L代表目标直径，S代表SAMPLE_INTERVAL
+import gymnasium as gym
+import numpy as np
+from gymnasium import spaces
+import ctypes
+from collections import deque
+from typing import Tuple
+import sys
+import os
+import matplotlib.pyplot as plt
+import queue
+
+os.environ["OMP_NUM_THREADS"] = "1"
+os.environ["MKL_NUM_THREADS"] = "1"
+
+current_dir = os.path.dirname(os.path.abspath("__file__"))
+parent_dir = os.path.abspath(os.path.join(current_dir, os.pardir))
+sys.path.append(parent_dir)
+from CelerisLab import FlowField
+from CelerisLab import utils
+
+config_cuda = utils.load_cuda_config(
+    os.path.join(parent_dir, "configs", "config_cuda.json")
+)
+config_field = utils.load_flow_field_config(
+    os.path.join(parent_dir, "configs", "config_flowfield.json")
+)
+
+S_DIM, A_DIM = 14, 3
+U0 = config_field.velocity
+T0 = 1000
+SAMPLE_INTERVAL = 600 # 这里会随着圆柱尺寸和粘性变动，在模型名中体现
+FIFO_LEN = 150
+CONV_LEN = 36
+MAX_STEPS = 500
+if config_field.data_type == "FP32":
+    DATA_TYPE = np.float32
+else:
+    raise ValueError(f"Unsupported data type {config_field.data_type}.")
+
+
+class CustomEnv(gym.Env):
+    """Custom Environment that follows gym interface."""
+
+    metadata = {"render_modes": ["human"], "render_fps": T0 / SAMPLE_INTERVAL}
+
+    def __init__(self, device_id=0):
+        super().__init__()
+        self.action_space = spaces.Box(low=-1, high=1, shape=(A_DIM,), dtype=DATA_TYPE)
+        self.observation_space = spaces.Box(
+            low=-1, high=1, shape=(S_DIM,), dtype=DATA_TYPE
+        )
+        self.fifo_states = deque(maxlen=FIFO_LEN)
+        self.target_states = np.empty((0, 8), dtype=DATA_TYPE)
+        self.force_norm_fact = 1.0
+        self.sens_norm_fact = np.ones(6, dtype=DATA_TYPE)
+        self.sens_deviation = np.zeros(6, dtype=DATA_TYPE)
+        self.reward_cd = 0.0
+        self.reward_cl = 0.0
+        self.reward_sim = 0.0
+        self.current_step = 0
+
+        self.flow_field = FlowField(config_field, config_cuda, device_id)
+        L0 = 20
+        U0 = config_field.velocity
+        NX = self.flow_field.FIELD_SHAPE[0]
+        NY = self.flow_field.FIELD_SHAPE[1]
+
+        self.ddf_ave = np.zeros((NX, NY, 9), dtype=DATA_TYPE)
+        self.ddf_ave_cont = 0
+
+        center: Tuple[float, float, float] = (20 * L0, (NY - 1) / 2, 0)
+        self.flow_field.add_cylinder(center, 1.5*L0) # 这里会随着圆柱尺寸变动，在模型名中体现
+        center: Tuple[float, float, float] = (30 * L0, (NY - 1) / 2 + 2 * L0, 0)
+        self.flow_field.add_sensor(center, L0 / 4)
+        center: Tuple[float, float, float] = (30 * L0, (NY - 1) / 2, 0)
+        self.flow_field.add_sensor(center, L0 / 4)
+        center: Tuple[float, float, float] = (30 * L0, (NY - 1) / 2 - 2 * L0, 0)
+        self.flow_field.add_sensor(center, L0 / 4)
+        self.flow_field.run(int(4*NX/U0), np.zeros(4, dtype=DATA_TYPE))
+
+        for i in range(FIFO_LEN):
+            self.flow_field.run(SAMPLE_INTERVAL, np.zeros(4, dtype=DATA_TYPE))
+            new_state = self.flow_field.obs.copy()[0:8]
+            self.target_states = np.vstack((self.target_states, new_state))
+
+        def analyze_harmonics(states, n_harmonics):
+            N, D = states.shape
+            result = []
+            for d in range(D):
+                y = states[:, d]
+                fft_coef = np.fft.rfft(y)
+                freqs = np.fft.rfftfreq(N, d=1)
+                amps = 2 * np.abs(fft_coef) / N
+                phases = np.angle(fft_coef)
+                idx = np.argsort(amps[1:])[::-1][:n_harmonics] + 1
+                harmonics = {
+                    'dc': np.real(fft_coef[0]) / N,
+                    'amps': amps[idx],
+                    'freqs': freqs[idx],
+                    'phases': phases[idx]
+                }
+                result.append(harmonics)
+            return result
+
+        self.target_harmonics = analyze_harmonics(self.target_states, n_harmonics=5)
+
+        del self.flow_field
+        self.flow_field = FlowField(config_field, config_cuda, device_id)
+
+        center: Tuple[float, float, float] = (30 * L0, (NY - 1) / 2 + 2 * L0, 0)
+        self.flow_field.add_sensor(center, L0 / 4)
+        center: Tuple[float, float, float] = (30 * L0, (NY - 1) / 2, 0)
+        self.flow_field.add_sensor(center, L0 / 4)
+        center: Tuple[float, float, float] = (30 * L0, (NY - 1) / 2 - 2 * L0, 0)
+        self.flow_field.add_sensor(center, L0 / 4)
+        center: Tuple[float, float, float] = (19 * L0, (NY - 1) / 2, 0)
+        self.flow_field.add_cylinder(center, L0 / 2)
+        center: Tuple[float, float, float] = (20.3 * L0, (NY - 1) / 2 + 0.75 * L0, 0)
+        self.flow_field.add_cylinder(center, L0 / 2)
+        center: Tuple[float, float, float] = (20.3 * L0, (NY - 1) / 2 - 0.75 * L0, 0)
+        self.flow_field.add_cylinder(center, L0 / 2)
+        self.flow_field.run(int(4*NX/U0), np.zeros(6, dtype=DATA_TYPE))
+        self.flow_field.get_ddf()
+        self.flow_field.save_ddf()
+
+        for i in range(FIFO_LEN):
+            self.flow_field.run(SAMPLE_INTERVAL, np.zeros(6, dtype=DATA_TYPE))
+            self.fifo_states.append(self.flow_field.obs.copy()[0:12])
+
+        temp_states = np.array(self.fifo_states)
+        self.force_norm_fact = 6 * np.max(np.abs(temp_states[:, 6:12]))
+
+        for i in range(6):
+            self.sens_deviation[i] = np.mean(temp_states[:, i])
+            self.sens_norm_fact[i] = 5 * np.max(np.abs(temp_states[:, i] - self.sens_deviation[i]))
+
+        self.flow_field.apply_ddf()
+
+        for i in range(FIFO_LEN):
+            self.flow_field.run(SAMPLE_INTERVAL, np.array([0.0, 0.0, 0.0, 0.0, -1*U0, 1*U0], dtype=DATA_TYPE))
+            self.fifo_states.append(self.flow_field.obs.copy()[0:12])
+            
+        self.save_states = self.fifo_states.copy()
+        self.flow_field.get_ddf()
+        self.flow_field.save_ddf()
+
+    def step(self, action):
+        assert self.action_space.contains(action), "%r (%s) invalid" % (
+            action,
+            type(action),
+        )
+
+        # barrier = threading.Barrier(2)
+        result_queue = queue.Queue()
+
+        def run_flow_field(action):
+            self.flow_field.context.push()
+            U0 = config_field.velocity
+            try:
+                temp = np.zeros(6, dtype=DATA_TYPE)
+                temp[3:6] = np.array((action*8+[0,-2,2])*U0, dtype=DATA_TYPE)
+                self.flow_field.run(SAMPLE_INTERVAL, temp)
+            finally:
+                self.flow_field.context.pop()
+            # barrier.wait()
+            self.fifo_states.append(self.flow_field.obs.copy()[0:12])
+
+        def proc_data():
+            states = np.array(self.fifo_states)
+            forces = states[-1, 6:12] / self.force_norm_fact
+            cd = forces[0] + forces[2] + forces[4]
+            cl = forces[1] + forces[3] + forces[5]
+            sens = (states[-1, 0:6] - self.sens_deviation) / self.sens_norm_fact
+
+            similarities = 0.0
+
+            def calc_lag(target, state):
+                target_mean = np.mean(target)
+                state_mean = np.mean(state)
+
+                correlation = np.correlate(target - target_mean, state - state_mean, "full")
+                lags = np.arange(-len(target) + 1, len(target))
+                max_lag = lags[np.argmax(correlation)]
+                return max_lag
+                
+            def calc_sim(target, state):
+
+                n = len(target)
+                m = len(state)
+                
+                dtw_matrix = np.full((n + 1, m + 1), np.inf)
+                dtw_matrix[0, 0] = 0
+                
+                for i in range(1, n + 1):
+                    for j in range(1, m + 1):
+                        cost = abs(target[i - 1] - state[j - 1])
+                        last_min = min(dtw_matrix[i - 1, j],
+                                    dtw_matrix[i, j - 1],
+                                    dtw_matrix[i - 1, j - 1])
+                        dtw_matrix[i, j] = cost + last_min
+
+                return 1 - (dtw_matrix[n, m] / len(target))
+            
+            def gen_target_states_at(t, harmonics):
+                t = np.asarray(t)
+                D = len(harmonics)
+                result = np.zeros((t.size, D), dtype=np.float32)
+                for d, h in enumerate(harmonics):
+                    val = np.full(t.shape, h['dc'], dtype=np.float32)
+                    for amp, freq, phase in zip(h['amps'], h['freqs'], h['phases']):
+                        val += amp * np.cos(2 * np.pi * freq * t + phase)
+                    result[:, d] = val
+                if result.shape[0] == 1:
+                    return result[0]
+                return result
+
+            id_sens = 1
+            target_seq = self.target_states[CONV_LEN:2*CONV_LEN, id_sens+2]
+            state_seq = states[-CONV_LEN:, id_sens]
+            lag = calc_lag(target_seq, state_seq)
+
+            for i in range(0, 6):
+                target_seq = np.roll(self.target_states[:, i+2], -lag)[CONV_LEN:2*CONV_LEN]
+                state_seq = states[-CONV_LEN:, i]
+                similarities += calc_sim(target_seq, state_seq) / 6
+
+            target_states = gen_target_states_at(self.current_step, self.target_harmonics)
+            target_cd = target_states[0] / self.force_norm_fact
+            target_cl = target_states[1] / self.force_norm_fact
+
+            self.reward_cd = np.exp(-np.abs((cd-target_cd) * 10))
+            self.reward_cl = np.exp(-np.abs((cl-target_cl) * 10))
+            self.reward_sim = np.exp(-10*np.abs(similarities - 1))
+            reward = np.minimum(0.3 * self.reward_cd + 0.3 * self.reward_cl + 0.4 * self.reward_sim, 1.0)
+            result_queue.put((np.hstack([forces, sens, target_cd, target_cl]), reward))
+
+        run_flow_field(action)
+        proc_data()
+        observation, reward = result_queue.get()
+
+        truncated = bool(np.any(observation > 1) or np.any(observation < -1))
+        observation = np.clip(observation, -1, 1)
+        self.current_step += 1
+        # done = self.current_step >= MAX_STEPS
+        done = False
+        return observation, float(reward), done, truncated, {}
+    
+    def reset(self, seed=None):
+        self.flow_field.restore_ddf()
+        self.flow_field.apply_ddf()
+        self.fifo_states = self.save_states.copy()
+        self.current_step = 0
+        return np.zeros(S_DIM, dtype=np.float32), {}
+    
+    def render(self, mode="human"):
+        NX = self.flow_field.FIELD_SHAPE[0]
+        NY = self.flow_field.FIELD_SHAPE[1]
+        self.flow_field.get_ddf()
+        ddf_plot = self.flow_field.ddf.copy().reshape((9, NY, NX)).transpose(2, 1, 0)
+        ux = (ddf_plot[:, :, 1] + ddf_plot[:, :, 5] + ddf_plot[:, :, 8] - ddf_plot[:, :, 3] - ddf_plot[:, :, 6] - ddf_plot[:, :, 7]) / U0
+        uy = (ddf_plot[:, :, 2] + ddf_plot[:, :, 5] + ddf_plot[:, :, 6] - ddf_plot[:, :, 4] - ddf_plot[:, :, 7] - ddf_plot[:, :, 8]) / U0
+        speed = np.sqrt(ux**2 + uy**2)
+        plt.figure(figsize=(10, 5))
+        plt.imshow(speed.T, origin='lower', cmap='viridis', extent=[0, NX, 0, NY])
+        plt.colorbar(label='Speed')
+        plt.title('Scalar Velocity Field')
+        plt.xlabel('X')
+        plt.ylabel('Y')
+        plt.tight_layout()
+        plt.show()
+
+    def save_field(self, filename):
+        NX = self.flow_field.FIELD_SHAPE[0]
+        NY = self.flow_field.FIELD_SHAPE[1]
+        self.flow_field.get_ddf()
+        ddf_plot = self.flow_field.ddf.copy().reshape((9, NY, NX)).transpose(2, 1, 0)
+        flag_plot = self.flow_field.flag.copy().reshape((NY, NX)).transpose(1, 0)
+        ux = (ddf_plot[:, :, 1] + ddf_plot[:, :, 5] + ddf_plot[:, :, 8] - ddf_plot[:, :, 3] - ddf_plot[:, :, 6] - ddf_plot[:, :, 7]) / U0
+        uy = (ddf_plot[:, :, 2] + ddf_plot[:, :, 5] + ddf_plot[:, :, 6] - ddf_plot[:, :, 4] - ddf_plot[:, :, 7] - ddf_plot[:, :, 8]) / U0
+        with open(os.path.join(parent_dir, "output", filename), "w") as f:
+            f.write("Title= \"LBM 2D\"\r\n")
+            f.write("VARIABLES= \"X\",\"Y\",\"flag\",\"U\",\"V\",\r\n")
+            f.write(f"ZONE T= \"BOX\",I= {NX},J= {NY},F=POINT\r\n")
+            for j in range(NY):
+                for i in range(NX):
+                    f.write(f"{i},{j},{flag_plot[i, j]},{ux[i, j]},{uy[i, j]}\r\n")
+
+    def average_field(self, mode=["add", "save", "clear"], filename="average_field.dat"):
+        NX = self.flow_field.FIELD_SHAPE[0]
+        NY = self.flow_field.FIELD_SHAPE[1]
+        self.flow_field.get_ddf()
+        ddf_new = self.flow_field.ddf.copy().reshape((9, NY, NX)).transpose(2, 1, 0)
+        if "add" in mode:
+            self.ddf_ave = self.ddf_ave + ddf_new
+            self.ddf_ave_cont += 1
+        if "save" in mode:
+            if self.ddf_ave_cont == 0:
+                raise ValueError("No data to save. Please run 'add' mode first.")
+            ux = (self.ddf_ave[:, :, 1] + self.ddf_ave[:, :, 5] + self.ddf_ave[:, :, 8] - self.ddf_ave[:, :, 3] - self.ddf_ave[:, :, 6] - self.ddf_ave[:, :, 7]) / U0 / self.ddf_ave_cont
+            uy = (self.ddf_ave[:, :, 2] + self.ddf_ave[:, :, 5] + self.ddf_ave[:, :, 6] - self.ddf_ave[:, :, 4] - self.ddf_ave[:, :, 7] - self.ddf_ave[:, :, 8]) / U0 / self.ddf_ave_cont
+            flag_plot = self.flow_field.flag.copy().reshape((NY, NX)).transpose(1, 0)
+            with open(os.path.join(parent_dir, "output", filename), "w") as f:
+                f.write("Title= \"LBM 2D\"\r\n")
+                f.write("VARIABLES= \"X\",\"Y\",\"flag\",\"U\",\"V\",\r\n")
+                f.write(f"ZONE T= \"BOX\",I= {NX},J= {NY},F=POINT\r\n")
+                for j in range(NY):
+                    for i in range(NX):
+                        f.write(f"{i},{j},{flag_plot[i, j]},{ux[i, j]},{uy[i, j]}\r\n")
+            print(f"Average field amount: {self.ddf_ave_cont}")
+        if "clear" in mode:
+            self.ddf_ave = np.zeros((NX, NY, 9), dtype=DATA_TYPE)
+            self.ddf_ave_cont = 0
+
+    def close(self):
+        self.flow_field.__del__()

src/drl_pinball/legacy_env/legacy_env_imit_target.py

@@ -0,0 +1,207 @@
+# 这个是imit圆柱的env，用于产生d1a3o14_250525_imit系列模型的目标流场
+# 跟随模型，要匹配圆柱直径和采样频率
+# 模型名中L代表目标直径，S代表SAMPLE_INTERVAL
+import gymnasium as gym
+import numpy as np
+from gymnasium import spaces
+import ctypes
+from collections import deque
+from typing import Tuple
+import sys
+import os
+import matplotlib.pyplot as plt
+import queue
+
+os.environ["OMP_NUM_THREADS"] = "1"
+os.environ["MKL_NUM_THREADS"] = "1"
+
+current_dir = os.path.dirname(os.path.abspath("__file__"))
+parent_dir = os.path.abspath(os.path.join(current_dir, os.pardir))
+sys.path.append(parent_dir)
+from CelerisLab import FlowField
+from CelerisLab import utils
+
+config_cuda = utils.load_cuda_config(
+    os.path.join(parent_dir, "configs", "config_cuda.json")
+)
+config_field = utils.load_flow_field_config(
+    os.path.join(parent_dir, "configs", "config_flowfield.json")
+)
+
+S_DIM, A_DIM = 14, 3
+U0 = config_field.velocity
+T0 = 1000
+SAMPLE_INTERVAL = 600 # 这里会随着圆柱尺寸和粘性变动，在模型名中体现
+FIFO_LEN = 150
+CONV_LEN = 36
+MAX_STEPS = 500
+if config_field.data_type == "FP32":
+    DATA_TYPE = np.float32
+else:
+    raise ValueError(f"Unsupported data type {config_field.data_type}.")
+
+
+class CustomEnv(gym.Env):
+    """Custom Environment that follows gym interface."""
+
+    metadata = {"render_modes": ["human"], "render_fps": T0 / SAMPLE_INTERVAL}
+
+    def __init__(self, device_id=0):
+        super().__init__()
+        self.action_space = spaces.Box(low=-1, high=1, shape=(A_DIM,), dtype=DATA_TYPE)
+        self.observation_space = spaces.Box(
+            low=-1, high=1, shape=(S_DIM,), dtype=DATA_TYPE
+        )
+        self.fifo_states = deque(maxlen=FIFO_LEN)
+        self.target_states = np.empty((0, 8), dtype=DATA_TYPE)
+        self.force_norm_fact = 1.0
+        self.sens_norm_fact = np.ones(6, dtype=DATA_TYPE)
+        self.sens_deviation = np.zeros(6, dtype=DATA_TYPE)
+        self.reward_cd = 0.0
+        self.reward_cl = 0.0
+        self.reward_sim = 0.0
+        self.current_step = 0
+
+        self.flow_field = FlowField(config_field, config_cuda, device_id)
+        L0 = 20
+        U0 = config_field.velocity
+        NX = self.flow_field.FIELD_SHAPE[0]
+        NY = self.flow_field.FIELD_SHAPE[1]
+
+        self.ddf_ave = np.zeros((NX, NY, 9), dtype=DATA_TYPE)
+        self.ddf_ave_cont = 0
+
+        center: Tuple[float, float, float] = (20 * L0, (NY - 1) / 2, 0)
+        self.flow_field.add_cylinder(center, 1*L0) # 这里会随着圆柱尺寸变动，在模型名中体现
+        center: Tuple[float, float, float] = (30 * L0, (NY - 1) / 2 + 2 * L0, 0)
+        self.flow_field.add_sensor(center, L0 / 4)
+        center: Tuple[float, float, float] = (30 * L0, (NY - 1) / 2, 0)
+        self.flow_field.add_sensor(center, L0 / 4)
+        center: Tuple[float, float, float] = (30 * L0, (NY - 1) / 2 - 2 * L0, 0)
+        self.flow_field.add_sensor(center, L0 / 4)
+        self.flow_field.run(int(4*NX/U0), np.zeros(4, dtype=DATA_TYPE))
+
+        for i in range(FIFO_LEN):
+            self.flow_field.run(SAMPLE_INTERVAL, np.zeros(4, dtype=DATA_TYPE))
+            new_state = self.flow_field.obs.copy()[0:8]
+            self.target_states = np.vstack((self.target_states, new_state))
+
+        def analyze_harmonics(states, n_harmonics):
+            N, D = states.shape
+            result = []
+            for d in range(D):
+                y = states[:, d]
+                fft_coef = np.fft.rfft(y)
+                freqs = np.fft.rfftfreq(N, d=1)
+                amps = 2 * np.abs(fft_coef) / N
+                phases = np.angle(fft_coef)
+                idx = np.argsort(amps[1:])[::-1][:n_harmonics] + 1
+                harmonics = {
+                    'dc': np.real(fft_coef[0]) / N,
+                    'amps': amps[idx],
+                    'freqs': freqs[idx],
+                    'phases': phases[idx]
+                }
+                result.append(harmonics)
+            return result
+
+        self.target_harmonics = analyze_harmonics(self.target_states, n_harmonics=5)
+
+        self.flow_field.get_ddf()
+        self.flow_field.save_ddf()
+
+    def step(self, action):
+        assert self.action_space.contains(action), "%r (%s) invalid" % (
+            action,
+            type(action),
+        )
+
+        # barrier = threading.Barrier(2)
+        result_queue = queue.Queue()
+
+        def run_flow_field(action):
+            self.flow_field.context.push()
+            U0 = config_field.velocity
+            try:
+                temp = np.zeros(4, dtype=DATA_TYPE)
+                self.flow_field.run(SAMPLE_INTERVAL, temp)
+            finally:
+                self.flow_field.context.pop()
+            # barrier.wait()
+
+        run_flow_field(action)
+
+        truncated = False
+        observation = np.zeros(14, dtype=DATA_TYPE)
+        self.current_step += 1
+        # done = self.current_step >= MAX_STEPS
+        done = False
+        return observation, float(0), done, truncated, {}
+    
+    def reset(self, seed=None):
+        self.flow_field.restore_ddf()
+        self.flow_field.apply_ddf()
+        self.current_step = 0
+        return np.zeros(S_DIM, dtype=np.float32), {}
+    
+    def render(self, mode="human"):
+        NX = self.flow_field.FIELD_SHAPE[0]
+        NY = self.flow_field.FIELD_SHAPE[1]
+        self.flow_field.get_ddf()
+        ddf_plot = self.flow_field.ddf.copy().reshape((9, NY, NX)).transpose(2, 1, 0)
+        ux = (ddf_plot[:, :, 1] + ddf_plot[:, :, 5] + ddf_plot[:, :, 8] - ddf_plot[:, :, 3] - ddf_plot[:, :, 6] - ddf_plot[:, :, 7]) / U0
+        uy = (ddf_plot[:, :, 2] + ddf_plot[:, :, 5] + ddf_plot[:, :, 6] - ddf_plot[:, :, 4] - ddf_plot[:, :, 7] - ddf_plot[:, :, 8]) / U0
+        speed = np.sqrt(ux**2 + uy**2)
+        plt.figure(figsize=(10, 5))
+        plt.imshow(speed.T, origin='lower', cmap='viridis', extent=[0, NX, 0, NY])
+        plt.colorbar(label='Speed')
+        plt.title('Scalar Velocity Field')
+        plt.xlabel('X')
+        plt.ylabel('Y')
+        plt.tight_layout()
+        plt.show()
+
+    def save_field(self, filename):
+        NX = self.flow_field.FIELD_SHAPE[0]
+        NY = self.flow_field.FIELD_SHAPE[1]
+        self.flow_field.get_ddf()
+        ddf_plot = self.flow_field.ddf.copy().reshape((9, NY, NX)).transpose(2, 1, 0)
+        flag_plot = self.flow_field.flag.copy().reshape((NY, NX)).transpose(1, 0)
+        ux = (ddf_plot[:, :, 1] + ddf_plot[:, :, 5] + ddf_plot[:, :, 8] - ddf_plot[:, :, 3] - ddf_plot[:, :, 6] - ddf_plot[:, :, 7]) / U0
+        uy = (ddf_plot[:, :, 2] + ddf_plot[:, :, 5] + ddf_plot[:, :, 6] - ddf_plot[:, :, 4] - ddf_plot[:, :, 7] - ddf_plot[:, :, 8]) / U0
+        with open(os.path.join(parent_dir, "output", filename), "w") as f:
+            f.write("Title= \"LBM 2D\"\r\n")
+            f.write("VARIABLES= \"X\",\"Y\",\"flag\",\"U\",\"V\",\r\n")
+            f.write(f"ZONE T= \"BOX\",I= {NX},J= {NY},F=POINT\r\n")
+            for j in range(NY):
+                for i in range(NX):
+                    f.write(f"{i},{j},{flag_plot[i, j]},{ux[i, j]},{uy[i, j]}\r\n")
+
+    def average_field(self, mode=["add", "save", "clear"], filename="average_field.dat"):
+        NX = self.flow_field.FIELD_SHAPE[0]
+        NY = self.flow_field.FIELD_SHAPE[1]
+        self.flow_field.get_ddf()
+        ddf_new = self.flow_field.ddf.copy().reshape((9, NY, NX)).transpose(2, 1, 0)
+        if "add" in mode:
+            self.ddf_ave = self.ddf_ave + ddf_new
+            self.ddf_ave_cont += 1
+        if "save" in mode:
+            if self.ddf_ave_cont == 0:
+                raise ValueError("No data to save. Please run 'add' mode first.")
+            ux = (self.ddf_ave[:, :, 1] + self.ddf_ave[:, :, 5] + self.ddf_ave[:, :, 8] - self.ddf_ave[:, :, 3] - self.ddf_ave[:, :, 6] - self.ddf_ave[:, :, 7]) / U0 / self.ddf_ave_cont
+            uy = (self.ddf_ave[:, :, 2] + self.ddf_ave[:, :, 5] + self.ddf_ave[:, :, 6] - self.ddf_ave[:, :, 4] - self.ddf_ave[:, :, 7] - self.ddf_ave[:, :, 8]) / U0 / self.ddf_ave_cont
+            flag_plot = self.flow_field.flag.copy().reshape((NY, NX)).transpose(1, 0)
+            with open(os.path.join(parent_dir, "output", filename), "w") as f:
+                f.write("Title= \"LBM 2D\"\r\n")
+                f.write("VARIABLES= \"X\",\"Y\",\"flag\",\"U\",\"V\",\r\n")
+                f.write(f"ZONE T= \"BOX\",I= {NX},J= {NY},F=POINT\r\n")
+                for j in range(NY):
+                    for i in range(NX):
+                        f.write(f"{i},{j},{flag_plot[i, j]},{ux[i, j]},{uy[i, j]}\r\n")
+            print(f"Average field amount: {self.ddf_ave_cont}")
+        if "clear" in mode:
+            self.ddf_ave = np.zeros((NX, NY, 9), dtype=DATA_TYPE)
+            self.ddf_ave_cont = 0
+
+    def close(self):
+        self.flow_field.__del__()

src/drl_pinball/legacy_env/legacy_env_karman_cloak_standard.py

@@ -0,0 +1,270 @@
+# 这个是Karman_cloak_standard的env，用于训练和评估d1a3o12_re系列模型和250326模型 
+# 上游一个2D扰流圆柱，目标是pinball后流场跟无pinball一致
+import gymnasium as gym
+import numpy as np
+from gymnasium import spaces
+import ctypes
+from collections import deque
+from typing import Tuple
+import sys
+import os
+import matplotlib.pyplot as plt
+import queue
+
+os.environ["OMP_NUM_THREADS"] = "1"
+os.environ["MKL_NUM_THREADS"] = "1"
+
+current_dir = os.path.dirname(os.path.abspath("__file__"))
+parent_dir = os.path.abspath(os.path.join(current_dir, os.pardir))
+sys.path.append(parent_dir)
+from CelerisLab import FlowField
+from CelerisLab import utils
+
+config_cuda = utils.load_cuda_config(
+    os.path.join(parent_dir, "configs", "config_cuda.json")
+)
+config_field = utils.load_flow_field_config(
+    os.path.join(parent_dir, "configs", "config_flowfield.json")
+)
+
+S_DIM, A_DIM = 12, 3
+U0 = config_field.velocity
+T0 = 1000
+SAMPLE_INTERVAL = 800
+FIFO_LEN = 150
+CONV_LEN = 30
+MAX_STEPS = 500
+if config_field.data_type == "FP32":
+    DATA_TYPE = np.float32
+else:
+    raise ValueError(f"Unsupported data type {config_field.data_type}.")
+
+
+class CustomEnv(gym.Env):
+    """Custom Environment that follows gym interface."""
+
+    metadata = {"render_modes": ["human"], "render_fps": T0 / SAMPLE_INTERVAL}
+
+    def __init__(self, device_id=0):
+        super().__init__()
+        self.action_space = spaces.Box(low=-1, high=1, shape=(A_DIM,), dtype=DATA_TYPE)
+        self.observation_space = spaces.Box(
+            low=-1, high=1, shape=(S_DIM,), dtype=DATA_TYPE
+        )
+        self.fifo_states = deque(maxlen=FIFO_LEN)
+        self.target_states = np.empty((0, 6), dtype=DATA_TYPE)
+        self.force_norm_fact = 1.0
+        self.sens_norm_fact = np.ones(6, dtype=DATA_TYPE)
+        self.sens_deviation = np.zeros(6, dtype=DATA_TYPE)
+        self.reward_cd = 0.0
+        self.reward_cl = 0.0
+        self.reward_sim = 0.0
+        self.current_step = 0
+
+        self.flow_field = FlowField(config_field, config_cuda, device_id)
+        L0 = 20
+        U0 = config_field.velocity
+        NX = self.flow_field.FIELD_SHAPE[0]
+        NY = self.flow_field.FIELD_SHAPE[1]
+
+        self.ddf_ave = np.zeros((NX, NY, 9), dtype=DATA_TYPE)
+        self.ddf_ave_cont = 0
+
+        center: Tuple[float, float, float] = (10 * L0, (NY - 1) / 2, 0)
+        self.flow_field.add_cylinder(center, L0)
+        center: Tuple[float, float, float] = (40 * L0, (NY - 1) / 2 + 2 * L0, 0)
+        self.flow_field.add_sensor(center, L0 / 4)
+        center: Tuple[float, float, float] = (40 * L0, (NY - 1) / 2, 0)
+        self.flow_field.add_sensor(center, L0 / 4)
+        center: Tuple[float, float, float] = (40 * L0, (NY - 1) / 2 - 2 * L0, 0)
+        self.flow_field.add_sensor(center, L0 / 4)
+        self.flow_field.run(int(4*NX/U0), np.zeros(4, dtype=DATA_TYPE))
+
+        for i in range(FIFO_LEN):
+            self.flow_field.run(SAMPLE_INTERVAL, np.zeros(4, dtype=DATA_TYPE))
+            new_state = self.flow_field.obs.copy()[2:8]
+            self.target_states = np.vstack((self.target_states, new_state))
+
+        # self.flow_field.apply_ddf()
+        center: Tuple[float, float, float] = (30 * L0, (NY - 1) / 2, 0)
+        self.flow_field.add_cylinder(center, L0 / 2)
+        center: Tuple[float, float, float] = (31.3 * L0, (NY - 1) / 2 + 0.75 * L0, 0)
+        self.flow_field.add_cylinder(center, L0 / 2)
+        center: Tuple[float, float, float] = (31.3 * L0, (NY - 1) / 2 - 0.75 * L0, 0)
+        self.flow_field.add_cylinder(center, L0 / 2)
+        self.flow_field.run(int(4*NX/U0), np.zeros(7, dtype=DATA_TYPE))
+        self.flow_field.get_ddf()
+        self.flow_field.save_ddf()
+
+        for i in range(FIFO_LEN):
+            self.flow_field.run(SAMPLE_INTERVAL, np.zeros(7, dtype=DATA_TYPE))
+            self.fifo_states.append(self.flow_field.obs.copy()[2:14])
+
+        temp_states = np.array(self.fifo_states)
+        self.force_norm_fact = 6 * np.max(np.abs(temp_states[:, 6:12]))
+
+        for i in range(6):
+            self.sens_deviation[i] = np.mean(temp_states[:, i])
+            self.sens_norm_fact[i] = 5 * np.max(np.abs(temp_states[:, i] - self.sens_deviation[i]))
+
+        self.flow_field.apply_ddf()
+
+        for i in range(FIFO_LEN):
+            self.flow_field.run(SAMPLE_INTERVAL, np.array([0.0, 0.0, 0.0, 0.0, 0.0, -4*U0, 4*U0], dtype=DATA_TYPE))
+            self.fifo_states.append(self.flow_field.obs.copy()[2:14])
+            
+        self.save_states = self.fifo_states.copy()
+        self.flow_field.apply_ddf()
+
+    def step(self, action):
+        assert self.action_space.contains(action), "%r (%s) invalid" % (
+            action,
+            type(action),
+        )
+
+        # barrier = threading.Barrier(2)
+        result_queue = queue.Queue()
+
+        def run_flow_field(action):
+            self.flow_field.context.push()
+            U0 = config_field.velocity
+            try:
+                temp = np.zeros(7, dtype=DATA_TYPE)
+                temp[4:7] = np.array((action*8+[0,-4,4])*U0, dtype=DATA_TYPE)
+                self.flow_field.run(SAMPLE_INTERVAL, temp)
+            finally:
+                self.flow_field.context.pop()
+            # barrier.wait()
+            self.fifo_states.append(self.flow_field.obs.copy()[2:14])
+
+        def proc_data():
+            states = np.array(self.fifo_states)
+            forces = states[-1, 6:12] / self.force_norm_fact
+            cd = (forces[0] + forces[2] + forces[4]) / 3
+            cl = (forces[1] + forces[3] + forces[5]) / 3
+            sens = (states[-1, 0:6] - self.sens_deviation) / self.sens_norm_fact
+
+            similarities = 0.0
+
+            def calc_lag(target, state):
+                target_mean = np.mean(target)
+                state_mean = np.mean(state)
+
+                correlation = np.correlate(target - target_mean, state - state_mean, "full")
+                lags = np.arange(-len(target) + 1, len(target))
+                max_lag = lags[np.argmax(correlation)]
+                return max_lag
+                
+            def calc_sim(target, state):
+
+                n = len(target)
+                m = len(state)
+                
+                dtw_matrix = np.full((n + 1, m + 1), np.inf)
+                dtw_matrix[0, 0] = 0
+                
+                for i in range(1, n + 1):
+                    for j in range(1, m + 1):
+                        cost = abs(target[i - 1] - state[j - 1])
+                        last_min = min(dtw_matrix[i - 1, j],
+                                    dtw_matrix[i, j - 1],
+                                    dtw_matrix[i - 1, j - 1])
+                        dtw_matrix[i, j] = cost + last_min
+
+                return 1 - (dtw_matrix[n, m] / len(target))
+
+            id_sens = 1
+            target_seq = self.target_states[CONV_LEN:2*CONV_LEN, id_sens]
+            state_seq = states[-CONV_LEN:, id_sens]
+            lag = calc_lag(target_seq, state_seq)
+
+            for i in range(0, 6):
+                target_seq = np.roll(self.target_states[:, i], -lag)[CONV_LEN:2*CONV_LEN]
+                state_seq = states[-CONV_LEN:, i]
+                similarities += calc_sim(target_seq, state_seq) / 6
+
+            self.reward_cd = np.exp(-np.abs(cd * 20))
+            self.reward_cl = np.exp(-np.abs(cl * 80))
+            self.reward_sim = np.exp(-10*np.abs(similarities - 1))
+            reward = np.minimum(0.3 * self.reward_cd + 0.4 * self.reward_cl + 0.3 * self.reward_sim, 1.0)
+            result_queue.put((np.hstack([forces, sens]), reward))
+
+        run_flow_field(action)
+        proc_data()
+        observation, reward = result_queue.get()
+
+        truncated = bool(np.any(observation > 1) or np.any(observation < -1))
+        observation = np.clip(observation, -1, 1)
+        self.current_step += 1
+        # done = self.current_step >= MAX_STEPS
+        done = False
+        return observation, float(reward), done, truncated, {}
+    
+    def reset(self, seed=None):
+        self.flow_field.restore_ddf()
+        self.flow_field.apply_ddf()
+        self.fifo_states = self.save_states.copy()
+        self.current_step = 0
+        return np.zeros(S_DIM, dtype=np.float32), {}
+    
+    def render(self, mode="human"):
+        NX = self.flow_field.FIELD_SHAPE[0]
+        NY = self.flow_field.FIELD_SHAPE[1]
+        self.flow_field.get_ddf()
+        ddf_plot = self.flow_field.ddf.copy().reshape((9, NY, NX)).transpose(2, 1, 0)
+        ux = (ddf_plot[:, :, 1] + ddf_plot[:, :, 5] + ddf_plot[:, :, 8] - ddf_plot[:, :, 3] - ddf_plot[:, :, 6] - ddf_plot[:, :, 7]) / U0
+        uy = (ddf_plot[:, :, 2] + ddf_plot[:, :, 5] + ddf_plot[:, :, 6] - ddf_plot[:, :, 4] - ddf_plot[:, :, 7] - ddf_plot[:, :, 8]) / U0
+        speed = np.sqrt(ux**2 + uy**2)
+        plt.figure(figsize=(10, 5))
+        plt.imshow(speed.T, origin='lower', cmap='viridis', extent=[0, NX, 0, NY])
+        plt.colorbar(label='Speed')
+        plt.title('Scalar Velocity Field')
+        plt.xlabel('X')
+        plt.ylabel('Y')
+        plt.tight_layout()
+        plt.show()
+
+    def save_field(self, filename):
+        NX = self.flow_field.FIELD_SHAPE[0]
+        NY = self.flow_field.FIELD_SHAPE[1]
+        self.flow_field.get_ddf()
+        ddf_plot = self.flow_field.ddf.copy().reshape((9, NY, NX)).transpose(2, 1, 0)
+        flag_plot = self.flow_field.flag.copy().reshape((NY, NX)).transpose(1, 0)
+        ux = (ddf_plot[:, :, 1] + ddf_plot[:, :, 5] + ddf_plot[:, :, 8] - ddf_plot[:, :, 3] - ddf_plot[:, :, 6] - ddf_plot[:, :, 7]) / U0
+        uy = (ddf_plot[:, :, 2] + ddf_plot[:, :, 5] + ddf_plot[:, :, 6] - ddf_plot[:, :, 4] - ddf_plot[:, :, 7] - ddf_plot[:, :, 8]) / U0
+        with open(os.path.join(parent_dir, "output", filename), "w") as f:
+            f.write("Title= \"LBM 2D\"\r\n")
+            f.write("VARIABLES= \"X\",\"Y\",\"flag\",\"U\",\"V\",\r\n")
+            f.write(f"ZONE T= \"BOX\",I= {NX},J= {NY},F=POINT\r\n")
+            for j in range(NY):
+                for i in range(NX):
+                    f.write(f"{i},{j},{flag_plot[i, j]},{ux[i, j]},{uy[i, j]}\r\n")
+
+    def average_field(self, mode=["add", "save", "clear"], filename="average_field.dat"):
+        NX = self.flow_field.FIELD_SHAPE[0]
+        NY = self.flow_field.FIELD_SHAPE[1]
+        self.flow_field.get_ddf()
+        ddf_new = self.flow_field.ddf.copy().reshape((9, NY, NX)).transpose(2, 1, 0)
+        if "add" in mode:
+            self.ddf_ave = self.ddf_ave + ddf_new
+            self.ddf_ave_cont += 1
+        if "save" in mode:
+            if self.ddf_ave_cont == 0:
+                raise ValueError("No data to save. Please run 'add' mode first.")
+            ux = (self.ddf_ave[:, :, 1] + self.ddf_ave[:, :, 5] + self.ddf_ave[:, :, 8] - self.ddf_ave[:, :, 3] - self.ddf_ave[:, :, 6] - self.ddf_ave[:, :, 7]) / U0 / self.ddf_ave_cont
+            uy = (self.ddf_ave[:, :, 2] + self.ddf_ave[:, :, 5] + self.ddf_ave[:, :, 6] - self.ddf_ave[:, :, 4] - self.ddf_ave[:, :, 7] - self.ddf_ave[:, :, 8]) / U0 / self.ddf_ave_cont
+            flag_plot = self.flow_field.flag.copy().reshape((NY, NX)).transpose(1, 0)
+            with open(os.path.join(parent_dir, "output", filename), "w") as f:
+                f.write("Title= \"LBM 2D\"\r\n")
+                f.write("VARIABLES= \"X\",\"Y\",\"flag\",\"U\",\"V\",\r\n")
+                f.write(f"ZONE T= \"BOX\",I= {NX},J= {NY},F=POINT\r\n")
+                for j in range(NY):
+                    for i in range(NX):
+                        f.write(f"{i},{j},{flag_plot[i, j]},{ux[i, j]},{uy[i, j]}\r\n")
+            print(f"Average field amount: {self.ddf_ave_cont}")
+        if "clear" in mode:
+            self.ddf_ave = np.zeros((NX, NY, 9), dtype=DATA_TYPE)
+            self.ddf_ave_cont = 0
+
+    def close(self):
+        self.flow_field.__del__()

src/drl_pinball/legacy_env/legacy_env_reduce_obs.py

@@ -0,0 +1,245 @@
+# 这个是reduce_obs的env，用于训练和评估d1a3o12_250421系列模型
+# 上游扰流圆柱，场景与Karman_cloak_standard一致
+# obs从12逐渐减少至2，观察模型是否能够适应，具体观察量在模型名中体现
+import gymnasium as gym
+import numpy as np
+from gymnasium import spaces
+import ctypes
+from collections import deque
+from typing import Tuple
+import sys
+import os
+import matplotlib.pyplot as plt
+import queue
+
+os.environ["OMP_NUM_THREADS"] = "1"
+os.environ["MKL_NUM_THREADS"] = "1"
+
+current_dir = os.path.dirname(os.path.abspath("__file__"))
+parent_dir = os.path.abspath(os.path.join(current_dir, os.pardir))
+sys.path.append(parent_dir)
+from CelerisLab import FlowField
+from CelerisLab import utils
+
+config_cuda = utils.load_cuda_config(
+    os.path.join(parent_dir, "configs", "config_cuda.json")
+)
+config_field = utils.load_flow_field_config(
+    os.path.join(parent_dir, "configs", "config_flowfield.json")
+)
+
+S_DIM, A_DIM = 3, 3 # 这里会随着obs数量变动，在模型名中体现
+U0 = config_field.velocity
+T0 = 1000
+SAMPLE_INTERVAL = 800
+FIFO_LEN = 150
+CONV_LEN = 36
+MAX_STEPS = 500
+if config_field.data_type == "FP32":
+    DATA_TYPE = np.float32
+else:
+    raise ValueError(f"Unsupported data type {config_field.data_type}.")
+
+
+class CustomEnv(gym.Env):
+    """Custom Environment that follows gym interface."""
+
+    metadata = {"render_modes": ["human"], "render_fps": T0 / SAMPLE_INTERVAL}
+
+    def __init__(self, device_id=0):
+        super().__init__()
+        self.action_space = spaces.Box(low=-1, high=1, shape=(A_DIM,), dtype=DATA_TYPE)
+        self.observation_space = spaces.Box(
+            low=-1, high=1, shape=(S_DIM,), dtype=DATA_TYPE
+        )
+        self.fifo_states = deque(maxlen=FIFO_LEN)
+        self.target_states = np.empty((0, 6), dtype=DATA_TYPE)
+        self.force_norm_fact = 1.0
+        self.torque_norm_fact = 1.0
+        self.sens_norm_fact = np.ones(6, dtype=DATA_TYPE)
+        self.sens_deviation = np.zeros(6, dtype=DATA_TYPE)
+        self.reward_cd = 0.0
+        self.reward_cl = 0.0
+        self.reward_sim = 0.0
+        self.current_step = 0
+
+        self.flow_field = FlowField(config_field, config_cuda, device_id)
+        L0 = 20
+        U0 = config_field.velocity
+        NX = self.flow_field.FIELD_SHAPE[0]
+        NY = self.flow_field.FIELD_SHAPE[1]
+        center: Tuple[float, float, float] = (10 * L0, (NY - 1) / 2, 0)
+        self.flow_field.add_cylinder(center, L0)
+        center: Tuple[float, float, float] = (40 * L0, (NY - 1) / 2 + 2 * L0, 0)
+        self.flow_field.add_sensor(center, L0 / 4)
+        center: Tuple[float, float, float] = (40 * L0, (NY - 1) / 2, 0)
+        self.flow_field.add_sensor(center, L0 / 4)
+        center: Tuple[float, float, float] = (40 * L0, (NY - 1) / 2 - 2 * L0, 0)
+        self.flow_field.add_sensor(center, L0 / 4)
+        self.flow_field.run(int(4*NX/U0), np.zeros(4, dtype=DATA_TYPE))
+
+        for i in range(FIFO_LEN):
+            self.flow_field.run(SAMPLE_INTERVAL, np.zeros(4, dtype=DATA_TYPE))
+            new_state = self.flow_field.obs.copy()[2:8]
+            self.target_states = np.vstack((self.target_states, new_state))
+
+        # self.flow_field.apply_ddf()
+        center: Tuple[float, float, float] = (30 * L0, (NY - 1) / 2, 0)
+        self.flow_field.add_cylinder(center, L0 / 2)
+        center: Tuple[float, float, float] = (31.3 * L0, (NY - 1) / 2 + 0.75 * L0, 0)
+        self.flow_field.add_cylinder(center, L0 / 2)
+        center: Tuple[float, float, float] = (31.3 * L0, (NY - 1) / 2 - 0.75 * L0, 0)
+        self.flow_field.add_cylinder(center, L0 / 2)
+        self.flow_field.run(int(4*NX/U0), np.zeros(7, dtype=DATA_TYPE))
+        self.flow_field.get_ddf()
+        self.flow_field.save_ddf()
+
+        for i in range(FIFO_LEN):
+            self.flow_field.run(SAMPLE_INTERVAL, np.zeros(7, dtype=DATA_TYPE))
+            self.fifo_states.append(self.flow_field.obs.copy()[2:14])
+
+        temp_states = np.array(self.fifo_states)
+        self.force_norm_fact = 10 * np.max(np.abs(temp_states[:, 6:12]))
+        temp_torque = -temp_states[:, 1] - temp_states[:, 2]*np.sqrt(3)/2 + temp_states[:, 3]/2 + temp_states[:, 4]*np.sqrt(3)/2 + temp_states[:, 5]/2
+        self.torque_norm_fact = 10 * np.max(np.abs(temp_torque))
+
+        for i in range(6):
+            self.sens_deviation[i] = np.mean(temp_states[:, i])
+            self.sens_norm_fact[i] = 5 * np.max(np.abs(temp_states[:, i] - self.sens_deviation[i]))
+
+        self.flow_field.apply_ddf()
+
+        for i in range(FIFO_LEN):
+            self.flow_field.run(SAMPLE_INTERVAL, np.array([0.0, 0.0, 0.0, 0.0, 0.0, -4*U0, 4*U0], dtype=DATA_TYPE))
+            self.fifo_states.append(self.flow_field.obs.copy()[2:14])
+            
+        self.save_states = self.fifo_states.copy()
+        self.flow_field.apply_ddf()
+
+    def step(self, action):
+        assert self.action_space.contains(action), "%r (%s) invalid" % (
+            action,
+            type(action),
+        )
+
+        # barrier = threading.Barrier(2)
+        result_queue = queue.Queue()
+
+        def run_flow_field(action):
+            self.flow_field.context.push()
+            U0 = config_field.velocity
+            try:
+                temp = np.zeros(7, dtype=DATA_TYPE)
+                temp[4:7] = np.array((action*8+[0,-4,4])*U0, dtype=DATA_TYPE)
+                self.flow_field.run(SAMPLE_INTERVAL, temp)
+            finally:
+                self.flow_field.context.pop()
+            # barrier.wait()
+            self.fifo_states.append(self.flow_field.obs.copy()[2:14])
+
+        def proc_data():
+            states = np.array(self.fifo_states)
+            forces = states[-1, 6:12] / self.force_norm_fact
+            obs_torque = (-states[-1, 1] - states[-1, 2]*np.sqrt(3)/2 + states[-1, 3]/2 + states[-1, 4]*np.sqrt(3)/2 + states[-1, 5]/2) / self.torque_norm_fact
+            obs_drag = (forces[0] + forces[2] + forces[4]) / 3
+            obs_lift = (forces[1] + forces[3] + forces[5]) / 3
+            sens = (states[-1, 0:6] - self.sens_deviation) / self.sens_norm_fact
+
+            similarities = 0.0
+
+            def calc_lag(target, state):
+                target_mean = np.mean(target)
+                state_mean = np.mean(state)
+
+                correlation = np.correlate(target - target_mean, state - state_mean, "full")
+                lags = np.arange(-len(target) + 1, len(target))
+                max_lag = lags[np.argmax(correlation)]
+                return max_lag
+                
+            def calc_sim(target, state):
+
+                n = len(target)
+                m = len(state)
+                
+                dtw_matrix = np.full((n + 1, m + 1), np.inf)
+                dtw_matrix[0, 0] = 0
+                
+                for i in range(1, n + 1):
+                    for j in range(1, m + 1):
+                        cost = abs(target[i - 1] - state[j - 1])
+                        last_min = min(dtw_matrix[i - 1, j],
+                                    dtw_matrix[i, j - 1],
+                                    dtw_matrix[i - 1, j - 1])
+                        dtw_matrix[i, j] = cost + last_min
+
+                return 1 - (dtw_matrix[n, m] / len(target))
+
+            id_sens = 1
+            target_seq = self.target_states[CONV_LEN:2*CONV_LEN, id_sens]
+            state_seq = states[-CONV_LEN:, id_sens]
+            lag = calc_lag(target_seq, state_seq)
+
+            for i in range(0, 6):
+                target_seq = np.roll(self.target_states[:, i], -lag)[CONV_LEN:2*CONV_LEN]
+                state_seq = states[-CONV_LEN:, i]
+                similarities += calc_sim(target_seq, state_seq) / 6
+
+            self.reward_cd = np.exp(-np.abs(obs_drag * 20))
+            self.reward_cl = np.exp(-np.abs(obs_lift * 80))
+            self.reward_sim = np.exp(-10*np.abs(similarities - 1))
+            reward = np.minimum(0.3 * self.reward_cd + 0.3 * self.reward_cl + 0.4 * self.reward_sim, 1.0)
+            result_queue.put((np.hstack([obs_torque, forces[0:2]]), reward)) # 这里会随着obs数量变动，在模型名中体现
+
+        run_flow_field(action)
+        proc_data()
+        observation, reward = result_queue.get()
+
+        truncated = bool(np.any(observation > 1) or np.any(observation < -1))
+        observation = np.clip(observation, -1, 1)
+        self.current_step += 1
+        # done = self.current_step >= MAX_STEPS
+        done = False
+        return observation, float(reward), done, truncated, {}
+    
+    def reset(self, seed=None):
+        self.flow_field.restore_ddf()
+        self.flow_field.apply_ddf()
+        self.fifo_states = self.save_states.copy()
+        self.current_step = 0
+        return np.zeros(S_DIM, dtype=np.float32), {}
+    
+    def render(self, mode="human"):
+        NX = self.flow_field.FIELD_SHAPE[0]
+        NY = self.flow_field.FIELD_SHAPE[1]
+        self.flow_field.get_ddf()
+        ddf_plot = self.flow_field.ddf.copy().reshape((9, NY, NX)).transpose(2, 1, 0)
+        ux = (ddf_plot[:, :, 1] + ddf_plot[:, :, 5] + ddf_plot[:, :, 8] - ddf_plot[:, :, 3] - ddf_plot[:, :, 6] - ddf_plot[:, :, 7]) / U0
+        uy = (ddf_plot[:, :, 2] + ddf_plot[:, :, 5] + ddf_plot[:, :, 6] - ddf_plot[:, :, 4] - ddf_plot[:, :, 7] - ddf_plot[:, :, 8]) / U0
+        speed = np.sqrt(ux**2 + uy**2)
+        plt.figure(figsize=(10, 5))
+        plt.imshow(speed.T, origin='lower', cmap='viridis', extent=[0, NX, 0, NY])
+        plt.colorbar(label='Speed')
+        plt.title('Scalar Velocity Field')
+        plt.xlabel('X')
+        plt.ylabel('Y')
+        plt.tight_layout()
+        plt.show()
+
+    def save_field(self, filename):
+        NX = self.flow_field.FIELD_SHAPE[0]
+        NY = self.flow_field.FIELD_SHAPE[1]
+        self.flow_field.get_ddf()
+        ddf_plot = self.flow_field.ddf.copy().reshape((9, NY, NX)).transpose(2, 1, 0)
+        flag_plot = self.flow_field.flag.copy().reshape((NY, NX)).transpose(1, 0)
+        ux = (ddf_plot[:, :, 1] + ddf_plot[:, :, 5] + ddf_plot[:, :, 8] - ddf_plot[:, :, 3] - ddf_plot[:, :, 6] - ddf_plot[:, :, 7]) / U0
+        uy = (ddf_plot[:, :, 2] + ddf_plot[:, :, 5] + ddf_plot[:, :, 6] - ddf_plot[:, :, 4] - ddf_plot[:, :, 7] - ddf_plot[:, :, 8]) / U0
+        with open(os.path.join(parent_dir, "output", filename), "w") as f:
+            f.write("Title= \"LBM 2D\"\r\n")
+            f.write("VARIABLES= \"X\",\"Y\",\"flag\",\"U\",\"V\",\r\n")
+            f.write(f"ZONE T= \"BOX\",I= {NX},J= {NY},F=POINT\r\n")
+            for j in range(NY):
+                for i in range(NX):
+                    f.write(f"{i},{j},{flag_plot[i, j]},{ux[i, j]},{uy[i, j]}\r\n")
+
+    def close(self):
+        self.flow_field.__del__()