DynamisLab/docs/ccd_handover.md

CCD Direction Handover

Agent Background

This agent worked on the CCD (Canonical Correlation Decomposition) analysis pipeline for the DynamisLab fluidic pinball project. The work spanned approximately 7-8 hours over 2026-06-14/15, covering Round 5 (raw-field baseline) and Round 6 (correction-field framework).

Work Summary

What was accomplished

1. Data pipeline overhaul: Replaced the old resampled.npz (interpolated) format with fields_aligned.npz (96 non-interpolated raw field snapshots) + phase_plan.json. Implemented load_aligned_fields() in utils/resampling.py as the unified data loader.

2. Raw-field CCD baseline (Round 5): ccd/run_ccd.py and ccd/validate.py rewritten for the new data format. Target-only POD basis, per-force observable (SigmaFy primary), Q_delay=6, per-case z-score. 90 CCD entries, LOCO validation passed for force_fy (R2 0.66-0.71).

3. Correction-field framework (Round 6): Shifted analysis object from q_ctl to dq_ctl = q_ctl - q_blk (the control correction field). Built correction_analysis/compute_correction_fields.py for unified q_in/q_blk/q_ctl/q_tar + dq_* field computation.

4. Completed analyses in round 6:

   • Force/action CCD on dq_ctl (0.75L, 1.0L)
   • Signature line CCD (0.75L, 1.0L) with tau scan (0, geom, corr)
   • 1.5L force/action/signature CCD + phase drift diagnostics
   • Steady cloak quantitative metrics
   • Zone-restricted CCD (near_body, body_wake, sensor_zone) for 0.75L and 1.0L
   • Snapshot POD speedup (SVD on 96x96 instead of 1310720x96)

5. Karman reference data collected: karman_q_in (vortex street without pinball) and karman_q_blk (pinball in vortex street, no control) — both 96 aligned frames.

6. Documentation:

   • docs/ccd_correction_field_report.md — comprehensive 412-line report explaining everything from scratch, including 10-figure reading guide
   • docs/sr_ccd_oid_mapping.md — cross-pipeline mapping (DRAFT - needs verification from SR and OID directions)
   • src/CCD_analysis/ccd_knowledge.md — updated with final results
   • src/CCD_analysis/ccd_notes.md — updated with completion status

Key findings

1. 1.0L: O(dqctl, dqtar)=0.913, force_fy m80=1 — the controller's correction nearly perfectly matches the target's required correction, and it's highly concentrated.

2. Force vs Signature separation: O(force,sig)=0.41-0.55 at tau=0 (separated), rising to 0.77-0.81 at tau=tau_c (shared). Zone-CCD shows 0.75L sensor_zone has O=0.01 at tau=0 (near orthogonal) and body_wake has O=0.917 at tau=tau_c.

3. 1.5L special mechanism: O=0.667, action sigma1=0.28 (1/4 of others), strong phase drift, correction concentrated near-body.

What is not done

1. Karman cloak analysis — data is ready (q_in, q_blk, q_ctl all have fields_aligned.npz), correction-field framework supports it, but analysis was deferred. Different physical question: distortion compensation vs target generation.

2. 1.5L force-vs-signature overlap — 0.75L and 1.0L have O(force,sig) values, 1.5L has signature m80 but no overlap comparison.

3. SR-CCD-OID mapping — docs/sr_ccd_oid_mapping.md was written without reading SR and OID reports. Needs correction.

4. Mixed-basis sensitivity — deferred sensitivity check (currently target-only basis).

Quick Start for Your First Commands

# Read the comprehensive report
less docs/ccd_correction_field_report.md

# Read the knowledge base
less src/CCD_analysis/ccd_knowledge.md

# Explore results
ls src/CCD_analysis/data/ccd/*.json
python3 -c "import json; r=json.load(open('src/CCD_analysis/data/ccd/correction_ccd_results.json')); print(f'{len(r)} entries'); [print(k) for k in list(r.keys())[:5]]"

# Check available figures
ls src/CCD_analysis/data/figures/*.png | wc -l

Environment

• All CPU analysis: conda run -n pycuda_3_10
• GPU collection: same environment, devices 2 or 3
• LegacyCelerisLab (FlowField) needed for GPU scripts
• Python 3.10+, numpy, matplotlib, scipy (via conda)
• sys.path.insert(0, 'src') needed for imports