完善MECMAS21参数配置与分组交互

app/simulation/components/amesim/mechanical/translational.py

@@ -4,13 +4,31 @@ from collections.abc import Mapping
 from math import expm1
 
 from app.simulation.core.base import AlgebraicComponent, DynamicComponent
-from app.simulation.core.catalog import ComponentDisplaySpec, PortDisplaySpec
+from app.simulation.core.catalog import (
+    ComponentDisplaySpec,
+    ParameterGroupDisplaySpec,
+    PortDisplaySpec,
+)
 from app.simulation.core.equations import EquationResidual
-from app.simulation.core.metadata import ParameterDefinition, ResultVariableDefinition
+from app.simulation.core.metadata import (
+    ParameterCondition,
+    ParameterDefinition,
+    ParameterOption,
+    ResultVariableDefinition,
+)
 from app.simulation.core.medium import IdealGasMedium
 from app.simulation.core.ports import PortDefinition
 
 
+_MECMAS21_FRICTION_ENABLED = ParameterCondition("useFriction", (2.0,))
+_MECMAS21_NON_RESTITUTION = ParameterCondition("stoptype", (1.0, 2.0, 4.0))
+_MECMAS21_LIMITS_ENABLED = ParameterCondition("stoptype", (1.0, 2.0, 3.0))
+_MECMAS21_ELASTIC_STOP = ParameterCondition("stoptype", (2.0,))
+_MECMAS21_RESTITUTION_STOP = ParameterCondition("stoptype", (3.0,))
+_MECMAS21_ADVANCED_FRICTION = ParameterCondition("frictionType", (2.0,))
+_MECMAS21_STRIBECK_ENABLED = ParameterCondition("strib", (2.0,))
+
+
 class AmesimF000(AlgebraicComponent):
     """AMESim F000 zero force source."""
 
@@ -133,37 +151,328 @@ class AmesimMecmas21(DynamicComponent):
     """AMESim MECMAS21 first public one-dimensional translational mass."""
 
     MODEL_TYPE = "amesim_mecmas21"
