MATLAB API的设置 #

本节是关于 MATLAB 编程接口的相关设置与使用方法的介绍。

SimWorks 提供了 MATLAB API 功能，允许用户通过编写 MATLAB 脚本或程序，与 SimWorks Finite Difference Solutions 仿真软件进行深度交互。通过此接口，您可以：

• 直接控制仿真软件：打开软件、设置参数、运行仿真等操作。
• 实现双向数据交换：将 MATLAB 工作空间中的变量、矩阵及复杂数据结构传输至 SimWorks，亦可从SimWorks 软件中提取仿真结果和数据至 MATLAB。
• 构建自动化工作流：将仿真的设置、执行与后处理流程集成于 MATLAB 环境中，实现任务批处理、参数扫描和设计优化。

借助该 API，您能够将 SimWorks 强大的物理场仿真能力与 MATLAB 的数据分析及可视化功能无缝结合。这不仅大大提升了仿真后处理的效率，也为实现更复杂的建模以及定制专属的仿真平台提供了极高的灵活性。
典型应用场景包括：

• 复杂仿真数据的后处理与可视化
• 自动化仿真与自定义优化流程
• 与 MATLAB 工具箱（如天线设计、信号处理、优化、机器学习工具箱）集成

MATLAB API的初始环境配置 #

在使用 MATLAB API 之前，需要正确配置系统环境，确保 MATLAB 能够定位到 SimWorks Finite Difference 的可执行文件和接口库。
用户应已正确安装 SimWorks Finite Difference 以及 MATLAB 编译环境。然后将以下代码添加到 MATLAB 脚本的开头，或保存在单独的配置脚本中。请根据实际安装路径修改对应目录。

% 配置 SimWorks Finite Difference 的 MATLAB API 环境

% 设置软件文件路径（包含 `fd_solution.exe` 的目录）
bin_dir = 'C:\Program Files\SimWorks\SimWorks FD Solutions beta\bin';
if ~contains(getenv('PATH'), bin_dir)
    setenv('PATH', [getenv('PATH') ';' bin_dir]);
end

% 设置 MATLAB API 接口文件路径（包含 `.mexw64` 文件的目录）
mex_dir = 'C:\Program Files\SimWorks\SimWorks FD Solutions beta\api\matlab';

if ~contains(path, mex_dir)
    path(path, mex_dir);
end

MATLAB API接口说明 #

MATLAB API 提供了一系列函数，用于控制 SimWorks Finite Difference 实例并实现数据交互。

1. h = appopen('fd');
   打开 SimWorks Finite Difference Solutions 软件的运行程序，用 h 做为软件实例的句柄，可以同时打开多个软件。
2. appclose(h);
   关闭指定的软件实例。
3. appevalscript(h,'a=1;');
   在指定软件实例中执行SimWorks脚本命令a=1;。
4. gvar=appgetvar(h,'a');
   从指定软件实例中获取变量a，该变量类型支持数值矩阵、字符串矩阵，以及软件内置的matrixdataset、unstructureddataset、cell、struct数据类型。
5. appputvar(h,'b',[1 2 3]);
   将变量b传输给指定的软件实例中，变量为数值矩阵[1 2 3]。该变量类型支持数值矩阵、字符串矩阵、软件内置的matrixdataset、unstructureddataset、cell、struct数据类型。其中matrixdataset、unstructureddataset在MATLAB中都表示为特殊结构的struct。

MATLAB API的代码示范 #

以下示例展示了 MATLAB API 的典型工作流程，包括环境配置、软件控制、数据交换和复杂数据类型处理。

% 将文件地址替换为用户自己对应的文件地址
bin_dir = 'C:\Program Files\SimWorks\SimWorks FD Solutions beta\bin';

if ~contains(getenv('PATH'), bin_dir)
    setenv('PATH', [getenv('PATH') ';' bin_dir]);
end

mex_dir = 'C:\Program Files\SimWorks\SimWorks FD Solutions beta\api\matlab';

if ~contains(path, mex_dir)
    path(path, mex_dir);
end
% 初始化
clear all;
close all;

% 打开软件
h = appopen('fd');

