ctpwa 0.3.0__tar.gz

ctpwa-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benhou Xiang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ctpwa-0.3.0/MANIFEST.in

@@ -0,0 +1,9 @@
+# sdist 内容清单：setup.py 自动包含 ext sources (src/main.cu) 和 packages (tests)，
+# 但被 main.cu #include 的 .cu 和头文件不会自动包含——必须显式列出，
+# 否则其他机器 pip install 编译失败。
+recursive-include include *.cuh *.h
+recursive-include src *.cu *.cuh *.h
+recursive-include tests *.py *.yml *.txt *.dat *.sh
+recursive-include doc *
+recursive-include example *.py *.yml *.md
+include README.md LICENSE

ctpwa-0.3.0/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.1
+Name: ctpwa
+Version: 0.3.0
+Summary: CUDA-Torch Partial Wave Analysis
+Author: Benhou Xiang
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: C++
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: pyyaml>=5.4.0
+
+A partial wave analysis packages with  theory of covariant tensor and tools of CUDA and Torch.

ctpwa-0.3.0/README.md

@@ -0,0 +1 @@
+A partial wave analysis packages with  theory of covariant tensor and tools of CUDA and Torch.

ctpwa-0.3.0/ctpwa.egg-info/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.1
+Name: ctpwa
+Version: 0.3.0
+Summary: CUDA-Torch Partial Wave Analysis
+Author: Benhou Xiang
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: C++
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: pyyaml>=5.4.0
+
+A partial wave analysis packages with  theory of covariant tensor and tools of CUDA and Torch.

ctpwa-0.3.0/ctpwa.egg-info/SOURCES.txt

@@ -0,0 +1,63 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+setup.py
+ctpwa.egg-info/PKG-INFO
+ctpwa.egg-info/SOURCES.txt
+ctpwa.egg-info/dependency_links.txt
+ctpwa.egg-info/requires.txt
+ctpwa.egg-info/top_level.txt
+doc/hessian_formula.md
+doc/hessian_status.md
+example/config.yml
+example/fit.py
+example/plot.py
+include/AmpGen.cuh
+include/Amplitude.cuh
+include/AutoDiff.cuh
+include/ComplexType.h
+include/ComputeBF.cuh
+include/ComputeHessian.cuh
+include/ComputeNLL.cuh
+include/ComputeResults.cuh
+include/Config.cuh
+include/DeviceManager.cuh
+include/Figure.cuh
+include/Info.cuh
+include/Parameters.cuh
+include/ResModel.cuh
+include/Resonance.cuh
+src/AmpGen.cu
+src/Amplitude.cu
+src/Analysis.cu
+src/ComputeBF.cu
+src/ComputeHessian.cu
+src/ComputeNLL.cu
+src/ComputeResults.cu
+src/Config.cu
+src/DeviceManager.cu
+src/Figure.cu
+src/Info.cu
+src/Parameters.cu
+src/ResModel.cu
+src/Resonance.cu
+src/main.cu
+tests/__init__.py
+tests/conftest.py
+tests/fit_benchmark.py
+tests/generate_test_data.py
+tests/prepare_real_data.py
+tests/run_tests.sh
+tests/test_endtoend.py
+tests/test_numerical.py
+tests/test_structure.py
+tests/update_golden.py
+tests/configs/no_trans.yml
+tests/configs/simple.yml
+tests/configs/with_trans.yml
+tests/data/test_data.dat
+tests/data/test_phsp.dat
+tests/data/test_sideband.dat
+tests/golden/grad_simple.txt
+tests/golden/nll_simple.txt

ctpwa-0.3.0/ctpwa.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ctpwa-0.3.0/ctpwa.egg-info/requires.txt

@@ -0,0 +1,2 @@
+numpy>=1.20.0
+pyyaml>=5.4.0

ctpwa-0.3.0/ctpwa.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+ctpwa
+tests

ctpwa-0.3.0/doc/hessian_formula.md