-    MODEL_VERSION = "0.1.0"
+    MODEL_VERSION = "0.2.0"
     PORTS = (
         PortDefinition.mechanical_translational("port_1"),
         PortDefinition.mechanical_translational("port_2"),
     )
     PARAMETERS = (
-        ParameterDefinition("mass", 1.0, label="质量", quantity="mass", unit="kg", minimum=0.0, minimum_exclusive=True),
-        ParameterDefinition("fstick", 0.0, label="静摩擦力", quantity="force", unit="N", minimum=0.0),
-        ParameterDefinition("fcoul", 0.0, label="库仑摩擦力", quantity="force", unit="N", minimum=0.0),
-        ParameterDefinition("rvisc", 0.0, label="黏性摩擦系数", quantity="translational_damping", unit="N/(m/s)", minimum=0.0),
-        ParameterDefinition("wind", 0.0, label="风阻系数", quantity="windage", unit="N/(m/s)^2", minimum=0.0),
-        ParameterDefinition("dvel", 1.0e-6, label="粘滞速度阈值", quantity="velocity", unit="m/s", minimum=0.0),
-        ParameterDefinition("restdvel", 1.0e-6, label="恢复速度阈值", quantity="velocity", unit="m/s", minimum=0.0),
-        ParameterDefinition("restcoeff", 0.65, label="恢复系数", quantity="dimensionless", unit="", minimum=0.0, maximum=1.0),
-        ParameterDefinition("astrib", 1.0e-3, label="Stribeck 常数", quantity="velocity", unit="m/s", minimum=0.0),
-        ParameterDefinition("xmin", -1.0, label="下位移限位", quantity="length", unit="m"),
-        ParameterDefinition("Kbmin", 1.0e9, label="下限位刚度", quantity="translational_stiffness", unit="N/m", minimum=0.0),
-        ParameterDefinition("Dbmin", 1.0e4, label="下限位阻尼", quantity="translational_damping", unit="N/(m/s)", minimum=0.0),
-        ParameterDefinition("Pdmin", 1.0e-4, label="下限位满阻尼穿透", quantity="length", unit="m", minimum=0.0),
-        ParameterDefinition("xmax", 0.8, label="上位移限位", quantity="length", unit="m"),
-        ParameterDefinition("Kbmax", 1.0e9, label="上限位刚度", quantity="translational_stiffness", unit="N/m", minimum=0.0),
-        ParameterDefinition("Dbmax", 1.0e4, label="上限位阻尼", quantity="translational_damping", unit="N/(m/s)", minimum=0.0),
-        ParameterDefinition("Pdmax", 1.0e-4, label="上限位满阻尼穿透", quantity="length", unit="m", minimum=0.0),
-        ParameterDefinition("theta", 0.0, label="倾角", quantity="dimensionless", unit=""),
-        ParameterDefinition("useFriction", 1.0, label="启用摩擦", quantity="dimensionless", unit="", minimum=0.0, maximum=1.0),
-        ParameterDefinition("stoptype", 4.0, label="限位类型", quantity="dimensionless", unit="", minimum=0.0),
-        ParameterDefinition("discContactOption", 1.0, label="接触选项", quantity="dimensionless", unit="", minimum=0.0),
-        ParameterDefinition("strib", 1.0, label="Stribeck 选项", quantity="dimensionless", unit="", minimum=0.0, maximum=1.0),
-        ParameterDefinition("frictionType", 1.0, label="摩擦类型", quantity="dimensionless", unit="", minimum=0.0),
-        ParameterDefinition("v0", 0.0, label="初始速度", quantity="velocity", unit="m/s"),
-        ParameterDefinition("x0", 0.0, label="初始位移", quantity="length", unit="m"),
+        ParameterDefinition(
+            "mass",
+            1.0,
+            label="质量",
+            quantity="mass",
+            unit="kg",
+            minimum=0.0,
+            minimum_exclusive=True,
+            description="平动质量，必须大于零。",
+        ),
+        ParameterDefinition(
+            "fstick",
+            0.0,
+            label="静摩擦力",
+            quantity="force",
+            unit="N",
+            minimum=0.0,
+            description=(
+                "AMESim 静摩擦阈值。当前公开求解器尚未实现静摩擦保持与脱离逻辑，"
+                "因此该参数暂不参与力计算。"
+            ),
+            visible_when=(
+                _MECMAS21_NON_RESTITUTION,
+                _MECMAS21_FRICTION_ENABLED,
+            ),
+        ),
+        ParameterDefinition(
+            "fcoul",
+            0.0,
+            label="库仑摩擦力",
+            quantity="force",
+            unit="N",
+            minimum=0.0,
+            description="滑动时的库仑摩擦力绝对值，方向与速度相反。",
+            visible_when=(
+                _MECMAS21_NON_RESTITUTION,
+                _MECMAS21_FRICTION_ENABLED,
+            ),
+        ),
+        ParameterDefinition(
+            "rvisc",
+            0.0,
+            label="黏性摩擦系数",
+            quantity="translational_damping",
+            unit="N/(m/s)",
+            minimum=0.0,
+            description="与速度成正比的黏性摩擦系数。",
+            visible_when=(_MECMAS21_FRICTION_ENABLED,),
+        ),
+        ParameterDefinition(
+            "wind",
+            0.0,
+            label="风阻系数",
+            quantity="windage",
+            unit="N/(m/s)^2",
+            minimum=0.0,
+            description="与速度平方成正比、方向与速度相反的风阻系数。",
+            visible_when=(_MECMAS21_FRICTION_ENABLED,),
+        ),
+        ParameterDefinition(
+            "dvel",
+            1.0e-6,
+            label="粘滞速度阈值",
+            quantity="velocity",
+            unit="m/s",
+            minimum=0.0,
+            description=(
+                "高级摩擦模型的低速切换阈值；当前公开求解器尚未实现对应的"
+                "高级静摩擦公式。"
+            ),
+            visible_when=(
+                _MECMAS21_NON_RESTITUTION,
+                _MECMAS21_FRICTION_ENABLED,
+                _MECMAS21_ADVANCED_FRICTION,
+            ),
+        ),
+        ParameterDefinition(
+            "restdvel",
+            1.0e-6,
+            label="恢复速度阈值",
+            quantity="velocity",
+            unit="m/s",
+            minimum=0.0,
+            description="恢复碰撞低于该入射速度时按无回弹处理。",
+            visible_when=(_MECMAS21_RESTITUTION_STOP,),
+        ),
+        ParameterDefinition(
+            "restcoeff",
+            0.65,
+            label="恢复系数",
+            quantity="dimensionless",
+            unit="",
+            minimum=0.0,
+            maximum=1.0,
+            description="恢复碰撞后的速度与碰撞前速度绝对值之比。",
+            visible_when=(_MECMAS21_RESTITUTION_STOP,),
+        ),
+        ParameterDefinition(
+            "astrib",
+            1.0e-3,
+            label="Stribeck 常数",
+            quantity="velocity",
+            unit="m/s",
+            minimum=0.0,
+            description=(
+                "高级 Stribeck 摩擦模型的速度常数；当前公开求解器尚未实现"
+                "对应的 Stribeck 公式。"
+            ),
+            visible_when=(
+                _MECMAS21_NON_RESTITUTION,
+                _MECMAS21_FRICTION_ENABLED,
+                _MECMAS21_ADVANCED_FRICTION,
+                _MECMAS21_STRIBECK_ENABLED,
+            ),
+        ),
+        ParameterDefinition(
+            "xmin",
+            -1.0,
+            label="下位移限位",
+            quantity="length",
+            unit="m",
+            description="理想、弹性或恢复碰撞限位的下边界位置。",
+            visible_when=(_MECMAS21_LIMITS_ENABLED,),
+        ),
+        ParameterDefinition(
+            "Kbmin",
+            1.0e9,
+            label="下限位刚度",
+            quantity="translational_stiffness",
+            unit="N/m",
+            minimum=0.0,
+            description="弹性下限位的接触刚度。",
+            visible_when=(_MECMAS21_ELASTIC_STOP,),
+        ),
+        ParameterDefinition(
+            "Dbmin",
+            1.0e4,
+            label="下限位阻尼",
+            quantity="translational_damping",
+            unit="N/(m/s)",
+            minimum=0.0,
+            description="弹性下限位的最大接触阻尼。",
+            visible_when=(_MECMAS21_ELASTIC_STOP,),
+        ),
+        ParameterDefinition(
+            "Pdmin",
+            1.0e-4,
+            label="下限位满阻尼穿透",
+            quantity="length",
+            unit="m",
+            minimum=0.0,
+            description="弹性下限位阻尼由零增至全值所需的穿透量。",
+            visible_when=(_MECMAS21_ELASTIC_STOP,),
+        ),
+        ParameterDefinition(
+            "xmax",
+            0.8,
+            label="上位移限位",
+            quantity="length",
+            unit="m",
+            description="理想、弹性或恢复碰撞限位的上边界位置。",
+            visible_when=(_MECMAS21_LIMITS_ENABLED,),
+        ),
+        ParameterDefinition(
+            "Kbmax",
+            1.0e9,
+            label="上限位刚度",
+            quantity="translational_stiffness",
+            unit="N/m",
+            minimum=0.0,
+            description="弹性上限位的接触刚度。",
+            visible_when=(_MECMAS21_ELASTIC_STOP,),
+        ),
+        ParameterDefinition(
+            "Dbmax",
+            1.0e4,
+            label="上限位阻尼",
+            quantity="translational_damping",
+            unit="N/(m/s)",
+            minimum=0.0,
+            description="弹性上限位的最大接触阻尼。",
+            visible_when=(_MECMAS21_ELASTIC_STOP,),
+        ),
+        ParameterDefinition(
+            "Pdmax",
+            1.0e-4,
+            label="上限位满阻尼穿透",
+            quantity="length",
+            unit="m",
+            minimum=0.0,
+            description="弹性上限位阻尼由零增至全值所需的穿透量。",
+            visible_when=(_MECMAS21_ELASTIC_STOP,),
+        ),
+        ParameterDefinition(
+            "theta",
+            0.0,
+            label="倾角（度）",
+            quantity="dimensionless",
+            unit="",
+            description=(
+                "源 AMESim 参数以度为单位：+90° 表示端口 1 位于最低端，"
+                "-90° 表示端口 1 位于最高端。当前一维公开求解器尚未加入"
+                "由该倾角产生的重力分量。"
+            ),
+        ),
+        ParameterDefinition(
+            "useFriction",
+            1.0,
+            label="启用摩擦",
+            quantity="dimensionless",
+            unit="",
+            editor="choice",
+            options=(
+                ParameterOption(1.0, "否"),
+                ParameterOption(2.0, "是"),
+            ),
+            description=(
+                "AMESim 原始编码：1 表示不启用摩擦，2 表示启用摩擦。"
+                "当前公开模型在启用时实现黏性摩擦、风阻和基础库仑摩擦；"
+                "高级静摩擦与 Stribeck 公式尚未实现。"
+            ),
+        ),
+        ParameterDefinition(
+            "stoptype",
+            4.0,
+            label="限位类型",
+            quantity="dimensionless",
+            unit="",
+            editor="choice",
+            options=(
+                ParameterOption(1.0, "理想限位"),
+                ParameterOption(2.0, "弹性限位"),
+                ParameterOption(3.0, "恢复碰撞"),
+                ParameterOption(4.0, "无限位"),
+            ),
+            description=(
+                "AMESim 原始编码：1 为理想限位，2 为弹性限位，"
+                "3 为带恢复系数的碰撞限位，4 为无限位。"
+            ),
+        ),
+        ParameterDefinition(
+            "discContactOption",
+            1.0,
+            label="允许负接触力",
+            quantity="dimensionless",
+            unit="",
+            editor="choice",
+            options=(
+                ParameterOption(1.0, "允许负接触力"),
+                ParameterOption(2.0, "不允许负接触力"),
+            ),
+            description=(
+                "仅在弹性限位中生效。AMESim 原始编码：1 保留阻尼项可能产生的"
+                "负接触力，2 将接触力限制为非负。"
+            ),
+            visible_when=(_MECMAS21_ELASTIC_STOP,),
+        ),
+        ParameterDefinition(
+            "strib",
+            1.0,
+            label="Stribeck 效应",
+            quantity="dimensionless",
+            unit="",
+            editor="choice",
+            options=(
+                ParameterOption(1.0, "否"),
+                ParameterOption(2.0, "是"),
+            ),
+            description=(
+                "AMESim 原始编码：1 表示不使用 Stribeck 效应，2 表示使用。"
+                "该选项目前用于保留模型配置和控制参数显示；"
+                "高级 Stribeck 摩擦公式尚未实现。"
+            ),
+            visible_when=(
+                _MECMAS21_NON_RESTITUTION,
+                _MECMAS21_FRICTION_ENABLED,
+                _MECMAS21_ADVANCED_FRICTION,
+            ),
+        ),
+        ParameterDefinition(
+            "frictionType",
+            1.0,
+            label="摩擦类型",
+            quantity="dimensionless",
+            unit="",
+            editor="choice",
+            options=(
+                ParameterOption(1.0, "简单"),
+                ParameterOption(2.0, "高级"),
+            ),
+            description=(
+                "AMESim 原始编码：1 为简单摩擦，2 为高级摩擦。"
+                "当前公开模型只实现黏性摩擦、风阻和基础库仑摩擦，"
+                "高级静摩擦与 Stribeck 行为尚未实现。"
+            ),
+            visible_when=(
+                _MECMAS21_NON_RESTITUTION,
+                _MECMAS21_FRICTION_ENABLED,
+            ),
+        ),
+        ParameterDefinition(
+            "v0",
+            0.0,
+            label="初始速度",
+            quantity="velocity",
+            unit="m/s",
+            description="仿真开始时质量的平动速度。",
+        ),
+        ParameterDefinition(
+            "x0",
+            0.0,
+            label="初始位移",
+            quantity="length",
+            unit="m",
+            description="仿真开始时质量的平动位置。",
+        ),
     )
     RESULT_VARIABLES = (
         ResultVariableDefinition("a", "加速度", "acceleration", "m/s2", "state", 10),
@@ -184,6 +493,41 @@ class AmesimMecmas21(DynamicComponent):
             PortDisplaySpec("port_1", "right", order=20),
         ),
         order=30,
