MATLAB API Settings #

This section introduces the configuration and usage of the MATLAB programming interface.

SimWorks provides a MATLAB API that enables deep integration between user-written MATLAB scripts or programs and the SimWorks Finite Difference Solutions simulation software. Through this interface, you can:

• Directly control the simulation software: Perform operations such as launching the software, configuring parameters, and running simulations.
• Achieve bidirectional data exchange: Transfer variables, matrices, and complex data structures from the MATLAB workspace into SimWorks, and extract simulation results and data from the SimWorks software to MATLAB.
• Build automated workflows: Integrate the setup, execution, and post-processing stages of simulations within the MATLAB environment, enabling batch task processing, parameter scanning, and design optimization.

By leveraging this API, you can seamlessly combine the powerful physical field simulation capabilities of SimWorks with MATLAB's robust data analysis and visualization functionalities. This not only significantly enhances the efficiency of simulation post-processing but also provides great flexibility for implementing more complex modeling and creating customized simulation platforms.

Typical application scenarios include:

• Post-processing and visualization of complex simulation data.
• Automated simulation and custom optimization workflows.
• Integration with MATLAB toolboxes (e.g., Antenna Design, Signal Processing, Optimization, Machine Learning toolboxes).

Environment Configuration for MATLAB API #

Before using the MATLAB API, the system environment must be correctly configured to ensure MATLAB can locate the SimWorks Finite Difference executable files and interface library.
Users should have correctly installed SimWorks Finite Difference and the MATLAB compilation environment. Then, add the following code to the beginning of your MATLAB script, or save it in a separate configuration script. Please modify the corresponding directories according to the actual installation path.

% Configure the MATLAB API environment for SimWorks Finite Difference

% Set the software binary file path (directory containing 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

% Set the MATLAB API interface file path (directory containing .mexw64 files)
mex_dir = 'C:\Program Files\SimWorks\SimWorks FD Solutions beta\api\matlab';

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

MATLAB API Interfaces #

The MATLAB API provides a series of functions for controlling SimWorks Finite Difference instances and enabling data interaction.

1. h = appopen('fd');

   Opens the SimWorks Finite Difference Solutions software runtime program, using h as the handle for the software instance. Multiple software instances can be opened simultaneously.

2. appclose(h);

   Closes the specified software instance.

3. appevalscript(h,'a=1;');

   Executes the SimWorks script command a=1; in the specified software instance.

4. gvar=appgetvar(h,'a');

   Retrieves variable a from the specified software instance. Supported variable types include numerical matrices, string matrices, and the software's built-in data types such as matrixdataset, unstructureddataset, cell, and struct.

5. appputvar(h,'b',[1 2 3]);

   Transfers variable b to the specified software instance, where the variable is the numerical matrix [1 2 3]. Supported variable types include numerical matrices, string matrices, and the software's built-in data types such as matrixdataset, unstructureddataset, cell, and struct. Among these, matrixdataset and unstructureddataset are represented as specially structured structs in MATLAB.

MATLAB API Code Example #

The following example demonstrates a typical workflow of the MATLAB API, including environment configuration, software control, data exchange, and complex data type handling.

% Replace the file paths with the user's corresponding file addresses
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
% Initialization
clear all;
close all;

% Open the software
h = appopen('fd');

% Execute script commands
appevalscript(h, "selectall;");
appevalscript(h, "delete;");
appevalscript(h, "clearall;");
appevalscript(h, "addfdtd;");
appevalscript(h, 'a = 1;');
appevalscript(h, 'b = a + 1;');

% Retrieve variables
var_a = appgetvar(h, 'a');
var_b = appgetvar(h, 'b');

% Generate matrices and retrieve corresponding variables
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');

% Output data variables to the software
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]));

% Build a structure group and output it to the software
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);

% Call an msf script
appevalscript(h, fileread("C:\Program Files\SimWorks\SimWorks FD Solutions beta\api\simworks_test\matlab\msf\create_project.msf"));

%% Close the software
appclose(h);

Among them, generate_project.msf can create a wire grid polarizer project, and its code example is as follows:

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');