13. 常见错误排查¶

CRANE有一套非常完善的错误排查机制，该机制由外向内分为以下三层：

基于 PyYAML 库，直接排查用户输入文件中的 YAML 格式错误；
基于 python-jsonschema 库，通过CRANE自带的用户输入规则配置文件，排查用户输入文件中的输入内容规则错误；
基于CRANE的C++错误处理模块，排查几何建模及计算过程中出现的运行时错误，如几何区域重叠错误等。

13.1. YAML 格式错误¶

YAML 格式错误是由于在用户输入文件中的内容不满足 YAML 格式要求，比较常见的问题有：

缩进错误： YAML 是通过缩进来表示层级关系的，因此在编写时需要确保正确的缩进。使用空格或者制表符缩进，但不能混用。常见的是使用两个空格作为缩进；
键值对格式错误：键值对之间使用冒号 : 分隔， 冒号后面需要加上一个空格，同时键值对的值需要适当地使用引号包裹，特别是包含特殊字符时，或者是字符串值；
列表格式错误：展开的列表开头需要加 -，列表项之间需要统一的缩进，列表项也可以是单个值或者是键值对；
引用错误：使用 & 和 * 符号可以进行变量引用，但是在使用时要注意引用的正确性和范围。
注释错误：使用 # 符号来表示注释，注释只能出现在一行的开头或者键值对的末尾；

Note

如果在专业的文本编辑工具上编辑 YAML 文件，许多格式错误本身就可以通过内容的颜色来区分，我们推荐使用 VScode 作为用户输入文件的编辑器。

这里以缩进错误为示例，若我们在 C5G7_2D 基准题中第一个材料的 sigma_tr 输入时缩进没有对齐：

materials:
  - name: UO2                             
      sigma_tr: [1.77949E-01, 3.29805E-01, 4.80388E-01, 5.54367E-01, 3.11801E-01, 3.95168E-01, 5.64406E-01,]
    sigma_f: [7.21206E-03, 8.19301E-04, 6.45320E-03, 1.85648E-02, 1.78084E-02, 8.30348E-02, 2.16004E-01,]
    nu_sigma_f: [2.00600E-02, 2.02730E-03, 1.57060E-02, 4.51830E-02, 4.33420E-02, 2.02090E-01, 5.25710E-01,]
    kappa_sigma_f: [7.21206E-03, 8.19301E-04, 6.45320E-03, 1.85648E-02, 1.78084E-02, 8.30348E-02, 2.16004E-01,]
    chi: [5.87910E-01, 4.11760E-01, 3.39060E-04, 1.17610E-07, 0.00000E+00, 0.00000E+00, 0.00000E+00,]
    sigma_s: [
      1.27537E-01, 4.23780E-02, 9.43740E-06, 5.51630E-09, 0.00000E+00, 0.00000E+00, 0.00000E+00,
      0.00000E+00, 3.24456E-01, 1.63140E-03, 3.14270E-09, 0.00000E+00, 0.00000E+00, 0.00000E+00,
      0.00000E+00, 0.00000E+00, 4.50940E-01, 2.67920E-03, 0.00000E+00, 0.00000E+00, 0.00000E+00,
      0.00000E+00, 0.00000E+00, 0.00000E+00, 4.52565E-01, 5.56640E-03, 0.00000E+00, 0.00000E+00,
      0.00000E+00, 0.00000E+00, 0.00000E+00, 1.25250E-04, 2.71401E-01, 1.02550E-02, 1.00210E-08,
      0.00000E+00, 0.00000E+00, 0.00000E+00, 0.00000E+00, 1.29680E-03, 2.65802E-01, 1.68090E-02,
      0.00000E+00, 0.00000E+00, 0.00000E+00, 0.00000E+00, 0.00000E+00, 8.54580E-03, 2.73080E-01,
    ]

这时我们运行CRANE会出现以下错误：

错误的详细信息会在最后显示（图中白色背景部分），对于 YAML 格式错误，除了提示是什么错误，还会给出错误发生的位置，几行几列。

13.2. 输入内容规则错误¶

输入内容规则错误是由于用户输入文件中的内容不满足用户输入规则配置文件中定义的规则。

比如 structure 对象必须要包含 primitives，若不满足该规则程序就会报错。

这里我们在 VERA_2A 基准题中把 primitives 的 p 改成大写：

geometries:
  structures:
  - name: F31
    Primitives:  # primitives --> Primitives
    - {type: CIRCLE, radius: 0.4096}
    - {type: CIRCLE, radius: 0.4180}
    - {type: CIRCLE, radius: 0.4750}
    regions:
    - {material: Fuel_31, space: '1'}
    - {material: Helium, space: 2-1}
    - {material: Zircaloy-4, space: 3-2}
    meshing: {type: SECTORS, num_azimuths: 4, radii: [0.2365, 0.3344, -0.4750, 0.5800]}

