Python API的设置

本节是关于Python API接口相关设置和用法的介绍。

SimWorks提供了名为simworks的Python的应用程序编程接口模块（API），允许用户通过Python脚本与SimWorks仿真软件（如FDTD、FDE、FDFD）进行交互，实现：

启动仿真引擎
构建器件结构
设置材料、光源、监视器、边界条件
运行仿真
提取仿真结果
批量自动化仿真任务

这个Python API接口，使得数据处理、自动化执行仿真、参数优化、高性能计算等具有更高自由度，满足用户的二次开发等高级需求。

Python API的初始环境配置

下面介绍如何配置Python环境，使其能够正确加载SimWorks仿真软件的本地 DLL 和 Python API模块。

Windows

为了实现SimWorks Finite Difference Solutions与Python编程语言的交互，需要用户已经在本机上安装Python.exe，推荐python 3.12及以上的版本。如果您没有安装，推荐您免费下载Python 开发工具PyCharm 。
SimWorks Python API模块，需要使用numpy库，因此建议使用pip等工具进行安装。
需要将simworks.py的目录附在当前目录上，使用append()函数添加带有接口模块的路径，让import类可以成功检索到simworks模块。下面以软件默认安装路径为例说明:

import os, sys
os.add_dll_directory(r"C:\Program Files\SimWorks\SimWorks FD Solutions beta\bin")
sys.path.append(r"C:\Program Files\SimWorks\SimWorks FD Solutions beta\api\python")
import simworks
import numpy as np

Linux

使用本功能需预先安装 Python 及 numpy 库。若尚未安装，请根据您的操作系统参考相应的安装指南进行配置。
确保AppImage文件可执行

chmod +x appimage_file.AppImage

使用 --appimage-extract选项解压

./appimage_file.AppImage --appimage-extract

需要将simworks.py的目录附在当前目录上

import sys, os
sys.path.append("squashfs-root/api/usr/api/python/")

macOS

使用本功能需预先安装 Python 及 numpy 库。若尚未安装，请根据您的操作系统参考相应的安装指南进行配置。
未安装到Applications，打开SimWorks软件.dmg镜像文件，找到对应“挂载”的一个虚拟磁盘，最后在这个磁盘中找到 Contents/api/python/。
已安装到Applications，进入Applications找到SimWorks FD Solutions.app，然后显示包内容，最终找到Contents/api/python/。

Python API的代码示范

在Python中，几乎所有的SimWorks内置的脚本语言都可以当作方法使用，simworks接口中定义的方法和内置的脚本命令具有相同的名称，在创建会话后可以直接调用，具体实现请见下面的代码：


import os
import sys

os.add_dll_directory(r"C:\Program Files\SimWorks\SimWorks FD Solutions beta\bin")
sys.path.append(r"C:\Program Files\SimWorks\SimWorks FD Solutions beta\api\python")

import simworks
import numpy as np