+        parameter_groups=(
+            ParameterGroupDisplaySpec(
+                id="friction",
+                label="摩擦",
+                parameters=(
+                    "frictionType",
+                    "strib",
+                    "astrib",
+                    "fstick",
+                    "fcoul",
+                    "rvisc",
+                    "wind",
+                    "dvel",
+                ),
+                order=10,
+            ),
+            ParameterGroupDisplaySpec(
+                id="endstops",
+                label="限位",
+                parameters=(
+                    "discContactOption",
+                    "xmax",
+                    "Kbmax",
+                    "Dbmax",
+                    "Pdmax",
+                    "xmin",
+                    "Kbmin",
+                    "Dbmin",
+                    "Pdmin",
+                    "restcoeff",
+                    "restdvel",
+                ),
+                order=20,
+            ),
+        ),
     )
     state_size = 2
 
@@ -193,7 +537,7 @@ class AmesimMecmas21(DynamicComponent):
         self.set_parameter_values(resolved)
         for name, value in resolved.items():
             setattr(self, name, float(value))
-        self.use_friction = bool(int(self.useFriction))
+        self.use_friction = int(self.useFriction) == 2
         self.port_1 = self.register_declared_port("port_1")
         self.port_2 = self.register_declared_port("port_2")
         self.v = float(self.v0)
@@ -210,9 +554,14 @@ class AmesimMecmas21(DynamicComponent):
         medium: IdealGasMedium,
         parameters: Mapping[str, float],
     ) -> "AmesimMecmas21":
+        definitions = {definition.name: definition for definition in cls.PARAMETERS}
         for integer_name in ("useFriction", "stoptype", "discContactOption", "strib", "frictionType"):
-            if not float(parameters[integer_name]).is_integer():
+            value = float(parameters[integer_name])
+            if not value.is_integer():
                 raise ValueError(f"MECMAS21 {integer_name} must be an integer.")
+            message = definitions[integer_name].validation_message(value)
+            if message is not None:
+                raise ValueError(f"MECMAS21 {integer_name} {message}.")
         return cls(name=name, medium=medium, **dict(parameters))
 
     def get_state_vector(self) -> list[float]: