LumAPI 1.1.0__tar.gz → 1.1.2__tar.gz

{lumapi-1.1.0 → lumapi-1.1.2}/LumAPI/lumapi.py

@@ -32,14 +32,28 @@ def savemat(filename, data_dict, version='v7.3', auto_transpose=True):
     bool
         写入成功返回 True。
     """
+    # 预处理字典，将所有整型转换为浮点型
+    processed_dict = {}
+    for key, val in data_dict.items():
+        data_array = np.asarray(val)
+        
+        # 对齐 MATLAB/scipy.io 的底层维度逻辑
+        # 强制将标量(0D)和一维数组(1D)提升为二维矩阵(1x1 或 1xN)
+        data_array = np.atleast_2d(data_array)
+        
+        # 针对 FDTD：将所有整数转为双精度浮点数
+        if np.issubdtype(data_array.dtype, np.integer):
+            data_array = data_array.astype(np.float64)
+            
+        processed_dict[key] = data_array
+
     if version == 'v7.3':
         import h5py
         with h5py.File(filename, 'w') as f:
-            for key, val in data_dict.items():
-                data_array = np.asarray(val)
+            for key, data_array in processed_dict.items():
                 
                 # 自动转置处理
-                if auto_transpose and data_array.ndim >= 2:
+                if auto_transpose:
                     data_array = data_array.T
                 
                 # 针对复数的特殊封装
@@ -57,16 +71,16 @@ def savemat(filename, data_dict, version='v7.3', auto_transpose=True):
     elif version == 'v7':
         import scipy.io
         # scipy.io 内部会自动处理 C-order 和 F-order 的转换，不需要手动转置
-        # 即使开启了 auto_transpose，为了保持形状一致，在此处也不做额外干预
-        scipy.io.savemat(filename, data_dict)
+        scipy.io.savemat(filename, processed_dict)
     else:
         raise ValueError("不支持的版本格式，请选择 'v7.3' 或 'v7'。")
     
     return True
 
-def loadmat(filename, auto_transpose=True):
+def loadmat(filename, auto_transpose=True, squeeze_me=True):
     """
-    自动检测版本并读取 MATLAB .mat 文件，支持自动多维数组转置恢复。
+    自动检测版本并读取 MATLAB .mat 文件，支持自动多维数组转置恢复，
+    并自动将数据格式转换为符合 Python 直觉的维度习惯。
 
     参数 (Parameters):
     ------------------
@@ -74,8 +88,10 @@ def loadmat(filename, auto_transpose=True):
         需要读取的 .mat 文件路径。
     auto_transpose : bool, 可选 (默认: True)
         是否自动处理 Python 和 MATLAB 的跨语言内存主序差异。
-        如果开启，且检测到是 v7.3 格式，会自动将读取到的多维数组转置回
-        MATLAB 中原本的维度顺序。
+    squeeze_me : bool, 可选 (默认: True)
+        是否开启数组压缩功能。
+        如果开启，会自动将 MATLAB 中的 1xN 或 Nx1 数组降维为真正的 1D NumPy 数组 (N,)。
+        同时会将 1x1 的矩阵提取为单纯的标量。
 
     返回 (Returns):
     ---------------
@@ -85,11 +101,12 @@ def loadmat(filename, auto_transpose=True):
     if not os.path.exists(filename):
         raise FileNotFoundError(f"找不到文件: {filename}")
 
-    # 读取魔法字节进行格式检测
+    # 读取魔法字节进行初步格式检测
     with open(filename, 'rb') as f:
         header = f.read(8)
     
     import h5py
+    # 判断是否为 v7.3 HDF5 格式
     is_v73 = h5py.is_hdf5(filename)
 
     data_dict = {}
@@ -104,24 +121,43 @@ def loadmat(filename, auto_transpose=True):
                     if data.dtype.names is not None and 'real' in data.dtype.names and 'imag' in data.dtype.names:
                         data = data['real'] + 1j * data['imag']
                     
-                    # 标量与转置处理
-                    if isinstance(data, np.ndarray) and data.shape == (1, 1):
-                        data = data[0, 0]
-                    elif isinstance(data, np.ndarray) and auto_transpose and data.ndim >= 2:
-                        data = data.T
+                    if isinstance(data, np.ndarray):
+                        # 标量与转置处理 (必须在 squeeze 之前转置，恢复实际物理形状)
+                        if auto_transpose and data.ndim >= 2:
+                            data = data.T
+                        
+                        # 维度压缩
+                        if squeeze_me:
+                            # np.squeeze 会自动剥离所有大小为 1 的维度
+                            data = np.squeeze(data)
+                        
+                        # 提取标量处理
+                        if data.ndim == 0:
+                            # 提取 0维 数组为真正的标量值 (但保留 numpy 数据类型)
+                            data = data[()]
+                        elif not squeeze_me and data.shape == (1, 1):
+                            # 如果用户关闭了压缩，但我们依然保持老版本的 1x1 标量提取兜底
+                            data = data[0, 0]
                             
                     data_dict[key] = data
     else:
         import scipy.io