if __name__ == "__main__":
    with simworks.FD() as fd:

        # Add fdtd solver
        fd.addfdtd()
        fd.set("x",0)
        fd.set("x span", 8e-6)
        fd.set("y",0)
        fd.set("y span",3e-6)
        fd.set("z",0)
        fd.set("z span",3e-6)
        fd.set("boundary conditions x max","PML")
        fd.set("boundary conditions x min","PML")
        fd.set("boundary conditions y max","periodic")
        fd.set("boundary conditions y min","periodic")
        fd.set("boundary conditions z max","PML")
        fd.set("boundary conditions z min","PML")

        # Add rectangle structure
        fd.addrect()
        fd.set("x", 0)
        fd.set("x span", 0.5e-6)
        fd.set("y", 1e-6)
        fd.set("y span", 2e-6)
        fd.set("z", 0)
        fd.set("z span", 2e-6)

        # Set the material of rectangle
        fd.set("material", "Ag (Silver)_CRC")

        # Save project
        fd.saveproject('F:\\pythondebug\\runfdtd.mpps')

        # Source
        fd.addplane()
        fd.set('direction', 'Forward')
        fd.set('incident axis', 'x')
        fd.set('x', -2e-6)
        fd.set('y', 0)
        fd.set('y span', 6e-6)
        fd.set('z', 0)
        fd.set('z span', 6e-6)
        fd.set('central wavelength', 1550e-9)
        fd.set('wavelength span', 0)

        # Monitor
        fd.addpowermonitor()
        fd.set("name", "T")
        fd.set("spatial type", "2D X normal")
        fd.set("x", 2e-6)
        fd.set("y", 0)
        fd.set("z", 0)
        fd.set("y span", 6e-6)
        fd.set("z span", 6e-6)

        # Run FDTD
        fd.run()

        # Obtain the simulation results
        Ex = fd.getdata("FDTD::T", "E", "Ex")
        f = fd.getdata("FDTD::T", "E", "f")
        sp = fd.getdata("FDTD::Plane", "sourcepower", "sourcepower")

        print("done")

下面介绍SimWorks和Python在simworks接口上的数据传递。用Python API启动SimWorks Finite Difference Solutions的仿真软件时，建立了两者环境之间的联系，彼此的工作空间不共享，而是在变量传递过程中创建一个相同的副本，根据getv( )和put( )函数中定义的转换类型来进行前传和后传。

SimWorks API支持的数据类型为：Real/Complex/Sring/Matrix/Struct/Cell/Dataset(matrixdataset and unstructureddataset)，具体实现请见下面的代码：


import os
import sys

os.add_dll_directory(r"C:\Program Files\SimWorks\SimWorks FD Solutions beta\bin")
sys.path.append(r"C:\Program Files\SimWorks\SimWorks FD Solutions beta\api\python")

import simworks
import numpy as np

if __name__ == "__main__":
    with simworks.Simworks('fd') as fd:

        # Run the defined scripts in the SimWorks GUI
        fd.eval("addpoly;")
        # Generate various data types
        fd.eval("str = 'test string content';")
        fd.eval(f"mdmds = reshape({[str(i) + str(i + 1) for i in range(3*4*5)]}, [3, 4, 5]);")
        fd.eval("mdc = [1+2j, 3+4j; 5+6j, 7+8j];")
        fd.eval("C = {1, 2, 3; 'text', rand(5,10,2), {11; 22; 33} };")
        fd.eval("E2=struct()")  
        fd.eval("E2.x=1;E2.y=2;E2.f=1.55e-6;E2.Ex=rand(5,5);")
        # Generate the combination of allowed data types
        fd.eval("{0} = struct;".format(field_result_name) +
              "{0}.E = getdata('{1}','E');".format(field_result_name, monitor_name))

      
        # Get variables from SimWorks FD Solutions
        var_str = fd.getv("str")
        var_mdmds = fd.getv("mdmds")
        var_mdc = fd.getv("mdc")
        var_cellA=fd.getv("C")
        var_E=fd.getv("E2")


        # Put variables from Python back to SimWorks FD Solutions
        fd.putv("num", np.array([12, 13]))
        fd.putv("putcomplex_np_mat", np.array([[1 + 2j, 3 + 4j], [5 + 6j, 7 + 8j]]))
        fd.putv("put_mdmdr", np.arange(3 * 4 * 5).reshape([3, 4, 5]))
        fd.putv("putstrmat", np.array([["123", "45678", "6789"], ['9101112', '13141516171819', '1457']], order='F'))  
        fd.putv("putemptystrmat", np.array([], dtype=np.str_))
        fd.putv("putcell",var_cellA)
        fd.putv("putstruct",var_E)

        fd.savematlabmatfile('Y:\\pythondebug\\struct.mat')
     

    print("done")

Python API的设置 #

Python API的初始环境配置 #

Windows #

Linux #

macOS #