@@ -0,0 +1,215 @@
+# Hessian 公式备忘录
+
+> 已验证精度：vv, vθ, θv, θθ 四个 block 与 PyTorch autograd 差异 < 1.2×10⁻⁶
+
+## 1. NLL 定义
+
+$$
+\text{NLL} = -\sum_{\text{data}} \log I_e + w_{\text{bkg}} \sum_{\text{bkg}} \log I_e + A \cdot \log(\text{pf})
+$$
+
+其中：
+
+- $A = N_{\text{data}} - \int_{\text{bkg}}$ （phsp 项的系数）
+- $\text{pf} = \frac{1}{N_{\text{phsp}}} \sum_{e \in \text{phsp}} I_e$
+- $I_e = \sum_p |S_{e,p}|^2$ （所有极化求和）
+- $S_{e,p} = \sum_a v_a \cdot \text{amp}_{a,e,p}$ （所有 channel 求和）
+- $\text{amp}_{a,e,p} = SL_{a,e,p} \cdot R_{\text{res}(a),e}(\theta) \cdot bf$ （完整振幅）
+
+## 2. Per-event 量定义
+
+### 2.1 基本量
+
+| 符号 | 定义 | 含义 |
+|------|------|------|
+| $S[p]$ | $\sum_a v_a \cdot \text{amp}_a[p]$ | 每个极化的复振幅 |
+| $I$ | $\sum_p (S_{\text{re}}[p]^2 + S_{\text{im}}[p]^2)$ | 每个事件的强度 |
+| $1/I$ | | 逆强度 |
+
+### 2.2 一阶导数
+
+| 符号 | 公式 | 含义 |
+|------|------|------|
+| $\partial S/\partial v_a^{\text{re}}$ | $\text{amp}_a$ | S 对耦合实部的导数 |
+| $\partial S/\partial v_a^{\text{im}}$ | $i \cdot \text{amp}_a$ | S 对耦合虚部的导数 |
+| $dS_j[p]$ | $\partial S[p]/\partial\theta_j$ | S 对共振态参数的导数 |
+| $\partial I/\partial v_a^{\text{re}}$ | $2 \cdot \text{Re}(\text{conj}(S) \cdot \text{amp}_a)$ | I 对耦合实部的导数 |
+| $\partial I/\partial v_a^{\text{im}}$ | $-2 \cdot \text{Im}(\text{conj}(S) \cdot \text{amp}_a)$ | I 对耦合虚部的导数 |
+| $\partial I/\partial\theta_j$ | $2 \cdot \text{Re}(\text{conj}(S) \cdot dS_j)$ | I 对共振态参数的导数 |
+
+### 2.3 二阶导数
+
+| 符号 | 公式 | 含义 |
+|------|------|------|
+| $\partial^2 I/\partial v_a^{\text{re}}\partial\theta_j$ | $2 \cdot \text{Re}(\text{conj}(dS_j) \cdot \text{amp}_a + \text{conj}(S) \cdot \partial\text{amp}_a/\partial\theta_j)$ | 混合二阶导数（实部） |
+| $\partial^2 I/\partial v_a^{\text{im}}\partial\theta_j$ | $-2 \cdot \text{Im}(\text{conj}(dS_j) \cdot \text{amp}_a + \text{conj}(S) \cdot \partial\text{amp}_a/\partial\theta_j)$ | 混合二阶导数（虚部） |
+| $\partial\text{amp}_a/\partial\theta_j$ | $SL_a \cdot \partial R_{\text{res}(a)}/\partial\theta_j$ | 振幅对 θ 的导数（同块非零，跨块为零） |
+
+### 2.4 Per-event 梯度
+
+| 符号 | 公式 | 含义 |
+|------|------|------|
+| $g_j$ | $-\frac{2}{I} \cdot \text{Re}(\text{conj}(S) \cdot dS_j)$ | $\partial(-\log I)/\partial\theta_j$（per-event，无权重） |
+| $g_a^{(v,\text{re})}$ | $-\frac{2}{I} \cdot \text{Re}(\text{conj}(S) \cdot \text{amp}_a)$ | $\partial(-\log I)/\partial v_a^{\text{re}}$ |
+| $g_a^{(v,\text{im})}$ | $+\frac{2}{I} \cdot \text{Im}(\text{conj}(S) \cdot \text{amp}_a)$ | $\partial(-\log I)/\partial v_a^{\text{im}}$ |
+
+## 3. Hessian 公式（data + bkg）
+
+每事件带权重 $w_e$（data=+1, bkg=-w_b）：
+
+### 3.1 vv Block（由 PyTorch autograd 计算）
+
+$H_{vv} = \partial^2\text{NLL}/\partial v\partial v$，由 `NLLFunction` 的 autograd 自动计算。
+
+### 3.2 θθ Block
+
+对每个事件 $e$，per-event Hessian：
+
+$$
+h_{jk} = g_j \cdot g_k - \frac{2}{I} \cdot \text{Re}(\text{conj}(dS_k) \cdot dS_j) - \frac{2}{I} \cdot \text{Re}(\text{conj}(S) \cdot d^2S_{jk})
+$$
+
+三项分别称为 **Term A**（外积）、**Term B**（$|dS|^2$ 修正）、**Term C**（$d^2S$ 修正，仅同块非零）。
+
+总 θθ Hessian：
+
+$$
+H_{\theta\theta}[j,k] = \sum_e w_e \cdot h_{jk}^{(e)}
+$$
+
+### 3.3 vθ / θv Block（混合 Hessian）
+
+对每个振幅 $a$ 和共振态参数 $j$（同块，即 $a$ 和 $\theta_j$ 属于同一 resonance）：
+
+$$
+\begin{aligned}
+H_{v_a^{\text{re}}, \theta_j} &= -\frac{2w_e}{I} \cdot \Big[\text{Re}(\text{conj}(dS_j) \cdot \text{amp}_a) + \text{Re}(\text{conj}(S) \cdot \partial\text{amp}_a/\partial\theta_j) + g_j \cdot \text{Re}(\text{conj}(S) \cdot \text{amp}_a)\Big] \\
+&= -\frac{2w_e}{I} \cdot \big[\text{Term1}_{\text{re}} + \text{Term2}_{\text{re}} + g_j \cdot \text{Term3}_{\text{re}}\big]
+\end{aligned}
+$$
+
+$$
+H_{v_a^{\text{im}}, \theta_j} = +\frac{2w_e}{I} \cdot \big[\text{Term1}_{\text{im}} + \text{Term2}_{\text{im}} + g_j \cdot \text{Term3}_{\text{im}}\big]
+$$
+
+对跨块（$a$ 和 $\theta_j$ 属于不同 resonance）：Term2 = 0（因为 $\partial\text{amp}_a/\partial\theta_j = 0$），只用 Term1 + Term3。
+
+---
+
+**Term1, Term2, Term3 定义：**
+
+| 项 | 实部公式 | 虚部公式 |
+|----|---------|---------|
+| Term1 | $\text{Re}(\text{conj}(dS_j) \cdot \text{amp}_a)$ | $\text{Im}(\text{conj}(dS_j) \cdot \text{amp}_a)$ |
+| Term2 | $\text{Re}(\text{conj}(S) \cdot SL_a \cdot \partial R/\partial\theta_j)$ | $\text{Im}(\text{conj}(S) \cdot SL_a \cdot \partial R/\partial\theta_j)$ |
+| Term3 | $\text{Re}(\text{conj}(S) \cdot \text{amp}_a)$ | $\text{Im}(\text{conj}(S) \cdot \text{amp}_a)$ |
+
+---
+
+## 4. Phsp 贡献
+
+### 4.1 θθ Block
+
+Phsp 项 $L_{\text{phsp}} = A \cdot \log(\text{pf})$，其中 $\text{pf} = \frac{1}{N_{\text{phsp}}} \sum_{e \in \text{phsp}} I_e$。
+
+$$
+\frac{\partial^2 L_{\text{phsp}}}{\partial\theta_j\partial\theta_k} = c_1 \cdot \Sigma_{\text{phsp}}[I \cdot (g_j g_k - h_{jk})] + c_2 \cdot (\Sigma I g_j) \cdot (\Sigma I g_k)
+$$
+
+其中：
+- $c_1 = \dfrac{A}{\text{pf} \cdot N_{\text{phsp}}}$
+- $c_2 = -\dfrac{A}{\text{pf}^2 \cdot N_{\text{phsp}}^2}$
+
+### 4.2 vθ Block
+
+Phsp 对混合 Hessian 的贡献：
+
+$$
+\frac{\partial^2 L_{\text{phsp}}}{\partial v_a^{\text{re}}\partial\theta_j} = c_{1m} \cdot \Sigma_{\text{phsp}}(\text{Term1}_{\text{re}} + \text{Term2}_{\text{re}}) + c_{2m} \cdot \big(\Sigma_{\text{phsp}} \text{Term3}_{\text{re}}^{(a)}\big) \cdot \big(\Sigma_{\text{phsp}} I \cdot g_j\big)
+$$
+
+$$
+\frac{\partial^2 L_{\text{phsp}}}{\partial v_a^{\text{im}}\partial\theta_j} = -\Big[c_{1m} \cdot \Sigma_{\text{phsp}}(\text{Term1}_{\text{im}} + \text{Term2}_{\text{im}}) + c_{2m} \cdot \big(\Sigma_{\text{phsp}} \text{Term3}_{\text{im}}^{(a)}\big) \cdot \big(\Sigma_{\text{phsp}} I \cdot g_j\big)\Big]
+$$
+
+其中：
+- $c_{1m} = \dfrac{2A}{\text{pf} \cdot N_{\text{phsp}}}$
+- $c_{2m} = \dfrac{2A}{\text{pf}^2 \cdot N_{\text{phsp}}^2}$
+
+> **注意**：$c_{1m}$ 和 $c_{2m}$ 都有因子 2（与 θθ 的 $c_1, c_2$ 不同），这是因为 $\partial I/\partial v = 2 \cdot \text{Term3}$，而 $\partial I/\partial\theta = -I \cdot g$。
+
+---
+
+## 5. CUDA 实现结构
+
+### 5.1 Kernel 流水线
+
+```
+Pre-pass: computeSfromAmpsKernel
+  → 计算 S[p], I, 以及 Term3（用于 phsp vθ）
+
+Stage 1: hessianStage1Kernel<Npr, Nres>  (per-block, per-event)
+  → 输出 per-event g_j, dS_j, ∂F/∂θ_j
+  → 累加同块 θθ Hessian
+  → 累加 phsp: I·g, I·(g⊗g - h)
+
+Stage 2: hessianCrossBlockKernel
+  → 跨块 θθ Hessian（仅 Term A + Term B）
+
+Stage 3: hessianMixedBlockKernel  (per-block)
+  → 同块 vθ Hessian（Term 1 + 2 + 3）
+  → phsp path: 写 Term1+Term2 到 h_sum，Term3 由 pre-pass 计算
+
+Stage 4: hessianCrossMixedKernel
+  → 跨块 vθ Hessian（仅 Term 1 + 3，Term2=0）
+  → phsp path: 写 Term1 到 h_sum（Term3 已由 pre-pass 计算，不重复）
+```
+
+### 5.2 关键注意点
+
+- **Pre-pass 计算完整 S**：Stage 1 不自己算 S，而是从 pre-pass 读入。确保 S 包含所有 channel 的贡献（不仅是本块的）。
+- **Term3（t3）在 pre-pass 统一计算**：Term3 是 per-amplitude 的量，与具体哪个 θ block 无关。在 pre-pass 中一次性计算所有 SL channel 的 Term3，避免 stage 3 和 stage 4 重复累加。
+- **跨块 Term2 = 0**：对于 $a \in \text{block A}, \theta_j \in \text{block B}$，$\partial\text{amp}_a/\partial\theta_j = 0$，因此 Term2 不参与跨块贡献。
+- **Phsp 的 is_phsp 判断**：`default_weight == 0.0 && d_phsp_sum != nullptr` 时走 phsp 路径，写入独立 buffer（非 d_mixed）。
+- **所有 resonance 必须注册到 blocks_**：即使没有 free params，其 SL channels 也需要参与跨块 vθ 计算（stage 4）。
+
+### 5.3 符号约定
+
+| ctpwa | 数学含义 |
+|-------|---------|
+| `g[j]` | $-\partial(\log I)/\partial\theta_j$（无权重） |
+| `d_dS_re[j][p]` | $\text{Re}(\partial S[p]/\partial\theta_j)$ |
+| `d_dS_im[j][p]` | $\text{Im}(\partial S[p]/\partial\theta_j)$ |
+| `d_dF_re[a][j]` | $\text{Re}(\partial R_{\text{res}(a)}/\partial\theta_j)$ |
+| `d_dF_im[a][j]` | $\text{Im}(\partial R_{\text{res}(a)}/\partial\theta_j)$ |
+| `d_phsp_I` | $\Sigma_{\text{phsp}} I_e$ |
+| `d_phsp_grad[j]` | $\Sigma_{\text{phsp}} I_e \cdot g_j^{(e)}$ |
+| `d_phsp_hessA[j][k]` | $\Sigma_{\text{phsp}} I_e \cdot (g_j g_k - h_{jk})$ |
+| `d_phsp_mixed_sum[a][j]` | $\Sigma_{\text{phsp}}(\text{Term1} + \text{Term2})_{a,j}$ |
+| `d_phsp_mixed_t3[a]` | $\Sigma_{\text{phsp}} \text{Term3}_a$（由 pre-pass 计算） |
+
+### 5.4 约束投影
+
+在 vv 和 vθ block 计算完成后，需要将 extended parameter space 的结果投影到 free parameter space：
+
+对于实部约束：$v_{\text{ext}}[e] = rr \cdot v_{\text{free}}[\text{oid}] + \cdots$
+
+$$
+H_{\text{free}}[\text{oid}, :] \mathrel{+}= rr \cdot H_{\text{ext}}[e, :] + ir \cdot H_{\text{ext}}[n_{\text{ext}} + e, :]
+$$
+$$
+H_{\text{free}}[n_{\text{free}} + \text{oid}, :] \mathrel{+}= -ir \cdot H_{\text{ext}}[e, :] + rr \cdot H_{\text{ext}}[n_{\text{ext}} + e, :]
+$$
+
+---
+
+## 6. 验证结果
+
+| Block | 1-res（1 个自由共振态） | 2-res（2 个自由共振态） |
+|-------|------------------------|------------------------|
+| vv | 7.73×10⁻⁷ | 7.73×10⁻⁷ |
+| vθ | 2.89×10⁻⁷ | 3.18×10⁻⁷ |
+| θv | 2.89×10⁻⁷ | 3.18×10⁻⁷ |
+| θθ | 8.95×10⁻⁷ | 1.18×10⁻⁶ |
+
+测试条件：1 data event, 3 phsp events, 1 bkg event, 9 polarizations, BWR×2 resonances。

ctpwa-0.3.0/doc/hessian_status.md

@@ -0,0 +1,52 @@
+# Hessian 多共振态修复状态报告
+
+## 已验证（正确）
+
+1. **AutoDiff BWR Hessian** (`Var<double,N,true>`): 与 PyTorch autograd 精确一致 (<1e-15)
+2. **Per-event Hessian 公式**: 在 Python 中与 PyTorch 完全匹配
+   ```
+   g[j] = -2·bf·Re(D^j · Σ conj(w)·T)
+   H = g·g^T - 2·I_inv·bf²·Σ|T|²·Re(conj(D_k)·D_j) - 2·bf·Re(Σ conj(w)·T · D²_jk)
+   ```
+3. **单共振态**: getHessian 与 PyTorch 匹配 (rel < 1e-7)
+4. **θθ 交叉块公式**: H_rs = g_r·g_s^T (只有外积，无 d²S 修正项)
+
+## 当前代码状态 (hessian-research 分支)
+
+### 已修改
+- `resonanceHessianBlockKernel` Step 5: 替换为 per-event 聚合公式
+- `computeResonanceHessian`: 替换为直接调用 BlockKernel（移除 3-pass）
+- `getHessian`: 添加 computeEffectiveCoupling 调用
+- `d_v[site+sl_idx]`: double-offset 修复（3个kernel）
+
+### 未解决
+1. **符号/权重**: data 的 sign 是 +1 还是 -1 需要和 NLL 公式对齐
+2. **bkg 权重**: 每个 bkg event 需要独立的 w_evt 权重传入 kernel
+3. **PHSP 对 θθ 的贡献**: 完全缺失
+4. **vθ 混合块**: 暂填零（单链模型下正确，多链需要实现）
+
+## 建议方案
+
+### 短期（最小修改让当前代码工作）
+在 `getHessian` 里 per-event 循环调用 `computeResonanceHessian` 时传入正确的 w_evt:
+- data: w_evt = -1
+- bkg: w_evt 从 bkg_weights_ 读取（正权重 → 负贡献）
+- 然后将 kernel 里的 `sign` 参数统一为 +1，外积和修正都用 `w_evt * (...)` 格式
+
+### 长期（推荐架构）
+```
+computeResonanceHessian() {
+    for each event:
+        1. 计算 S = A*v, I = |S|², w = S/I
+        2. for each resonance r:
+            计算 g_r, H_rr (per-event)
+            H_total += w_evt * H_rr  
+            存储 g_r 到 per-event buffer
+        3. for each pair (r,s) where r≠s:
+            H_total += w_evt * g_r ⊗ g_s^T
+        4. PHSP 贡献: H += n_data * ∂²log(phsp_factor)/∂θ²
+}
+```
+
+### 如果重新开始
+用 Python 先写完整的多共振态 NLL + Hessian，验证公式完全对上后，再逐块翻译成 CUDA kernel。避免在 C++ 里反复编译调试。