-        mat_data = scipy.io.loadmat(filename)
+        # 对于 scipy，直接利用它内部极其完善的 squeeze_me 参数
+        mat_data = scipy.io.loadmat(filename, squeeze_me=squeeze_me)
         for key, val in mat_data.items():
             if not key.startswith('__'):
-                if isinstance(val, np.ndarray) and val.shape == (1, 1):
-                    val = val[0, 0]
+                if isinstance(val, np.ndarray):
+                    # scipy 在开启 squeeze_me 时，也会把 1x1 变成 0 维数组
+                    if val.ndim == 0:
+                        val = val[()]
+                    # 如果用户关闭了压缩，兜底提取 1x1
+                    elif not squeeze_me and val.shape == (1, 1):
+                        val = val[0, 0]
                 data_dict[key] = val
 
     return data_dict
 
+
 # *****************绘图增强函数******************
 def create_cmap(color_list, cmap_name="custom_cmap"):
     """
@@ -194,6 +230,7 @@ def set_colorbar_range(mappable, vmin, vmax):
     # 获取当前的 figure 并请求重新绘制以更新显示
     plt.draw()
 
+
 # *****************近远场变换函数*****************
 def Estimate_focal(lamb, r, focal_theory):
     '''
@@ -942,6 +979,7 @@ def AngularSpectrum_Vector(lamb, x_near, y_near, E_near_x, E_near_y, x_far, y_fa
     else:
         raise ValueError("Invalid mode. Please use 'fft' or 'numba'.")
 
+
 # ***************lumerical相关函数***************
 def detect_version(lumerical_root):
     """检测Lumerical安装目录下的有效版本号"""
@@ -1076,10 +1114,34 @@ class lumerical:
         return INTERCONNECT(self.lumapi, filename, key, hide, serverArgs, remoteArgs, **kwargs)
 
 class LumFuncBase:
-    """Lumerical 功能基类，处理通用的 API 转发和参数预处理"""
-    def __init__(self, target_handle):
-        # 隐藏内部句柄，避免与转发逻辑冲突
-        self._handle = target_handle
+    """Lumerical 功能基类，处理通用的 API 转发、兼容性初始化和参数预处理"""
+    def __init__(self, lumapi_module, product_name, filename=None, key=None, hide=False, serverArgs=None, remoteArgs=None, **kwargs):
+        # 修复 Python 可变默认参数陷阱
+        if serverArgs is None:
+            serverArgs = {}
+        if remoteArgs is None:
+            remoteArgs = {}
+
+        # 动态获取对应的 Lumerical 构造函数 (例如 lumapi_module.FDTD)
+        target_constructor = getattr(lumapi_module, product_name)
+
+        try:
+            # 首先尝试 v24R1 及更新版本的完整参数调用
+            self._handle = target_constructor(
+                filename=filename, key=key, hide=hide, 
+                serverArgs=serverArgs, remoteArgs=remoteArgs, **kwargs
+            )
+        except TypeError as e:
+            # 捕获旧版本不支持 remoteArgs 的错误并降级调用
+            if 'remoteArgs' in str(e) or 'unexpected keyword argument' in str(e):
+                self._handle = target_constructor(
+                    filename=filename, key=key, hide=hide, 
+                    serverArgs=serverArgs, **kwargs
+                )
+            else:
+                raise # 其他 TypeError 原样抛出
+
+        self.filename = filename
 
     def _process_arg(self, arg):
         """
