1. 为什么平面实体值得单独拎出来讲
做FDTD仿真的人，绕不开结构搭建这一步。不管你是做光栅耦合器、微环谐振腔、还是超表面透镜，最终都要落到“在仿真区域里放一个什么东西”这个最朴素的问题上。Lumerical的FDTD Solutions提供了图形界面画结构的方式，但真正做过几个项目之后你会发现，纯靠鼠标拖拽建出来的模型，改一个参数就得重新画一遍，效率低得让人抓狂。这时候脚本语言就成了分水岭——会用脚本的人，改一个变量就能批量扫描几十组参数；不会的人，只能一遍遍手动调。
平面实体（Planar solid）是Lumerical脚本里最基础也最常用的结构类型之一。所谓“平面实体”，你可以把它理解成一块有厚度、有形状的平板——它在某一个方向上延伸出厚度，另外两个方向由你定义的几何轮廓决定。听起来简单，但实际用起来，从坐标系的选取、厚度的方向、到材料属性的赋值，每一步都有坑。我见过不少新手，结构画出来了，仿真跑起来结果不对，排查半天发现是厚度方向搞反了，或者材料覆盖错了区域。
这篇内容适合两类人：一类是刚接触Lumerical脚本、想从“会点鼠标”过渡到“会写脚本”的FDTD使用者；另一类是用了一段时间脚本，但对Planar solid的理解还停留在“能用就行”、想搞清楚底层逻辑和最佳实践的人。我会从脚本语言的基本结构讲起，把平面实体的搭建过程拆开揉碎，配上可直接复现的代码和参数计算过程，最后分享一些我实际踩过的坑和排查技巧。
2. Lumerical脚本语言与结构搭建的整体思路
2.1 脚本语言在FDTD工作流中的位置
Lumerical的脚本语言本质上是一种面向仿真对象的命令式语言，它的语法风格接近Lua，但又不完全是Lua。你在FDTD的脚本编辑器里写的每一行，最终都会被解释成对仿真对象属性的操作。比如addfdtd是添加FDTD仿真区域，addrect是添加矩形结构，set是设置属性，setnamed是按名称设置属性。这些命令组合起来，就构成了整个仿真模型的搭建过程。
为什么强调“面向仿真对象”？因为Lumerical的脚本不是通用编程语言，它没有复杂的控制流和数据结构（虽然支持循环和数组），它的核心价值在于：把你手动操作GUI的每一步，用文本命令的形式固定下来。这样做的好处是显而易见的——可复用、可参数化、可版本控制。你写好的脚本，换一台机器、换一个项目，改几个参数就能继续用。
从工作流的角度看，一个完整的FDTD仿真脚本通常包含这几个阶段：初始化（清空旧模型、设置单位）、定义参数（波长、尺寸、材料等）、搭建结构（添加各种实体）、设置仿真区域和边界条件、添加光源和监视器、运行仿真、提取和分析结果。平面实体的搭建属于第三个阶段，但它承上启下——上面的参数定义决定了它的尺寸和位置，下面的仿真设置又依赖于它的存在。
2.2 平面实体的几何逻辑与坐标系约定
在讲具体命令之前，必须先搞清楚Lumerical的坐标系约定。FDTD Solutions默认使用右手坐标系，X、Y、Z三个轴的方向遵循右手定则。对于平面实体来说，最关键的是“厚度方向”的确定。Lumerical里的平面实体（比如addplanarsolid）允许你指定一个平面和厚度，平面由法线方向和平面上的一个点确定，厚度则沿着法线方向延伸。
这里有一个容易混淆的地方：很多人以为“平面实体”就是二维的，其实不是。它是有厚度的三维物体，只是它的几何形状由一个二维轮廓加上一个厚度方向上的拉伸来定义。你可以把它想象成一块用模具压出来的饼干——饼干的形状由模具决定（二维轮廓），饼干的厚度由面团的厚度决定（拉伸方向）。
Lumerical提供了几种创建平面实体的方式。最直接的是addplanarsolid命令，它接受一个结构名称和一组属性参数。另一种方式是用addrect或addcircle等命令创建二维形状，然后通过设置Z方向的跨度来赋予厚度。两种方式各有适用场景：addplanarsolid更适合需要精确控制法线方向和平面位置的场合，而addrect加Z跨度更适合简单的矩形平板。
2.3 为什么选择脚本而非GUI
这个问题我被问过很多次。GUI画结构直观，所见即所得，为什么还要费劲写脚本？答案在于“规模”和“重复性”。当你只需要画一个简单的波导时，GUI确实快。但当你需要画一个由几十个周期组成的光栅、或者需要扫描上百组几何参数时，GUI的效率就崩溃了。脚本的优势在于：一次编写，无限次运行；参数化定义，批量扫描；版本可控，团队协作方便。
还有一个容易被忽视的好处：脚本强迫你思考结构的数学定义。用GUI画图时，你可能凭感觉拖拽，尺寸差不多就行。但写脚本时，你必须明确写出每个坐标、每个尺寸的数值，这迫使你回到设计本身，想清楚每个几何参数的意义。这种“被迫的严谨”，长期来看对仿真能力的提升是巨大的。
3. 平面实体搭建的核心命令与参数详解
3.1 addplanarsolid命令的完整语法
addplanarsolid是Lumerical脚本中创建平面实体的核心命令。它的基本语法是：
addplanarsolid; set("name", "结构名称"); set("x", x坐标); set("y", y坐标); set("z", z坐标); set("nx", 法线x分量); set("ny", 法线y分量); set("nz", 法线z分量); set("thickness", 厚度); set("material", "材料名称");这里有几个关键点需要展开。首先，addplanarsolid本身不带参数，它只是创建一个空的平面实体对象，后续用set命令来配置属性。这种“先创建、后配置”的模式在Lumerical脚本中很常见，好处是你可以分步骤设置，也方便调试。
其次，x、y、z定义的是平面上的一个参考点，而不是结构的中心。这个参考点的具体含义取决于你后续如何定义轮廓。对于最简单的矩形平面实体，这个点通常取矩形的中心。但对于复杂轮廓，它可能只是平面上的任意一点。
法线向量(nx, ny, nz)决定了平面的朝向。如果你想要一个水平放置的平板（厚度沿Z方向），法线就是(0, 0, 1)。如果你想要一个垂直放置的平板（厚度沿X方向），法线就是(1, 0, 0)。法线向量不需要归一化，Lumerical会自动处理，但为了清晰起见，建议使用单位向量。
厚度thickness是沿着法线方向从参考点向两侧延伸的总厚度。注意，是“向两侧延伸”，也就是说，参考点位于厚度的中间位置。如果你设置厚度为0.2微米，法线为(0, 0, 1)，参考点Z坐标为0，那么结构会从Z=-0.1延伸到Z=+0.1。这一点和很多人的直觉不同——他们以为参考点是底面或者顶面。我当初就因为这个搞错过，结构位置偏了半个厚度，仿真结果怎么都对不上。
3.2 轮廓定义：从矩形到任意多边形
平面实体的“平面形状”由轮廓决定。Lumerical提供了几种定义轮廓的方式：
第一种是使用内置的简单形状。比如，你可以在创建平面实体后，用set("shape", "rectangle")来指定矩形轮廓，然后用set("x span", ...)和set("y span", ...)来定义矩形的长和宽。这种方式最简单，适合规则形状。
第二种是使用顶点列表定义任意多边形。命令是set("vertices", ...)，后面跟一个N×2的矩阵，每一行是一个顶点的(x, y)坐标。这种方式灵活度最高，可以定义任何凸多边形或凹多边形。但要注意，顶点必须按顺序排列（顺时针或逆时针），不能交叉，否则Lumerical会报错或者生成错误的形状。
第三种是使用数学表达式定义曲面。这种方式用得相对少一些，适合需要精确控制轮廓曲线的场合。比如你可以用set("shape", "equation")然后定义一个函数来描述边界。
对于大多数应用场景，矩形轮廓已经够用了。光栅的每个周期可以是一个矩形平板，波导的芯层可以是一个长条形矩形，微环的耦合区域也可以用矩形近似。真正需要复杂多边形的时候，往往是做超表面或者光子晶体的时候，每个单元的形状不是简单的矩形。
3.3 材料属性的赋值与优先级
材料赋值是平面实体搭建中另一个容易出问题的地方。Lumerical的材料系统分为几个层级：内置材料库（如Si、SiO2、Au等）、用户自定义材料、以及直接指定折射率数值。当你用set("material", "Si")时，Lumerical会去材料库里查找名为“Si”的材料。如果找不到，它会报错。
这里有一个实用技巧：如果你只是做快速验证，不想花时间定义材料模型，可以直接用set("index", 3.5)来指定折射率。这种方式简单粗暴，但只适合色散不明显的场合。对于需要精确色散建模的场景，还是老老实实用材料库或者自定义材料模型。
材料赋值的优先级也需要注意。如果你先设置了material，然后又设置了index，后者会覆盖前者。反过来，如果你先设置了index，再设置material，材料库的定义会覆盖折射率数值。所以，设置顺序很重要，建议在脚本里把材料相关的设置集中放在一起，避免混乱。
还有一个坑：当多个结构重叠时，Lumerical默认使用“后添加的结构覆盖先添加的结构”的规则。也就是说，如果你先画了一个大平板，又在上面画了一个小方块，小方块区域会使用小方块的材料，其余区域使用大平板的材料。这个规则在搭建多层结构时非常有用，但如果不注意添加顺序，可能会得到意想不到的结果。
4. 从零搭建一个平面实体：完整实操流程
4.1 环境准备与脚本框架
在开始写具体结构之前，先建立一个干净的脚本框架。我习惯在脚本开头做这几件事：清空当前模型、设置单位、定义全局参数。清空模型用newproject或者switchtolayout加deleteall，前者会重置所有设置，后者只删除结构。对于大多数情况，我推荐用newproject，确保从一个完全干净的状态开始。
单位设置用set("units", "micron")，把长度单位统一为微米。FDTD仿真中，微米是最常用的单位，波长、尺寸都在这个量级。统一单位可以避免很多换算错误。
全局参数的定义是脚本可读性的关键。我习惯把所有的几何参数、材料参数、仿真参数都放在脚本开头，用变量名代替具体数值。比如：
-- 全局参数定义 lambda0 = 1.55; -- 中心波长，单位微米 wg_width = 0.5; -- 波导宽度 wg_height = 0.22; -- 波导厚度 sub_thickness = 2.0; -- 衬底厚度 si_index = 3.48; -- 硅的折射率（近似值） sio2_index = 1.44; -- 二氧化硅的折射率这样做的好处是，当你需要修改参数时，只需要改一处，整个脚本都会跟着变。而且，变量名本身就是注释，读脚本的人一眼就能看出每个数值的含义。
4.2 创建衬底与波导的平面实体
假设我们要搭建一个最简单的硅波导结构：二氧化硅衬底上有一层硅波导。衬底是一个大平板，波导是一个长条形平板。先创建衬底：
addplanarsolid; set("name", "substrate"); set("x", 0); set("y", 0); set("z", -sub_thickness/2); set("nx", 0); set("ny", 0); set("nz", 1); set("thickness", sub_thickness); set("material", "SiO2 (Glass) - Palik"); set("shape", "rectangle"); set("x span", 10); set("y span", 10);这里我把衬底的中心放在Z=-sub_thickness/2的位置，这样衬底的上表面正好在Z=0处。法线是(0,0,1)，厚度是2微米，所以衬底从Z=-2延伸到Z=0。x span和y span都设为10微米，足够覆盖大多数仿真区域。
接下来创建波导：
addplanarsolid; set("name", "waveguide"); set("x", 0); set("y", 0); set("z", wg_height/2); set("nx", 0); set("ny", 0); set("nz", 1); set("thickness", wg_height); set("material", "Si (Silicon) - Palik"); set("shape", "rectangle"); set("x span", 10); set("y span", wg_width);波导的中心在Z=wg_height/2，厚度是0.22微米，所以波导从Z=0延伸到Z=0.22。波导的下表面和衬底的上表面正好接触，没有间隙也没有重叠。这种“刚好接触”的设置在仿真中很常见，但要注意，如果两个结构的表面完全重合，Lumerical可能会在网格划分时产生一些数值上的模糊。更稳妥的做法是让它们稍微重叠一点点，比如波导的下表面延伸到Z=-0.01，这样确保材料覆盖没有缝隙。
4.3 参数计算：厚度、位置与网格匹配
平面实体的厚度和位置不是随便设的，它们需要和仿真网格匹配。FDTD的网格是离散的，如果结构的边界不在网格线上，Lumerical会用“共形网格”技术来近似，但这会引入一定的误差。为了减少误差，一个实用的技巧是：让结构的厚度是网格尺寸的整数倍。
假设你设置的网格尺寸是0.02微米（在硅波导中，为了精确解析模式，通常需要这么细的网格），那么波导厚度0.22微米就是11个网格，刚好是整数倍。如果你设置厚度为0.225微米，那就不是整数倍，Lumerical需要做共形网格处理，虽然也能算，但精度会打折扣。
位置的计算也是同理。波导的中心Z坐标是wg_height/2=0.11微米，如果网格在Z方向的起点是-2微米，网格尺寸是0.02微米，那么0.11除以0.02等于5.5，不是整数。这意味着波导的中心不在网格线上。更好的做法是调整网格起点或者波导位置，让关键界面落在网格线上。
我通常的做法是：先确定网格尺寸，然后反推结构的尺寸和位置，确保关键界面（如波导上下表面）都在网格线上。这个过程在脚本里可以用变量和表达式自动完成，不需要手动计算。
4.4 验证结构：可视化与脚本检查
结构搭建完成后，不要急着跑仿真。先做两件事：可视化检查和脚本检查。可视化检查用plot命令或者直接在GUI里看。Lumerical的脚本可以调用plot来显示结构，但更直观的方式是运行脚本后，在GUI的“Layout”视图里查看。检查的内容包括：结构的位置是否正确、尺寸是否匹配、材料是否覆盖了正确的区域。
脚本检查主要是看有没有语法错误和逻辑错误。Lumerical的脚本编辑器会高亮语法错误，但逻辑错误需要你自己排查。一个常用的技巧是在关键步骤后加?命令来打印变量值，比如?wg_height会输出波导厚度的当前值。这在你用表达式计算尺寸时特别有用，可以确认计算结果是否符合预期。
还有一个检查项：结构的名称是否唯一。Lumerical允许同名结构存在，但setnamed命令会操作第一个匹配的结构，这可能导致意外的结果。我习惯给每个结构起一个描述性的名字，比如“substrate”、“waveguide_core”、“cladding”等，避免用“rect1”、“rect2”这种无意义的名字。
5. 常见问题与排查技巧实录
5.1 结构位置偏移：法线与参考点的陷阱
这是新手最容易踩的坑。很多人以为set("z", 0)就是把结构的底面放在Z=0处，实际上参考点位于厚度的中间。如果你想要底面在Z=0，参考点应该设在Z=thickness/2。如果你想要顶面在Z=0，参考点应该设在Z=-thickness/2。
更隐蔽的问题是法线方向。如果你设置法线为(0,0,-1)，厚度为0.2，参考点在Z=0，那么结构会从Z=-0.1延伸到Z=+0.1——和法线为(0,0,1)时一样。因为厚度是向两侧延伸的，法线的正负只影响平面的“正面”朝向，不影响厚度的延伸范围。但如果你后续用到了依赖法线方向的操作（比如某些边界条件或者材料各向异性），法线方向就很重要了。
排查方法：在GUI里查看结构时，注意看Z方向的跨度。Lumerical会在属性栏里显示结构的实际范围。如果范围和预期不符，检查参考点和厚度的设置。
5.2 材料未生效：名称匹配与覆盖顺序
材料设置不生效，通常有两个原因：名称不匹配或者覆盖顺序不对。名称不匹配的情况很常见——你写了set("material", "Si")，但材料库里实际的名字是"Si (Silicon) - Palik"。Lumerical的材料库命名有固定的格式，通常是“材料名 (全称) - 来源”。你可以用?getmaterial("Si")来查询材料是否存在，或者用?getmaterial列出所有可用材料。
覆盖顺序的问题更隐蔽。假设你先添加了一个大平板，材料设为SiO2，然后又添加了一个小方块，材料设为Si。如果小方块和大平板有重叠区域，重叠部分的材料取决于添加顺序——后添加的覆盖先添加的。如果你先添加小方块再添加大平板，那么大平板会覆盖小方块，重叠区域变成SiO2。这显然不是你想要的结果。
排查方法：用select命令选中结构，然后用?get("material")查看当前材料。如果材料不对，检查添加顺序和名称拼写。
5.3 网格与结构不匹配导致的仿真异常
结构尺寸和网格不匹配，轻则精度下降，重则仿真不收敛。我遇到过一次，波导厚度设了0.22微米，网格尺寸设了0.03微米，0.22除以0.03等于7.33，不是整数。仿真跑起来后，模式分布看起来正常，但传输率比预期低了10%。后来把网格尺寸改成0.02微米，传输率就对了。原因是共形网格在处理非整数倍厚度时，引入了额外的数值反射。
排查方法：在仿真设置里查看网格尺寸，然后手动计算关键尺寸是否是网格尺寸的整数倍。如果不是，调整网格尺寸或者结构尺寸。Lumerical也提供了“mesh override region”功能，可以在关键区域强制使用更细的网格，但这是另一个话题了。
5.4 脚本调试的实用技巧
Lumerical的脚本调试功能不算强大，但有几个技巧很实用。第一，用?命令打印变量值，这是最直接的调试方式。第二，用try...catch结构捕获错误，避免脚本因为一个错误就完全停止。第三，把脚本分成小段运行，每段运行后检查结果，而不是一次性跑完整个脚本。
还有一个技巧：在脚本开头设置set("script mode", "true")，这样脚本运行时不会弹出GUI窗口，速度更快。调试完成后再关掉这个设置，用GUI查看结果。
6. 进阶技巧：参数化扫描与结构复用
6.1 用循环批量创建周期结构
平面实体的真正威力在于批量创建。假设你要做一个由20个周期组成的光栅，每个周期的宽度是0.5微米，间距是0.2微米。用GUI画的话，你得复制粘贴20次。用脚本的话，一个循环就够了：
period = 0.7; -- 周期 width = 0.5; -- 光栅条宽度 N = 20; -- 周期数 for i = 1, N do addplanarsolid; set("name", "grating_" + num2str(i)); set("x", (i - (N+1)/2) * period); set("y", 0); set("z", wg_height/2); set("nx", 0); set("ny", 0); set("nz", 1); set("thickness", wg_height); set("material", "Si (Silicon) - Palik"); set("shape", "rectangle"); set("x span", width); set("y span", 10); end这段代码的关键是(i - (N+1)/2) * period这个表达式，它让光栅条以原点为中心对称分布。num2str(i)把数字转换成字符串，用于生成唯一的名称。这种模式在搭建超表面、光子晶体等周期结构时非常常用。
6.2 将常用结构封装为函数
如果你经常搭建类似的结构，可以把它们封装成函数。Lumerical的脚本支持自定义函数，语法是：
function add_waveguide(name, x, y, z, width, height, material) addplanarsolid; set("name", name); set("x", x); set("y", y); set("z", z); set("nx", 0); set("ny", 0); set("nz", 1); set("thickness", height); set("material", material); set("shape", "rectangle"); set("x span", 10); set("y span", width); end然后调用add_waveguide("wg1", 0, 0, 0.11, 0.5, 0.22, "Si (Silicon) - Palik")就能快速创建一个波导。这种方式不仅减少了重复代码，还让脚本的结构更清晰，修改起来更方便。
6.3 结构复用与参数继承
在复杂的仿真中，很多结构共享相同的参数。比如，所有的硅结构都用同一种材料，所有的波导都有相同的厚度。这时候可以用“参数继承”的方式，把公共参数定义在全局，然后在创建结构时引用这些全局变量。这样，当你需要修改材料或者厚度时，只需要改全局变量，所有结构都会自动更新。
更进一步，你可以把结构定义写在一个单独的脚本文件里，然后在主脚本中用include命令引入。这样，不同的项目可以共享同一套结构定义，避免重复劳动。
7. 我个人的实操体会
平面实体看起来简单，但真正用好需要理解几个核心概念：参考点的位置、法线的方向、厚度的延伸方式、材料覆盖的优先级。这些概念在GUI里是隐式的，你拖拽鼠标时不需要想这些，但写脚本时必须明确。我刚开始用脚本时，经常因为参考点位置搞错导致结构偏移，排查半天才发现是厚度延伸方向的问题。后来养成了一个习惯：每创建一个结构，就在脚本里加一行注释，写明参考点的位置和厚度的范围。这样即使过了几个月回头看，也能快速理解当时的意图。
另一个体会是：脚本的可读性比简洁性更重要。我见过一些脚本，写得非常紧凑，一行命令搞定好几个设置，但过两周自己都看不懂了。相比之下，把每个设置单独写一行，加上注释，虽然脚本长一点，但维护起来轻松得多。特别是当你要把脚本交给别人或者过一段时间自己再看时，可读性的价值就体现出来了。
最后分享一个小技巧：在脚本开头定义一个debug变量，设为true时打印详细的调试信息，设为false时静默运行。这样你可以在调试阶段打开详细输出，正式运行时关掉，既方便排查问题，又不影响运行速度。这个习惯我从写第一行Lumerical脚本时就养成了，到现在还在用。
