CST超表面设计神器：一键生成编码矩阵并自动布阵-171主机测评

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */
#content_views .toc,
/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */
#content_views.markdown_views > p:empty:has(+ .toc),
#content_views.markdown_views > .toc + p:empty,
/* 富文本旧版目录标记 */
#content_views.htmledit_views #main-toc,
#content_views.htmledit_views #hr-toc,
#content_views.htmledit_views p[id*=\”-toc\”] {
display: none !important;
}
/* 目录去掉后，紧跟的首个标题不再多出一块上边距 */
#content_views.markdown_views > .toc + h1,
#content_views.markdown_views > .toc + h2,
#content_views.markdown_views > .toc + h3,
#content_views.markdown_views > .toc + h4,
#content_views.markdown_views > .toc + p:empty + h1,
#content_views.markdown_views > .toc + p:empty + h2,
#content_views.markdown_views > .toc + p:empty + h3,
#content_views.markdown_views > .toc + p:empty + h4 {
margin-top: 0 !important;
}

建议标签：CST、超表面、反射阵、Python、PyQt5、阵列天线项目仓库：CST_Arrary_design

设计编码超表面或可重构阵列时，工作往往分散在几个地方：手工计算相位、整理状态矩阵、核对单元模型、在 CST 中重复复制对象，以及查看初步方向图。矩阵和 CST 模型只要有一个状态对应错了，排查起来就很费时间。

这个项目把这些步骤放进一个 Windows 图形界面：生成或导入整数编码矩阵，查看状态统计与解析阵因子预览，配置 PB 几何单元或可重构 Lumped Elements 的状态映射，最后将阵列写入新建的 CST 工程副本。

本文介绍当前版本的功能和完整操作流程。软件可以用于设计与预检查，但解析预览不是 CST 全波仿真结果；布阵命令完成也不等于几何、电连接和电磁性能已经验证。

在这里插入图片描述

图 1｜软件主界面。左侧继续向下滚动可见状态映射和执行布阵。标注： 1 是工程入口，可选文件或挂载活动工程；2 是周期、频率和矩阵操作区；3 是右侧编码热力图，点击上方“计算远场”可切换到阵因子预览。

一、软件能做什么

模块主要功能

CST 工程	选择并打开已保存的 .cst 文件，或挂载当前活动工程；读取源实体及 Lumped Elements。
阵列与编码	输入、加载、保存 TXT 整数矩阵；设置 X/Y 周期和工作频率；使用多种物理模型生成编码。
矩阵统计与运算	查看状态占比、信息熵、横纵相邻状态变化率；旋转、镜像、转置、循环偏移、周期平铺。
状态映射	为每个编码状态指定 PB 几何源对象或可重构元件，并填写可选的实际幅度、相位标定值。
结果预览	显示矩阵热力图和归一化解析阵因子，可选单元方向图近似与角域采样数。
CST 布阵	核对源工程和对象后创建独立副本，分批写入 History，保存执行记录，并提供受控取消和失败恢复提示。

目前快速生成区包括：波束指向、近场聚焦、聚焦 OAM、双波束、双焦点、贝塞尔波束、馈源补偿、三种入射/点源相位补偿、棋盘编码和可复现随机编码。编码模式可以独立于 CST 使用；真正写入几何时才需要可用的 CST 环境。

二、运行环境与启动

项目依赖 Python、PyQt5、NumPy 和 Matplotlib。若需要连接 CST，请使用与本机 CST Python 接口兼容的 Python 小版本；不要直接假设任意 Python 版本均可连接。只做矩阵计算和界面预览时，可以不安装 CST。

在 Windows PowerShell 中进入项目目录，安装依赖并启动：

python –m pip install –r requirements.txt
python cst_array_gui.py

可以先运行无需 CST 的测试：

python –m unittest discover –s tests –v

如果 CST 已安装但界面显示“接口未加载”，点击“CST 工程”中的“配置库路径”，选择安装目录下的 AMD64\\python_cst_libraries。也可在程序目录的 cst_path.txt 第一行写入该目录，或设置环境变量 CST_PYTHON_LIBRARIES，然后点击“重新检测”。这里需要的是Python 库目录，不是某个 .dll 文件。在这里插入图片描述

图 2｜CST Python 库配置。图中接口库已识别，但尚未连接工程；“接口可用”和“工程已连接”是两回事。标注： 1 显示检测到的库目录，可通过下方按钮修改或重新检测；2 是“打开工程”入口，先选取已保存的 .cst 文件后才能使用。图示路径仅用于说明目录结构。

