osis-python 0.6.1__tar.gz → 0.6.2__tar.gz

{osis_python-0.6.1/src/osis_python.egg-info → osis_python-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: osis-python
-Version: 0.6.1
+Version: 0.6.2
 Summary: A Python client library for Osis APDL
 Author-email: "CCCC Highway Consultant Co. Ltd." <support@osisbim.com>
 License-Expression: MIT

{osis_python-0.6.1 → osis_python-0.6.2/src/osis_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: osis-python
-Version: 0.6.1
+Version: 0.6.2
 Summary: A Python client library for Osis APDL
 Author-email: "CCCC Highway Consultant Co. Ltd." <support@osisbim.com>
 License-Expression: MIT

{osis_python-0.6.1 → osis_python-0.6.2}/src/pyosis/__init__.py

@@ -7,7 +7,7 @@ A library for extending OSIS functionality.
 A library that allows users to use CAE with great flexibility.
 """
 
-__version__ = "0.6.1"
+__version__ = "0.6.2"
 __author__ = "CCCC Highway Consultant Co. Ltd." # 中交公路规划设计院 - 工程技术研究中心 - lzh - wjh - myf
 
 from .core.engine import OSISEngine

{osis_python-0.6.1 → osis_python-0.6.2}/src/pyosis/boundary/manager.py

@@ -497,14 +497,14 @@ class BoundaryGroupManager:
         ...
 
     def _load(self) -> list[BoundaryGroup]:
-        """从服务端加载所有边界组信息"""
+        '''从服务端加载所有边界组信息'''
         resp = osis_client("GetAllBoundaryGroupInfo", {})
         if not resp["success"]:
             raise RuntimeError(resp["error"])
-        
+
         groups = [
-            BoundaryGroup._from_dict(d) 
-            for d in resp.get("data", []) 
+            BoundaryGroup._from_dict(d)
+            for d in resp.get("data", [])
             if isinstance(d, dict) and "groupName" in d
         ]
         return groups
@@ -512,31 +512,50 @@ class BoundaryGroupManager:
     # ── 增删改 ────────────────────────────────
 
     def create(self, name: str, op:Literal["c", "a", "s", "r", "aa", "ra", "m", "d"], *param) -> BoundaryGroup:
-        """创建边界组
+        '''创建边界组并返回刷新后的对象
 
         Args:
             name: 边界组名称
-            op: 操作
+            op: 操作类型
+                * c = 创建
+                * a = 添加
+                * s = 替换
+                * r = 移除
+                * aa = 添加全部
+                * ra = 移除全部
+                * m = 修改组名
+                * d = 删除
+            *param: 待操作的编号，支持格式：*，*to*；*by*（仅用于替换）。
+                例子：[2,3,5,"8to10"] ["2by3","5by6","8by10"] 重合的编号自动忽略
+
         Returns:
-            创建的 BoundaryGroup 对象
-        """
+            BoundaryGroup: 创建（或刷新后的）边界组对象
+        '''
         ok, err = osis_boundary_group(name, op, *param)
         if not ok:
             raise RuntimeError(f"创建边界组 {name} 失败: {err}")
         return self.get(name)
 
     def delete(self, name: str) -> None:
-        """删除边界组
+        '''删除边界组
 
         Args:
             name: 边界组名称
-        """
+
+        Raises:
+            RuntimeError: 删除失败时抛出异常
+        '''
         ok, err = osis_boundary_group(name, "d")
         if not ok:
             raise RuntimeError(f"删除边界组 {name} 失败: {err}")
         
     def rename(self, old_name, new_name) -> None:
-        """修改边界组名"""
+        '''修改边界组名称
+
+        Args:
+            old_name: 原边界组名称
+            new_name: 新边界组名称
+        '''
         ok, err = osis_boundary_group(old_name, "m", [new_name])
         if not ok:
             raise RuntimeError(f"修改边界组名  {old_name} -> {new_name} 失败:  失败: {err}")
@@ -575,15 +594,18 @@ class BoundaryGroupManager:
         return boundary_groups
     
     def all(self) -> list[BoundaryGroup]:
-        """获取所有边界组"""
+        '''获取所有边界组'''
         return self._load()
 
     def count(self) -> int:
-        """获取边界组总数"""
+        '''获取边界组总数'''
         return len(self._load())
 
     def clear(self) -> None:
-        """清空所有边界组"""
+        '''清空所有边界组
+
+        逐个删除服务端的所有边界组；若任一边界组被占用则抛出异常。
+        '''
         try:
             [self.delete(bg.name) for bg in self.all()]
         except Exception as e:
@@ -624,23 +646,30 @@ class BoundaryManager:
         resp = osis_client("GetAllBoundaryInfo", {})
         if not resp["success"]:
             raise RuntimeError(f"{resp['error']}")
-        
+
         boundaries = [
-            Boundary._from_dict(d) 
-            for d in resp.get("data", []) 
+            Boundary._from_dict(d)
+            for d in resp.get("data", [])
             if isinstance(d, dict) and "no" in d
         ]
         return boundaries
 
     def _next_no(self) -> int:
-        """生成下一个可用边界编号"""
+        """返回下一个可用的边界编号（当前最大编号 + 1，空模型为 1）"""
         boundaries = self._load()
         if not boundaries:
             return 1
         return max(bd.no for bd in boundaries) + 1
 
     def get_dependencies(self, no: int) -> dict[str, list]:
-        """查询边界被谁引用"""
+        """查询边界被哪些对象引用（用于删除前检查占用情况）
+
+        Args:
+            no: 边界编号
+
+        Returns:
+            dict[str, list]: 依赖项字典，键为引用类型，值为引用编号列表
+        """
         return get_references("Boundary", no=no)
 
     # ── 增删改 ────────────────────────────────
@@ -690,7 +719,28 @@ class BoundaryManager:
         rz: bool = 1,
         rw: bool = 1,
     ) -> GeneralBoundary:
-        """创建一般边界"""
+        '''创建一般支撑边界
+
+        在指定节点上约束 7 个自由度（UX/UY/UZ/RX/RY/RZ/RW），
+        可基于局部坐标系或全局坐标系。
+
+        Args:
+            no: 边界编号，None 时自动分配
+            coor: 局部坐标系编号，"" 代表缺省（使用全局坐标系）
+            x: UX 方向约束标志，0 = 释放，1 = 约束
+            y: UY 方向约束标志，0 = 释放，1 = 约束
+            z: UZ 方向约束标志，0 = 释放，1 = 约束
+            rx: RX 方向约束标志，0 = 释放，1 = 约束
+            ry: RY 方向约束标志，0 = 释放，1 = 约束
+            rz: RZ 方向约束标志，0 = 释放，1 = 约束
+            rw: RW（翘曲）方向约束标志，0 = 释放，1 = 约束
+
+        Returns:
+            GeneralBoundary 对象
+
+        Examples:
+            >>> boundary_manager.create_general(None, x=1, y=1, z=1)
+        '''
         if no is None:
             no = self._next_no()
         ok, err = osis_boundary_general(no, "GENERAL", coor or "", x, y, z, rx, ry, rz, rw)
@@ -710,7 +760,28 @@ class BoundaryManager:
         rz: bool = 1,
         coincident: int | None = 1,
     ) -> MstSlvBoundary:
-        """创建主从约束"""
+        '''创建主从约束
+
+        将已分配本边界的从节点与指定的主节点在 6 个自由度上耦合，
+        常用于模拟桥梁支座、铰接等连接关系。
+
+        Args:
+            no: 边界编号，None 时自动分配
+            node: 主节点编号
+            dx: UX 方向耦合标志，0 = 释放，1 = 约束
+            dy: UY 方向耦合标志，0 = 释放，1 = 约束
+            dz: UZ 方向耦合标志，0 = 释放，1 = 约束
+            rx: RX 方向耦合标志，0 = 释放，1 = 约束
+            ry: RY 方向耦合标志，0 = 释放，1 = 约束
+            rz: RZ 方向耦合标志，0 = 释放，1 = 约束
+            coincident: 0 = 仅同位移约束；1 = 完全主从约束（含转动耦合），默认 1
+
+        Returns:
+            MstSlvBoundary 对象
+
+        Examples:
+            >>> boundary_manager.create_master_slave(None, node=10, coincident=1)
+        '''
         if no is None:
             no = self._next_no()
         ok, err = osis_boundary_master_slave(no, "MSTSLV", node, dx, dy, dz, rx, ry, rz,coincident)
@@ -730,7 +801,52 @@ class BoundaryManager:
         fxj: float,fyj: float,fzj: float,
         mxj: float,myj: float,mzj: float,mbj: float,
     ) -> ReleaseBoundary:
-        """创建释放梁端约束"""
+        '''创建释放梁端约束
+
+        在梁单元的 I 端和 J 端分别释放 7 个自由度（FX/FY/FZ/MX/MY/MZ/MB），
+        每个自由度通过 _state（0 = 完全释放，1 = 完全约束）和对应 _value（0-1 之间，
+        表示释放后残余约束能力的百分比）共同控制。
+
+        Args:
+            no: 边界编号，None 时自动分配
+            fxi_state: I 端 FX（轴力）状态，0 = 释放，1 = 约束
+            fyi_state: I 端 FY（剪力）状态，0 = 释放，1 = 约束
+            fzi_state: I 端 FZ（剪力）状态，0 = 释放，1 = 约束
+            mxi_state: I 端 MX（扭矩）状态，0 = 释放，1 = 约束
+            myi_state: I 端 MY（弯矩）状态，0 = 释放，1 = 约束
+            mzi_state: I 端 MZ（弯矩）状态，0 = 释放，1 = 约束
+            mbi_state: I 端 MB（双力矩）状态，0 = 释放，1 = 约束
+            fxi: I 端 FX 部分约束残余百分比（0-1）
+            fyi: I 端 FY 部分约束残余百分比（0-1）
+            fzi: I 端 FZ 部分约束残余百分比（0-1）
+            mxi: I 端 MX 部分约束残余百分比（0-1）
+            myi: I 端 MY 部分约束残余百分比（0-1）
+            mzi: I 端 MZ 部分约束残余百分比（0-1）
+            mbi: I 端 MB 部分约束残余百分比（0-1）
+            fxj_state: J 端 FX 状态，0 = 释放，1 = 约束
+            fyj_state: J 端 FY 状态，0 = 释放，1 = 约束
+            fzj_state: J 端 FZ 状态，0 = 释放，1 = 约束
+            mxj_state: J 端 MX 状态，0 = 释放，1 = 约束
+            myj_state: J 端 MY 状态，0 = 释放，1 = 约束
+            mzj_state: J 端 MZ 状态，0 = 释放，1 = 约束
+            mbj_state: J 端 MB 状态，0 = 释放，1 = 约束
+            fxj: J 端 FX 部分约束残余百分比（0-1）
+            fyj: J 端 FY 部分约束残余百分比（0-1）
+            fzj: J 端 FZ 部分约束残余百分比（0-1）
+            mxj: J 端 MX 部分约束残余百分比（0-1）
+            myj: J 端 MY 部分约束残余百分比（0-1）
+            mzj: J 端 MZ 部分约束残余百分比（0-1）
+            mbj: J 端 MB 部分约束残余百分比（0-1）
+
+        Returns:
+            ReleaseBoundary 对象
+
+        Examples:
+            >>> boundary_manager.create_release(None, 1,1,1,1,1,1,1,
+            ...     1.0,1.0,1.0,1.0,1.0,1.0,1.0,
+            ...     0,0,0,1,1,1,1,
+            ...     0.0,0.0,0.0,1.0,1.0,1.0,1.0)
+        '''
         if no is None:
             no = self._next_no()
         ok, err = osis_boundary_release(
@@ -761,7 +877,35 @@ class BoundaryManager:
         rz: bool = 1,
         drz: float | int = 1e16,
     ) -> ElstcSptBoundary:
-        """创建弹性支承"""
+        '''创建节点弹性支承
+
+        在节点 6 个自由度上分别设置弹性约束或固定约束。
+        每个方向由一个标志位（0 = 弹性，1 = 固定）和对应的弹性刚度组成。
+        注：弹性支撑与一般边界固定的自由度相同，且弹性支撑其余自由度上约束为零时，
+        二者结果完全相同，不存在数值差异。
+
+        Args:
+            no: 边界编号，None 时自动分配
+            coor: 局部坐标系编号，"" 代表缺省
+            x: UX 方向，0 = 弹性，1 = 固定
+            dx: 坐标系 X 轴方向的弹性支承刚度
+            y: UY 方向，0 = 弹性，1 = 固定
+            dy: 坐标系 Y 轴方向的弹性支承刚度
+            z: UZ 方向，0 = 弹性，1 = 固定
+            dz: 坐标系 Z 轴方向的弹性支承刚度
+            rx: RX 方向，0 = 弹性，1 = 固定
+            drx: 绕坐标系 X 轴方向的转动弹性刚度
+            ry: RY 方向，0 = 弹性，1 = 固定
+            dry: 绕坐标系 Y 轴方向的转动弹性刚度
+            rz: RZ 方向，0 = 弹性，1 = 固定
+            drz: 绕坐标系 Z 轴方向的转动弹性刚度
+
+        Returns:
+            ElstcSptBoundary 对象
+
+        Examples:
+            >>> boundary_manager.create_elstcspt(None)
+        '''
         if no is None:
             no = self._next_no()
         ok, err = osis_boundary_elstcspt(
@@ -831,7 +975,10 @@ class BoundaryManager:
         no: int | None,
         nNodeI: int,
     ) -> Boundary:
-        """创建刚性连接
+        '''创建刚性连接
+
+        将主节点 nNodeI 与通过 assign 分配的从节点绑定为刚性区域，
+        刚性区域内所有节点的 6 个自由度保持完全一致。
 
         Args:
             no: 边界编号，None 时自动分配
@@ -841,8 +988,8 @@ class BoundaryManager:
             Boundary 对象
 
         Notes:
-            用于形成刚性区域的节点号 nodeJ, nodeK, ..., nodeL 由 assign 方法定义
-        """
+            用于形成刚性区域的从节点号 nodeJ, nodeK, ..., nodeL 由 assign 方法定义。
+        '''
         if no is None:
             no = self._next_no()
         ok, err = osis_boundary_rigid(no, "RIGID", nNodeI)
@@ -866,21 +1013,28 @@ class BoundaryManager:
     # ── 查询 ──────────────────────────────────
 
     def get(self, no: int | list[int]) -> Boundary | list[Boundary | None] | None:
-        """根据编号获取单个或多个边界 (O(k))
-        
-        接口：GetBoundaryInfoByNos
-        """
+        '''根据编号获取单个或多个边界（O(k)）
+
+        内部调用接口 GetBoundaryInfoByNos。
+
+        Args:
+            no: 边界编号，支持单个 int 或编号列表
+
+        Returns:
+            单个 Boundary 对象；如果传入列表则按顺序返回对象列表；
+            不存在返回 None
+        '''
         if isinstance(no, int):
             no = [no]
         elif not isinstance(no, list):
             raise TypeError(f"不支持的编号类型: {type(no)}")
-        
+
         resp = osis_client("GetBoundaryInfoByNos", {"no": no})
         if not resp['success']:
             raise RuntimeError(f"{resp['error']}")
-        
+
         boundaries = [Boundary._from_dict(d) if d else None for d in resp.get("data", [])]
-        
+
         if len(boundaries) == 0:
             return None
         elif len(boundaries) == 1:
@@ -888,15 +1042,18 @@ class BoundaryManager:
         return boundaries
 
     def all(self) -> list[Boundary]:
-        """获取所有边界"""
+        '''获取所有边界'''
         return self._load()
 
     def count(self) -> int:
-        """获取边界总数"""
+        '''获取边界总数'''
         return len(self._load())
 
     def clear(self) -> None:
-        """清空所有边界"""
+        '''清空所有边界
+
+        逐个删除服务端的所有边界；若任一边界被占用则抛出异常。
+        '''
         try:
             [self.delete(b.no) for b in self.all()]
         except Exception as e:

{osis_python-0.6.1 → osis_python-0.6.2}/src/pyosis/control/manager.py

@@ -67,26 +67,50 @@ class ControlManager:
 
 
     def set_gravity_acceleration(self, g: float = 9.8066) -> None:
-        """设置重力加速度值，默认 9.8066 m/s²"""
+        '''设置整体坐标系下三个方向的重力加速度分量
+
+        Args:
+            g (float): 重力加速度值，默认 9.8066 m/s²
+
+        Returns:
+            None
+
+        Raises:
+            RuntimeError: 设置失败时抛出异常
+        '''
         ok, err = osis_acel(g)
         if not ok:
             raise RuntimeError(f"设置重力加速度失败: {err}")
 
     def export_apdl(self, path: str | None = None) -> None:
-        """导出前处理状态为 .out 文件"""
+        '''导出当前前处理状态到 APDL .out 文件
+
+        Args:
+            path (str | None): 输出文件完整路径，可缺省；不传则使用程序当前路径
+
+        Returns:
+            None
+
+        Raises:
+            RuntimeError: 导出失败时抛出异常
+        '''
         ok, err = osis_apdl(path)
         if not ok:
             raise RuntimeError(f"导出 APDL 文件失败: {err}")
         
     def import_apdl(self, path: str | None = None) -> None:
-        """读取 .out / .sml 文件
+        '''读取 APDL .out / .sml 文件
 
         Args:
-            path (str): 完整文件名
-         
-        Notes: 
-            path 中如果不输入绝对路径的话，默认使用程序执行文件所在的路径，比如“D:\\Rbin\\X.sml”。
-        """
+            path (str): 完整文件名，可缺省。path 中如果不输入绝对路径的话，
+                默认使用程序执行文件所在的路径，例如 "D:\\\\Rbin\\\\X.sml"。
+
+        Returns:
+            None
+
+        Raises:
+            RuntimeError: 导入失败时抛出异常
+        '''
         ok, err = osis_run(f"/input,{path}")
         if not ok:
             raise RuntimeError(f"导入 APDL 文件失败: {err}")
@@ -95,49 +119,129 @@ class ControlManager:
     # ── 材料效应开关 ────────────────────────────
 
     def set_calc_tendon(self, enabled: Literal[0,1] = 1) -> None:
-        """是否计算预应力"""
+        '''设置是否计算预应力效应
+
+        Args:
+            enabled (int): 1=开，0=关
+
+        Returns:
+            None
+
+        Raises:
+            RuntimeError: 设置失败时抛出异常
+        '''
         ok, err = osis_calc_tendon(enabled)
         if not ok:
             raise RuntimeError(f"设置预应力计算失败: {err}")
 
     def set_calc_concurrent_force(self, enabled: Literal[0,1] = 1) -> None:
-        """是否计算并发反力"""
+        '''设置是否计算并发反力
+
+        Args:
+            enabled (int): 1=开，0=关
+
+        Returns:
+            None
+
+        Raises:
+            RuntimeError: 设置失败时抛出异常
+        '''
         ok, err = osis_calc_con_force(enabled)
         if not ok:
             raise RuntimeError(f"设置并发反力计算失败: {err}")
 
     def set_calc_shrink(self, enabled: Literal[0,1] = 1) -> None:
-        """是否计算收缩"""
+        '''设置是否计算收缩
+
+        Args:
+            enabled (int): 1=开，0=关
+
+        Returns:
+            None
+
+        Raises:
+            RuntimeError: 设置失败时抛出异常
+        '''
         ok, err = osis_calc_shrink(enabled)
         if not ok:
             raise RuntimeError(f"设置收缩计算失败: {err}")
 
     def set_calc_creep(self, enabled: Literal[0,1] = 1) -> None:
-        """是否计算徐变"""
+        '''设置是否计算徐变
+
+        Args:
+            enabled (int): 1=开，0=关
+
+        Returns:
+            None
+
+        Raises:
+            RuntimeError: 设置失败时抛出异常
+        '''
         ok, err = osis_calc_creep(enabled)
         if not ok:
             raise RuntimeError(f"设置徐变计算失败: {err}")
 
     def set_calc_shear(self, enabled: Literal[0,1] = 1) -> None:
-        """是否计算剪切"""
+        '''设置是否计算剪切变形
+
+        Args:
+            enabled (int): 1=开，0=关
+
+        Returns:
+            None
+
+        Raises:
+            RuntimeError: 设置失败时抛出异常
+        '''
         ok, err = osis_calc_shear(enabled)
         if not ok:
             raise RuntimeError(f"设置剪切计算失败: {err}")
 
     def set_calc_relaxation(self, enabled: Literal[0,1] = 1) -> None:
-        """是否计算钢束松弛"""
+        '''设置是否计算钢束松弛
+
+        Args:
+            enabled (int): 1=开，0=关
+
+        Returns:
+            None
+
+        Raises:
+            RuntimeError: 设置失败时抛出异常
+        '''
         ok, err = osis_calc_rlx(enabled)
         if not ok:
             raise RuntimeError(f"设置钢束松弛计算失败: {err}")
 
     def set_mod_loc_coor(self, enabled: Literal[0,1] = 1) -> None:
-        """是否修改变截面单元局部坐标轴来计算内力/应力"""
+        '''设置是否修改变截面单元局部坐标轴以计算内力/应力
+
+        Args:
+            enabled (int): 1=开，0=关
+
+        Returns:
+            None
+
+        Raises:
+            RuntimeError: 设置失败时抛出异常
+        '''
         ok, err = osis_mod_loc_coor(enabled)
         if not ok:
             raise RuntimeError(f"设置局部坐标轴修正失败: {err}")
 
     def set_inc_tendon(self, enabled: Literal[0,1] = 1) -> None:
-        """是否考虑钢束自重及钢束对截面几何特性的影响"""
+        '''设置是否考虑钢束自重及钢束对截面几何特性的影响
+
+        Args:
+            enabled (int): 1=开，0=关
+
+        Returns:
+            None
+
+        Raises:
+            RuntimeError: 设置失败时抛出异常
+        '''
         ok, err = osis_inc_tendon(enabled)
         if not ok:
             raise RuntimeError(f"设置钢束自重影响失败: {err}")
@@ -149,30 +253,67 @@ class ControlManager:
         geom: Literal[0,1] = 0,
         link: Literal[0,1] = 0,
     ) -> None:
-        """设置非线性控制开关
+        '''设置非线性分析控制开关
 
         Args:
-            geom: 打开几何非线性（大位移大转角）
-            link: 考虑非线性连接单元
-        """
+            geom (int): 是否打开几何非线性（大位移大转角），1=开，0=关
+            link (int): 是否考虑非线性连接单元，1=考虑，0=不考虑
+
+        Returns:
+            None
+
+        Raises:
+            RuntimeError: 设置失败时抛出异常
+        '''
         ok, err = osis_nl(1 if geom else 0, 1 if link else 0)
         if not ok:
             raise RuntimeError(f"设置非线性控制失败: {err}")
 
     def set_line_search(self, enabled: Literal[0,1] = 1) -> None:
-        """设置线性搜索开关"""
+        '''设置求解阶段的线性搜索开关
+
+        Args:
+            enabled (int): 1=开，0=关
+
+        Returns:
+            None
+
+        Raises:
+            RuntimeError: 设置失败时抛出异常
+        '''
         ok, err = osis_ln_srch(enabled)
         if not ok:
             raise RuntimeError(f"设置线性搜索失败: {err}")
 
     def set_auto_time_step(self, enabled: Literal[0,1] = 1) -> None:
-        """设置是否自动计算时间荷载步"""
+        '''设置是否启用自动计算时间荷载步
+
+        Args:
+            enabled (int): 1=开，0=关
+
+        Returns:
+            None
+
+        Raises:
+            RuntimeError: 设置失败时抛出异常
+        '''
         ok, err = osis_auto_ts(enabled)
         if not ok:
             raise RuntimeError(f"设置自动时间步长失败: {err}")
 
     def set_substitution_steps(self, ls: int, sbmx: int) -> None:
-        """指定荷载步数和最大荷载子步数"""
+        '''指定荷载步数与最大荷载子步数
+
+        Args:
+            ls (int): 荷载步数
+            sbmx (int): 最大荷载子步数
+
+        Returns:
+            None
+
+        Raises:
+            RuntimeError: 设置失败时抛出异常
+        '''
         ok, err = osis_NSUBST(ls, sbmx)
         if not ok:
             raise RuntimeError(f"设置荷载步数失败: {err}")
@@ -180,7 +321,20 @@ class ControlManager:
     # ── 模态分析 ────────────────────────────────
 
     def set_modal_opt(self, num: int = 1) -> None:
-        """定义模态分析所需的特征值最大数目"""
+        '''定义模态分析所需计算的特征值最大数目
+
+        Args:
+            num (int): 需要计算的特征值最大数目，缺省值：1
+
+        Returns:
+            None
+
+        Raises:
+            RuntimeError: 设置失败时抛出异常
+
+        Examples:
+            >>> control_manager.set_modal_opt(5)  # 设置计算前 5 阶模态
+        '''
         ok, err = osis_mod_opt(num)
         if not ok:
             raise RuntimeError(f"设置模态分析参数失败: {err}")