ctpwa-0.3.0/example/config.yml

@@ -0,0 +1,148 @@
+# ============================================================
+# ctpwa config.yml — compact format
+# ============================================================
+# 衰变链支持两种写法：
+#   紧凑格式（推荐）:
+#     chain_name:
+#       mother:
+#         - [daughter1, intermediate]      # 含中间态
+#         - [daughter2, intermediate]
+#       intermediate: [d1, d2]             # 中间态衰变
+#
+#       intermediates:                     # 中间态共振态配置
+#         intermediate:
+#           - [J: 1, P: -1]: [res1, res2]
+#   展开格式 (等价):
+#     chain_name:
+#       decay:
+#         - mother: [daughter1, intermediate]
+#         - intermediate: [d1, d2]
+#       intermediate:
+#         - [J: 1, P: -1]: [res1, res2]
+#
+# 约束:
+#   trans: 跨链全同约束。[chain_substr_A, chain_substr_B]: ratio
+#   identical: 全同粒子组，自动施加 (-1)^{L+S} 选择定则
+#   maxL: 全局轨道角动量上限
+# ============================================================
+
+Particles:
+  Jpsi:
+    J: 1; P: -1; mass: 3.0969
+    # polarization: [1, -1]  # 横极化 (仅 m=±1)
+    tex: ['J/\\psi']
+  eta:
+    J: 0; P: -1; mass: 0.5478
+    tex: ['\\eta']
+  Kp:
+    J: 0; P: -1; mass: 0.4937
+    tex: ['K^{+}']
+  Km:
+    J: 0; P: -1; mass: 0.4937
+    tex: ['K^{-}']
+
+Data:
+  order: [Kp, Km, eta]
+  data:  [dat, "./data.dat"]
+  phsp:  [dat, "./phsp.dat"]
+  # bkg:   [dat, "./bkg.dat"]
+  # bkg_weights: [dat, "./bkg_weights.dat"]
+
+  # 使用root文件 （TBranch名字与order中粒子名字顺序一致）
+  # data: [ROOT, "/file.root", TTree, TBranch1, TBranch2, TBranch3, ...]
+  # phsp: [ROOT, "/file.root", TTree, TBranch1, TBranch2, TBranch3, ...]
+  # bkg:  [ROOT, "/file.root", TTree, TBranch1, TBranch2, TBranch3, ...]
+  # bkg_weights: [ROOT, "/file.root", TTree, TBranch1(weight)]
+  # 也可混合使用
+
+# ============================================================
+# 衰变链: J/psi → eta KK / Kp Keta / Km Keta
+# BFS 自动展开所有中间态 J^P 组合 × 共振态组合
+# ============================================================
+DecayChains:
+  decay1:
+    Jpsi: 
+      - [eta, R_KK] # [eta, R_KK, {if some requirement, like p_break: true}]
+      - [Kp, R_Kpeta]
+      - [Km, R_Kmeta]
+    R_KK: [Kp, Km]
+    R_Kpeta: 
+      - [Kp, eta] # R_Keta_0      
+      - [Km, eta] # R_Keta_1
+
+    intermediates:
+      R_KK:
+        - [J: 1, P: -1]: [phi1020, omega1420]
+        - [J: 3, P: -1]: [omega3_1670]
+      R_Keta:
+        - [J: 1, P: -1]: [K1_1410]
+        - [J: 2, P: +1]: [K2_1430]
+    legends:
+      - ['R_KK', ' \\to ', 'eta']         # chain 0: R_KK 的第0个共振态
+      - ['R_Keta_0', ' \\to ', 'Kp']       # chain 1
+      - ['R_Keta_1', ' \\to ', 'Km']       # chain 2
+
+Constraints:
+  # R_Keta_0 和 R_Keta_1 通过 trans 约束共享参数（互为相反数）
+  trans:
+    - [R_Keta_0, R_Keta_1]: -1
+  # 全局参数
+  # maxL: 4
+  bf_d: 3.0
+
+# ============================================================
+# 共振态配置
+# model: BWR (Breit-Wigner), Flatte, ONE (常数), BWR_Bf (含势垒)
+# free: 自由参数下标，-1 表示全部自由
+# free_range: 自由参数拟合范围
+# ============================================================
+Resonances:
+  # ---- R_KK 共振态 ----
+  phi1020:
+    J: 1; P: -1; model: BWR
+    parameters: [1.0195, 0.0045]
+    tex: ["\\phi(1020)"]
+
+  omega1420:
+    J: 1; P: -1; model: BWR
+    parameters: [1.41, 0.35]
+    tex: ["\\omega(1420)"]
+
+  omega3_1670:
+    J: 3; P: -1; model: BWR
+    parameters: [1.667, 0.168]
+    tex: ["\\omega_{3}(1670)"]
+
+  # ---- R_Keta 共振态 (Kpi) ----
+  K1_1410:
+    J: 1; P: -1; model: BWR
+    parameters: [1.414, 0.232]
+    tex: ["K_{1}(1410)"]
+
+  K2_1430:
+    J: 2; P: +1; model: BWR
+    parameters: [1.432, 0.109]
+    tex: ["K_{2}^{*}(1430)"]
+
+# ============================================================
+# ROOT 输出绘图
+# ============================================================
+Plot:
+  mass:
+    - input: [Kp, Km]
+      bins: 100; range: [1.0, 2.6]
+      display: ["M(K^{+}K^{-}) (GeV/c^{2})", "Events/16 MeV/c^{2}"]
+    - input: [Kp, eta]
+      bins: 100; range: [1.0, 2.6]
+      display: ["M(K^{+}\\eta) (GeV/c^{2})", "Events/16 MeV/c^{2}"]
+    - input: [Km, eta]
+      bins: 100; range: [1.0, 2.6]
+      display: ["M(K^{-}\\eta) (GeV/c^{2})", "Events/16 MeV/c^{2}"]
+  cosbeta:
+    - input: [[Jpsi], [Kp, Km], [Kp]]
+      bins: 100; range: [-1.0, 1.0]
+      display: ["cos\\beta(K^{+}K^{-})", "Events/0.02"]
+  dalitz:
+    - input: [[Kp, Km], [Kp, eta]]
+      bins: [100, 100]; range: [[1.0, 6.8], [1.0, 6.8]]
+      display: ["M^{2}(K^{+}K^{-}) (GeV^{2}/c^{4})", "M^{2}(K^{+}\\eta) (GeV^{2}/c^{4})"]