如需生成 Windows 文件夹版程序，可在已配置 Conda 的环境中执行 build_exe.ps1；默认使用名为 cst_tool 的环境，也可通过 CST_ARRAY_CONDA_ENV 指定其他环境。打包产物在 dist\\CST_Array_Tool。打包文件不包含 CST 本体或其 Python 库，目标电脑仍需安装相应 CST。

三、五分钟上手：不连接 CST 也能完成编码预览

先用棋盘编码走一遍流程，确认矩阵、统计和预览都正常。

在“阵列与编码”中设置 X 周期、Y 周期和频率。例如分别填入 6 mm、6 mm 和 10 GHz。这些参数会参与物理编码生成和阵因子计算。

切换到“快速生成”，把行数、列数设为 8 × 8，状态数设为 2。

“编码类型”选择“棋盘编码”，分块行数和列数先保持 1，状态 A/B 分别选择 0、1，点击“生成并载入矩阵”。

软件返回“矩阵输入”页。检查状态占比、信息熵、横纵相邻状态变化率，以及右侧的矩阵热力图。

点击右侧“计算远场”，得到归一化解析阵因子图。可以切换“各向同性（仅阵因子）”或“余弦单元（贴片近似）”观察预览模型的差别。在这里插入图片描述

图 3｜快速生成棋盘编码。标注： 1 选择“棋盘编码”；2 设置行数，旁边依次是列数和状态数，本例为 8 × 8、2 状态；3 设置分块行列数，下方再指定交替使用的状态 A/B。

在这里插入图片描述

图 4｜生成后的矩阵与统计。标注： 1 是可编辑的整数状态矩阵；2 是状态分布，旁边还有信息熵与相邻变化率；3 是同一矩阵的热力图，颜色对应状态编号。

右侧远场图只是简化阵因子预览，不包含完整的单元电磁响应、互耦、损耗、馈源照明或 CST 求解结果；图上的峰值方向不能直接称为“全波增益方向”。若所有单元的有效激励幅度均为零，软件会报错，因为这时不存在可定义的峰值方向。

在这里插入图片描述

图 5｜解析阵因子远场预览。标注： 1 选择单元方向图近似，角域采样数在下一行；2 显示计算得到的峰值方向；3 是归一化阵因子图。峰值与图形均属于解析预览，不能作为 CST 全波增益报告。

四、矩阵文件、统计与变换

已有编码结果可以直接粘贴到“矩阵输入”，也可以用“加载 TXT”读取。文件按行表示矩阵；整数之间可用空格、逗号或分号分隔，整行可用 # 写注释。例如：

# 4 行 4 列，两种状态
0 1 0 1
1 0 1 0
0 1 0 1
1 0 1 0

点击“解析并预览”后，程序会检查矩阵是否为空、每行列数是否一致，以及编码状态是否为非负整数。如果矩阵包含超出当前映射状态数的编号，会在输入区提示；这时应先调整 PB 状态数或可重构 bit 数。

“矩阵输入”同时给出三项统计：

状态分布：各状态在矩阵中的单元占比，便于发现某一状态是否意外缺失。
信息熵：按状态出现频率计算的 bit/单元，反映状态分布的均匀程度。
相邻变化率：横向或纵向相邻单元编码不同的比例，描述离散图案变化，不代表电磁性能。

“矩阵运算”支持顺/逆时针旋转 90°、左右/上下镜像、行列转置、按当前状态数循环偏移，以及周期平铺。应用后仍输出原 TXT 整数矩阵格式；误操作可以点击“撤销上次运算”。周期平铺后行数、列数分别不能超过 512。在这里插入图片描述

图 6｜矩阵运算页。标注： 1 选择变换类型，本例为周期平铺；2 设行方向重复次数，旁边可设列方向重复次数；3 将结果写回矩阵，右侧“撤销上次运算”会在应用后可用。演示旋转或镜像时，建议使用非对称矩阵。

五、相位与编码生成：从目标到离散状态

除了棋盘和随机编码，快速生成区还可以按目标方向或焦点位置计算相位，再量化为状态编号。设置行列数、状态数、周期和频率后，在“编码类型”中选择模型；下方只显示当前模型需要的参数。

例如，用“波束指向（线性相位）”生成 16 × 16、8 状态的编码，目标指向角设为 20°、方位角设为 0°，再点击“生成并载入矩阵”。程序使用单元坐标及波长计算二维相位梯度，再映射到状态 0 至 7。为避免状态范围提示，可在 PB 映射区把状态数量也设为 8。生成矩阵后再进行解析阵因子预览。在这里插入图片描述