% 执行脚本命令
appevalscript(h, 'a = 1;');
appevalscript(h, 'b = a + 1;');

% 获取变量
var_a = appgetvar(h, 'a');
var_b = appgetvar(h, 'b');

% 生成矩阵并获取对应变量
appevalscript(h, "gstr_empty = '';");
appevalscript(h, "gstr_single = 'abc';");
appevalscript(h, "gstr_mat = ['abc', 'de', 'ff'; 'f', 'gh', 'hh'];");
appevalscript(h, "gcomplex_mat1 = [0 + 1j, 1+2j, 2+3j; 2+3j 3+4j 4+3.2j];");
gstr_empty = appgetvar(h, 'gstr_empty');
gstr_single = appgetvar(h, 'gstr_single');
gstr_mat = appgetvar(h, 'gstr_mat');
gcomplex_mat1 = appgetvar(h, 'gcomplex_mat1');

% 输出数据变量到软件中
appputvar(h, 'preal_empty', []);
appputvar(h, 'preal_single', 1);
appputvar(h, 'preal_int32', int32([1, 2]));
appputvar(h, 'pcomplex_single', 1.2 + 2.2j);
appputvar(h, 'pcomplex_int32', int32(1.2 + 2.2j));
appputvar(h, 'preal_double', [1.2, 2.2, 3.2; 4.2, 5.2 6.2]);
appputvar(h, 'preal_int32_2', int32([1.2, 2.2, 3.2; 4.2, 5.2 6.2]));
appputvar(h, 'pcomplex_double', [1.2 + 2.2j, 2.2 + 2.2j, 3.2 + 3.2j; 4.2 + 1.2j, 5.2 + 2.2j 6.2 + 2.2j]);
appputvar(h, 'pcomplex_int32_2', int32([1.2 + 2.2j, 2.2 + 2.2j, 3.2 + 3.2j; 4.2 + 1.2j, 5.2 + 2.2j 6.2 + 2.2j]));

% 构建结构组并输出到软件中
pmds = struct();
pmds.Simworks_dataset = struct();
pmds.Simworks_dataset.name = "pmds-abc";
pmds.Simworks_dataset.geometry = 'matrix';
pmds.Simworks_dataset.parameters = {["xxx"], ["yyy"], ["zzz"]};
pmds.Simworks_dataset.attributes = ["attr1", "attr2", "attr3", "attr4"];
appputvar(h, "pmds", pmds);

% 调用创建结构msf脚本
appevalscript(h, fileread("C:\Program Files\SimWorks\SimWorks FD Solutions beta\api\simworks_test\matlab\msf\create_project.msf"));

%% 关闭软件
appclose(h);

其中create_project.msf可以创建一个线栅偏振器工程，其代码示例如下：

clear;
deleteall;
clc;

switchtotopview;
addrect;
select('Rectangle');
set('name','grating');
set('x',0);
set('y',0);
set('z',0.07e-6);
set('x span',0.1e-6);
set('y span',1e-6);
set('z span',0.14e-6);
set('material','Al (Aluminium) - Palik');

addrect;
select('Rectangle');
set('name','substrate');
set('x',0);
set('y',0);
set('z',0.07e-6);
set('x span',0.1e-6);
set('y span',1e-6);
set('z span',0.14e-6);
set('material','Al (Aluminium) - Palik');

addfdtd;
set('dimension','2d');
set('polarization','te');
set('x',0);
set('y',0);
set('z',0.12e-6);
set('x span',0.2e-6);
set('z span',0.8e-6);
set('boundary conditions x max','periodic');
set('boundary conditions x min','periodic');
addplane;
set('x',0);
set('y',0);
set('z',0.252e-6);
set('x span',0.4e-6);
set('y span',0);
set('direction','backward');
set('central wavelength',0.55e-6);
set('wavelength span',0.2e-6);
addfieldmonitor;
set('name','ref');
set('z',0.5e-6);
set('x span',1e-6);
set('spatial type','linear x');
addfieldmonitor;
set('name','trans');
set('z',-0.252e-6);
set('x span',1e-6);
set('spatial type','linear x');