这时我们运行CRANE会出现以下错误：

除了给出是什么错误的信息外，还会以 JSON Path 的形式给出错误发生的具体位置。如上图中错误信息中给出的是在根目录下的 geometries 对象下的第1个（0是最开头） structure 对象中缺少 primitives，因为我们把 primitives 改成了 Primitives。

Note

用户输入文件中所有的内容都是大小写相关的。

13.3. 运行时错误¶

若 YAML 格式错误和输入内容规则错误都没有发生，才会进入到CRANE运行，如进行几何建模、输运计算等等。此时若再出现错误，则为运行时错误。

13.3.1. 单个几何结构体内区域重叠错误¶

在定义 structure 对象时，其材料区是通过 regions 来定义的，如果几个材料区之间存在区域重叠，则会给出几何结构体内的区域重叠错误。

如我们在 VERA_2A 基准题中，将燃料棒定义两个重复的气隙区域 2-1：

geometries:
  structures:
  - name: F31
    primitives:
    - {type: CIRCLE, radius: 0.4096}
    - {type: CIRCLE, radius: 0.4180}
    - {type: CIRCLE, radius: 0.4750}
    regions:
    - {material: Fuel_31, space: '1'}
    - {material: Helium, space: 2-1}
    - {material: Helium, space: 2-1}  # add another gap region
    - {material: Zircaloy-4, space: 3-2}
    meshing: {type: SECTORS, num_azimuths: 4, radii: [0.2365, 0.3344, -0.4750, 0.5800]}

这时我们运行CRANE会出现以下错误：

../_images/error_region_overlap_in_structure.png

该错误信息会给出哪个 structure 对象发生了区域重叠，重叠的是哪些区域。

13.3.2. 几何结构体之间区域重叠错误¶

不同的几何结构体定义好了之后，CRANE会根据 lattice 对象、grid 对象等包含的布置图信息或者 structure_location 对象来排布不同的几何结构体，如果这时发生不同几何结构体之间的区域重叠，也会报错。

如我们在 VERA_2A 基准题中，将中心测量管的外径由 0.605 改为 0.905：

geometries:
  structures:
  - name: F31
    primitives:
    - {type: CIRCLE, radius: 0.4096}
    - {type: CIRCLE, radius: 0.4180}
    - {type: CIRCLE, radius: 0.4750}
    regions:
    - {material: Fuel_31, space: '1'}
    - {material: Helium, space: 2-1}
    - {material: Zircaloy-4, space: 3-1}
    meshing: {type: SECTORS, num_azimuths: 4, radii: [0.2365, 0.3344, -0.4750, 0.5800]}
  - name: GT
    primitives:
    - {type: CIRCLE, radius: 0.561}
    - {type: CIRCLE, radius: 0.602}
    regions:
    - {material: Zircaloy-4, space: 2-1}
    meshing: {type: SECTORS, num_azimuths: 8, radii: [0.3239, 0.4581]}
  - name: IT
    primitives:
    - {type: CIRCLE, radius: 0.559}
    - {type: CIRCLE, radius: 0.905}  # 0.605 --> 0.905
    regions:
    - {material: Zircaloy-4, space: 2-1}
    meshing: {type: SECTORS, num_azimuths: 8, radii: [0.3227, 0.4564]}

这时我们运行CRANE会出现以下错误：

../_images/error_region_overlap_between_structure.png

该错误信息会给出哪几个 structure 对象之间发生了区域重叠，重叠的分别是这几个 structure 对象中的哪些区域，重叠区域的面积是多少，重叠发生在哪个组件。

虽然错误信息非常详细，但是很多情况下由于结构体重复排列，出现结构体之间重叠区域会非常多，会报出大量的区域重叠错误。另外通过文字信息去寻找到底哪些位置出现了重叠确实比较费力。

为此，CRANE提供了 crane check-region-overlap 命令，能够将结构体之间的区域重叠错误变为警告以防止程序中断，并在几何处理完毕后绘制出区域重叠的可视化图。

Note

crane check-region-overlap 命令只支持结构体之间的区域重叠可视化，并不支持单个结构体内部的区域重叠可视化。

如对以上 VERA_2A 问题执行：

crane check-region-overlap VERA_2A.yaml

在几何处理过程中会出现以下警告信息：

../_images/warn_region_overlap_between_structure.png

运行结束后绘制出区域重叠的可视化图：

../_images/region_overlap_between_structure.png

该图只会对区域重叠的材料区进行颜色渲染，以方便用户迅速定位区域重叠位置。由图可见中心测量管与周围的燃料棒结构体发生了区域重叠。

Note

对于三维问题，crane check-region-overlap 命令会从底到顶逐层产生区域重叠可视化图，中间取消可按 Ctrl + C。