图 7｜波束指向编码。示例为 16 × 16、8 状态。标注： 1 选择线性相位模型；2 输入目标 θ = 20°，右侧输入 φ = 0°；3 显示量化后的编码矩阵热力图，尚不是远场方向图。

相位补偿的三种用法

新加入的补偿模式覆盖常见的“已知入射、指定输出”情形：

编码类型需要填写适合先做什么

斜入射补偿 / 波束指向	入射波传播方向 θᵢ/φᵢ；目标波束 θ/φ	为斜入射平面波设计指定出射方向的离散编码。
斜入射补偿 / 近场聚焦	入射方向；焦点 X/Y/Z	在给定斜入射条件下计算目标焦点所需相位。
点源补偿 / 近场聚焦	馈源 X/Y/Z；焦点 X/Y/Z	同时考虑馈源到单元、单元到焦点的光程。

程序采用 e^(+jωt) 相位约定，按目标阵面相位减去入射场相位求补偿，再按理想等间隔状态或当前映射表的实际复响应进行量化。例如，斜入射到远场方向时，阵面相位梯度与“入射横向方向余弦 − 目标横向方向余弦”有关。这里的“入射方向”指波朝阵面传播的方向；若手里的角度是“从阵面指向波源”，应先检查并转换方向定义。全局相位偏置只改变状态选取的整体参考，不代替正确的入射/目标坐标设置。

一个便于检查的例子：使用 16 × 16、8 状态、10 GHz、Dx = Dy = 6 mm，选择“斜入射补偿 / 波束指向”，设置入射传播方向 θᵢ = 20°、φᵢ = 0°，目标方向 θ = 0°、φ = 0°。生成后先核对矩阵状态范围，再在 CST 工程副本中施加与输入一致的照明条件验证出射方向。**普通远场预览没有加上斜入射场相位，不能用其峰值直接判定补偿后的目标方向。**近场聚焦模式同理，必须检查焦点附近的场分布，而不能只看远场图。

在这里插入图片描述

图 8｜斜入射相位补偿。标注： 1 选择“斜入射补偿 / 波束指向”；2 设置入射波的传播方向 θᵢ，旁边是 φᵢ；3 设置目标波束的 θ，旁边是 φ。右侧只显示量化编码，尚未验证实际照明下的方向。

如果在状态映射表中填入单元仿真或实测得到的线性幅度、相位，且“快速生成”的状态数与映射表一致，可勾选“按当前映射表的实际幅度与相位进行校准量化”。状态数不一致时会退回理想等间隔量化，并在运行记录中说明。量化后的矩阵依然需要结合具体单元和频率验证。

六、连接 CST 并配置 PB / 可重构映射

准备布阵前，先在 CST 中完成并保存源单元工程。软件复制的是磁盘上已保存的 .cst 文件，CST 窗口里尚未保存的编辑不会进入布阵副本。打开软件后，可以“选择工程”→“打开工程”，也可以“挂载活动工程”；随后读取对应对象清单。

PB / 几何模式

切换“状态映射”中的“几何 / PB 相位”，设置状态数量，点击“读取 CST 结构”。在每一行的配置单元格中双击，为 State 0、State 1 等选择相应源实体。可选的幅度、相位列用于编码量化与解析预览；它们不会替代源几何本身的电磁验证。矩阵中的每一个状态都应有对应的源对象映射。在这里插入图片描述

图 9｜PB 状态映射界面。标注： 1 切换到几何 / PB 模式；2 设置可用状态数量；3 为每个状态指定 CST 源实体，并可填写幅度与相位。截图时未连接工程，表中对象仍待配置。

可重构 / Lumped 模式

切换“可重构 / Lumped”，先选择 1-bit 至 4-bit 编码位数，再用“读取 Lumped 元件”获取状态源对象。双击表格中的配置单元格为各状态选取元件，并在“基板 / 介质实体”处选择需要随阵元复制的共享几何。可重构模式要求基板/共享实体非空；矩阵所用状态也必须有映射。在这里插入图片描述

图 10｜可重构映射界面。标注： 1 切换到可重构 / Lumped 模式；2 选择编码位数，决定可用状态数；3 是各状态的 Lumped 元件映射表，上方还需选择基板。截图时源对象和基板均未配置。

七、安全布阵、执行记录与恢复