@@ -1088,11 +1150,11 @@ class LumFuncBase:
         2. 一维 ndarray (len > 1) -> 二维 [[...]]
         """
         if isinstance(arg, np.ndarray):
-            # 规则 1: 检查是否为整型数组并转换
+            # 检查是否为整型数组并转换
             if np.issubdtype(arg.dtype, np.integer):
                 arg = arg.astype(float)
             
-            # 规则 2: 检查一维数组且长度不为 1，进行升维
+            # 检查一维数组且长度不为 1，进行升维
             if arg.ndim == 1 and arg.shape[0] != 1:
                 arg = arg[np.newaxis, :]
         return arg
@@ -1129,28 +1191,20 @@ class LumFuncBase:
             pass
     
 class FDTD(LumFuncBase):
-    def __init__(self, lumapi, filename=None, key=None, hide=False, serverArgs={}, remoteArgs={}, **kwargs):
-        handle = lumapi.FDTD(filename, key, hide, serverArgs, remoteArgs, **kwargs)
-        super().__init__(handle)
-        self.filename = filename
+    def __init__(self, lumapi, filename=None, key=None, hide=False, serverArgs=None, remoteArgs=None, **kwargs):
+        super().__init__(lumapi, 'FDTD', filename, key, hide, serverArgs, remoteArgs, **kwargs)
 
 class MODE(LumFuncBase):
-    def __init__(self, lumapi, filename=None, key=None, hide=False, serverArgs={}, remoteArgs={}, **kwargs):
-        handle = lumapi.MODE(filename, key, hide, serverArgs, remoteArgs, **kwargs)
-        super().__init__(handle)
-        self.filename = filename
+    def __init__(self, lumapi, filename=None, key=None, hide=False, serverArgs=None, remoteArgs=None, **kwargs):
+        super().__init__(lumapi, 'MODE', filename, key, hide, serverArgs, remoteArgs, **kwargs)
 
 class DEVICE(LumFuncBase):
-    def __init__(self, lumapi, filename=None, key=None, hide=False, serverArgs={}, remoteArgs={}, **kwargs):
-        handle = lumapi.DEVICE(filename, key, hide, serverArgs, remoteArgs, **kwargs)
-        super().__init__(handle)
-        self.filename = filename
+    def __init__(self, lumapi, filename=None, key=None, hide=False, serverArgs=None, remoteArgs=None, **kwargs):
+        super().__init__(lumapi, 'DEVICE', filename, key, hide, serverArgs, remoteArgs, **kwargs)
 
 class INTERCONNECT(LumFuncBase):
-    def __init__(self, lumapi, filename=None, key=None, hide=False, serverArgs={}, remoteArgs={}, **kwargs):
-        handle = lumapi.INTERCONNECT(filename, key, hide, serverArgs, remoteArgs, **kwargs)
-        super().__init__(handle)
-        self.filename = filename
+    def __init__(self, lumapi, filename=None, key=None, hide=False, serverArgs=None, remoteArgs=None, **kwargs):
+        super().__init__(lumapi, 'INTERCONNECT', filename, key, hide, serverArgs, remoteArgs, **kwargs)
     
 lumapi = lumerical()
 

{lumapi-1.1.0 → lumapi-1.1.2/LumAPI.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: LumAPI
-Version: 1.1.0
+Version: 1.1.2
 Summary: Lumerical Python API 自动化配置工具
 Author-email: JaniQuiz <janiquiz@163.com>
 Maintainer-email: JaniQuiz <janiquiz@163.com>
@@ -32,23 +32,30 @@ Dynamic: license-file
 * **API 增强**：支持原本接口，并对原本接口参数进行优化。
 * **衍射积分函数**：封装了个人常用的衍射积分函数，且每个衍射积分函数结果均进行了验证。
 * **数据保存读取**：封装了matlab数据文件.mat的读取和写入函数，方便与其他软件进行数据交互。
-
+* **绘图函数增强**：封装了一些常用的matplotlib绘图功能，方便快速绘制合适的图像。
 
 
 ## 📦 如何安装 
 [安装方式](install.md)
 
-## 📖 衍射积分函数验证文档
-为确保我们的衍射积分函数的准确性，我们进行了验证，见[文档目录](docs/menu.md)
+## 🗂️ 文档目录
+
+### 使用指南
 
-## 💻 使用指南
  - [使用文档](docs/usage.md)
- - [相关案例](docs/methods.md)
+ - [使用案例](docs/methods.md)
+
+### 衍射积分函数验证
+
+ - [基尔霍夫(Kirchhoff)标量衍射积分函数验证](docs/Kirchhoff.md)
+ - [瑞利-索末菲(Rayleigh-Sommerfeld)标量衍射积分函数验证](docs/Rayleigh-Sommerfeld_Scalar.md)
+ - [瑞利-索末菲(Rayleigh-Sommerfeld)矢量衍射积分函数验证](docs/Rayleigh-Sommerfeld_Vector.md)
+ - [矢量角谱(Angular Spectrum)矢量衍射积分函数验证](docs/AngularSpectrum_Vector.md)
 
-## 许可证
+## 📜 许可证
 本库遵循[GPL-3.0](https://www.gnu.org/licenses/gpl-3.0.html)开源许可证
 
-## 联系作者
+## 📧 联系作者
  - **作者**: [JaniQuiz](https://github.com/JaniQuiz)  
  - **邮箱**: janiquiz@163.com
  - **项目主页**: [LumAPI](https://github.com/JaniQuiz/LumAPI)

{lumapi-1.1.0/LumAPI.egg-info → lumapi-1.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: LumAPI
-Version: 1.1.0
+Version: 1.1.2
 Summary: Lumerical Python API 自动化配置工具
 Author-email: JaniQuiz <janiquiz@163.com>
 Maintainer-email: JaniQuiz <janiquiz@163.com>
@@ -32,23 +32,30 @@ Dynamic: license-file
 * **API 增强**：支持原本接口，并对原本接口参数进行优化。
 * **衍射积分函数**：封装了个人常用的衍射积分函数，且每个衍射积分函数结果均进行了验证。
 * **数据保存读取**：封装了matlab数据文件.mat的读取和写入函数，方便与其他软件进行数据交互。
-
+* **绘图函数增强**：封装了一些常用的matplotlib绘图功能，方便快速绘制合适的图像。
 
 
 ## 📦 如何安装 
 [安装方式](install.md)
 
-## 📖 衍射积分函数验证文档
-为确保我们的衍射积分函数的准确性，我们进行了验证，见[文档目录](docs/menu.md)
+## 🗂️ 文档目录
+
+### 使用指南
 
-## 💻 使用指南
  - [使用文档](docs/usage.md)
- - [相关案例](docs/methods.md)
+ - [使用案例](docs/methods.md)
+
+### 衍射积分函数验证
+
+ - [基尔霍夫(Kirchhoff)标量衍射积分函数验证](docs/Kirchhoff.md)
+ - [瑞利-索末菲(Rayleigh-Sommerfeld)标量衍射积分函数验证](docs/Rayleigh-Sommerfeld_Scalar.md)
+ - [瑞利-索末菲(Rayleigh-Sommerfeld)矢量衍射积分函数验证](docs/Rayleigh-Sommerfeld_Vector.md)
+ - [矢量角谱(Angular Spectrum)矢量衍射积分函数验证](docs/AngularSpectrum_Vector.md)
 
-## 许可证
+## 📜 许可证
 本库遵循[GPL-3.0](https://www.gnu.org/licenses/gpl-3.0.html)开源许可证
 
-## 联系作者
+## 📧 联系作者
  - **作者**: [JaniQuiz](https://github.com/JaniQuiz)  
  - **邮箱**: janiquiz@163.com
  - **项目主页**: [LumAPI](https://github.com/JaniQuiz/LumAPI)

{lumapi-1.1.0 → lumapi-1.1.2}/README.md

@@ -8,23 +8,30 @@
 * **API 增强**：支持原本接口，并对原本接口参数进行优化。
 * **衍射积分函数**：封装了个人常用的衍射积分函数，且每个衍射积分函数结果均进行了验证。
 * **数据保存读取**：封装了matlab数据文件.mat的读取和写入函数，方便与其他软件进行数据交互。
-
+* **绘图函数增强**：封装了一些常用的matplotlib绘图功能，方便快速绘制合适的图像。
 
 
 ## 📦 如何安装 
 [安装方式](install.md)
 
-## 📖 衍射积分函数验证文档
-为确保我们的衍射积分函数的准确性，我们进行了验证，见[文档目录](docs/menu.md)
+## 🗂️ 文档目录
+
+### 使用指南
 
-## 💻 使用指南
  - [使用文档](docs/usage.md)
- - [相关案例](docs/methods.md)
+ - [使用案例](docs/methods.md)
+
+### 衍射积分函数验证
+
+ - [基尔霍夫(Kirchhoff)标量衍射积分函数验证](docs/Kirchhoff.md)
+ - [瑞利-索末菲(Rayleigh-Sommerfeld)标量衍射积分函数验证](docs/Rayleigh-Sommerfeld_Scalar.md)
+ - [瑞利-索末菲(Rayleigh-Sommerfeld)矢量衍射积分函数验证](docs/Rayleigh-Sommerfeld_Vector.md)
+ - [矢量角谱(Angular Spectrum)矢量衍射积分函数验证](docs/AngularSpectrum_Vector.md)
 
-## 许可证
+## 📜 许可证
 本库遵循[GPL-3.0](https://www.gnu.org/licenses/gpl-3.0.html)开源许可证
 
-## 联系作者
+## 📧 联系作者
  - **作者**: [JaniQuiz](https://github.com/JaniQuiz)  
  - **邮箱**: janiquiz@163.com
  - **项目主页**: [LumAPI](https://github.com/JaniQuiz/LumAPI)

{lumapi-1.1.0 → lumapi-1.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "LumAPI"
-version = "1.1.0"
+version = "1.1.2"
 authors = [
     {name = "JaniQuiz", email = "janiquiz@163.com"},
 ]