确认矩阵、周期、模式、状态映射及源工程后，在“执行布阵”中选择是否启用高速布阵、是否以阵列中心作为 CST 原点。高速模式默认开启；关闭时为兼容布阵路径。“布阵完成后询问是否清理副本中的源模板”默认不勾选，即使勾选，清理也会在布阵完成后列出对象，等待单独确认。

在这里插入图片描述

图 11｜执行布阵设置。本图未连接工程，也没有执行布阵。标注： 1 是默认开启的高速布阵；2 是默认关闭的源模板清理请求，勾选后仍需单独确认；3 是布阵启动入口，真正执行前应先用其左侧“本地预检”检查输入与连接。

点击“本地预检”只能检查程序依赖、连接和部分输入，不代表几何已经正确。点击“开始布阵到 CST”后，先核对弹窗中的源工程、自动生成的副本路径、矩阵规模和模式，再确认执行。程序在后台创建新副本、核验源对象、写入 CST History，并记录分批进度；界面仍可显示进度与错误。取消请求会在批次边界生效，不能中断正在执行的一条 CST 命令。

【图 12】布阵前复核弹窗。展示源工程路径、新副本路径、矩阵规模和 PB/可重构模式；截图请打码个人路径。在这里插入图片描述

副本旁会生成同名的 .array-job.json 执行记录。重点查看：status、completed_chunks、total_chunks、new_object_counts、expected_object_counts、placement_envelope、geometry_status 与 solver_status。needs_review 表示自动对象检查结束、仍待人工复核；solver_status 为 not_run 表示程序没有启动求解器。

【图 13：无源单元布阵】执行记录与 CST 模型树。

无源单元布阵

【图 14：有源单元布阵】执行记录与 CST 模型树。

有源单元布阵

拿到副本后，建议按下面顺序人工检查：

确认原 .cst 文件未变化，打开的是自动生成的新副本。

PB 模式逐格检查实体数量、状态对应关系、X/Y 位置、材料和层高；可重构模式还要检查基板、Lumped Elements 数量与端点。

检查是否出现多余的原点重叠单元、连接错误、端口或边界设置变化。

如果执行了源模板清理，核对被删的是副本中已使用状态的源模板，未使用状态和生成对象仍然存在。

有仿真需求时，再由研究者在 CST 中配置/检查求解器并运行；使用 CST 输出的结果判断增益、效率、互耦与近场焦点。

如果任务失败或取消，先看记录中的 completed_chunks 与副本模型树。不要对部分完成的同一副本直接重发布阵任务；定位问题后，从原工程重新创建一个新副本。这比尝试在未知中间状态上续写更容易审查和恢复。

八、常见问题

1. 没有 CST，能使用软件吗？可以。矩阵生成、导入、统计、变换和解析阵因子预览不依赖 CST；打开工程、读取对象和布阵需要本机可用的 CST 接口。

2. 为什么提示“状态超出当前映射范围”？矩阵里出现了大于等于当前状态数量的编号。提高 PB 状态数或可重构 bit 数，或者修改矩阵状态编号，并补齐源对象映射。

3. 为什么远场峰值和设定角度不同？先检查频率、单元周期、状态幅相、量化状态数和单元方向图近似。对斜入射或点馈源补偿模式，普通阵因子预览未计入实际入射照明；近场聚焦也不能由远场峰值判断。最终应以一致条件下的 CST 验证为准。

4. 为什么布阵副本没有包含刚刚修改的 CST 几何？程序从磁盘上已保存的源 .cst 创建副本。回到 CST 保存源工程后，再重新发起布阵并复核新副本路径。

5. 运行记录显示完成，是否可以直接发布仿真结论？不可以。对象计数和整体边界框只完成了有限的自动检查；材料、端口、连接、边界、网格和求解结果仍须在 CST 中核对。

九、项目当前验证范围

代码仓库包含无需 CST 的数值、任务流程和离屏界面回归测试；在本文整理时，本地测试为 60 项通过。由于尚未提供用于端到端验证的真实 .cst 工程，PB 与可重构模式在真实 CST 中的对象位置、源模板清理及失败恢复仍需按 CST_VALIDATION.md 在工程副本上手动验证。使用实际课题模型前，请先用小规模演示工程完成这一步。

项目的价值在于把“编码计算 → 状态映射 → 解析预览 → 安全写入工程副本”串成可重复的操作流程。它适合做设计准备、批量布阵和前期排错；真正的电磁结论仍需要结合单元标定和 CST 全波仿真。