bstart-trb 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

bstart_trb/__init__.py

@@ -11,8 +11,8 @@ Features:
 - Dataclass wrapped results
 
 Example:
-    >>> from slice_wrapper import slice_stress, RollerParams, RacewayParams
-    >>> from slice_wrapper import CrownType, RacewayType
+    >>> from bstart_trb import slice_stress, RollerParams, RacewayParams
+    >>> from bstart_trb import CrownType, RacewayType
     >>> 
     >>> # Define cylindrical roller parameters
     >>> roller = RollerParams(
@@ -47,17 +47,17 @@ from .wrapper import (
 )
 
 __all__ = [
-    # 枚举类型
+    # Enum types
     "CrownType",
     "RacewayType",
-    # 数据类型
+    # Data types
     "RollerParams",
     "RacewayParams",
     "SliceResult",
-    # 计算函数
+    # Calculation functions
     "slice_stress",
     "batch_slice_stress",
     "is_fortran_available",
 ]
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"

bstart_trb/models.py

@@ -1,8 +1,9 @@
 """
-数据类型定义
+Data Type Definitions
 
-定义圆柱/圆锥滚子轴承切片计算所需的输入参数和输出结果的数据类。
-所有类都使用 dataclass 装饰器，支持完整的类型提示。
+Defines input parameter and output result data classes for
+cylindrical/tapered roller bearing slice calculation.
+All classes use the dataclass decorator with complete type hints.
 """
 
 from dataclasses import dataclass
@@ -13,62 +14,63 @@ from numpy.typing import NDArray
 
 
 class CrownType(IntEnum):
-    """凸度类型枚举
+    """Crown modification type enumeration.
     
-    用于指定滚子的凸度修形类型。
+    Specifies the crown modification type for the roller.
     
     Attributes:
-        STRAIGHT: 直线（无修形）
-        ARC: 圆弧凸度
-        LOGARITHMIC: 对数凸度（推荐，可实现最优应力分布）
+        STRAIGHT: No modification (straight profile)
+        ARC: Circular arc crown
+        LOGARITHMIC: Logarithmic crown (recommended for optimal stress distribution)
     """
     STRAIGHT = 0
-    """直线（无修形），边缘应力高"""
+    """No modification (straight profile), high edge stress"""
     
     ARC = 1
-    """圆弧凸度，需要指定圆弧半径"""
+    """Circular arc crown, requires arc radius specification"""
     
     LOGARITHMIC = 2
-    """对数凸度（推荐），理论上可实现均匀应力分布"""
+    """Logarithmic crown (recommended), theoretically achieves uniform stress distribution"""
 
 
 class RacewayType(IntEnum):
-    """滚道类型枚举
+    """Raceway type enumeration.
     
-    用于指定接触的滚道类型。
+    Specifies the type of raceway in contact.
     
     Attributes:
-        PLANE: 平面接触
-        INNER: 内圈滚道（凸面）
-        OUTER: 外圈滚道（凹面）
+        PLANE: Flat surface contact
+        INNER: Inner ring raceway (convex surface)
+        OUTER: Outer ring raceway (concave surface)
     """
     PLANE = 0
-    """平面接触"""
+    """Flat surface contact"""
     
     INNER = 1
-    """内圈滚道（凸面）"""
+    """Inner ring raceway (convex surface)"""
     
     OUTER = 2
-    """外圈滚道（凹面），注意 diameter 使用负值"""
+    """Outer ring raceway (concave surface), note: use negative diameter value"""
 
 
 @dataclass
 class RollerParams:
-    """滚子几何参数
+    """Roller geometry parameters.
     
-    定义圆柱/圆锥滚子的几何尺寸和修形参数。
+    Defines geometric dimensions and crown modification parameters
+    for cylindrical/tapered rollers.
     
     Attributes:
-        d1: 滚子小端直径 (mm)
-        d2: 滚子大端直径 (mm)，圆柱滚子 d1=d2
-        length: 滚子有效长度 (mm)
-        alfa: 滚子半圆锥角 (度)，圆柱滚子 alfa=0
-        tilt: 滚子倾斜角度 (度)，0 表示无倾斜
-        crown_type: 凸度类型，见 CrownType 枚举
-        curve_q: 设计载荷 (N)，用于计算对数凸度修形量
+        d1: Roller small end diameter (mm)
+        d2: Roller large end diameter (mm), d1=d2 for cylindrical rollers
+        length: Roller effective length (mm)
+        alfa: Roller half cone angle (degrees), alfa=0 for cylindrical rollers
+        tilt: Roller tilt angle (degrees), 0 means no tilt
+        crown_type: Crown modification type, see CrownType enum
+        curve_q: Design load (N), used for logarithmic crown calculation
     
     Example:
-        >>> # 圆柱滚子
+        >>> # Cylindrical roller
         >>> roller = RollerParams(
         ...     d1=10.0, d2=10.0, length=9.6,
         ...     alfa=0.0, tilt=0.0,
@@ -76,7 +78,7 @@ class RollerParams:
         ...     curve_q=14100.0
         ... )
         
-        >>> # 圆锥滚子
+        >>> # Tapered roller
         >>> taper_roller = RollerParams(
         ...     d1=8.0, d2=10.0, length=12.0,
         ...     alfa=10.0, tilt=0.0,
@@ -85,79 +87,79 @@ class RollerParams:
         ... )
     
     Note:
-        - 对数凸度修形在 load == curve_q 时可实现均匀应力分布
-        - tilt > 0 会导致一端应力集中，另一端可能脱离接触
+        - Logarithmic crown achieves uniform stress distribution when load == curve_q
+        - tilt > 0 causes stress concentration at one end, other end may lose contact
     """
     d1: float
-    """滚子小端直径 (mm)"""
+    """Roller small end diameter (mm)"""
     
     d2: float
-    """滚子大端直径 (mm)，圆柱滚子 d1=d2"""
+    """Roller large end diameter (mm), d1=d2 for cylindrical rollers"""
     
     length: float
-    """滚子有效长度 (mm)"""
+    """Roller effective length (mm)"""
     
     alfa: float = 0.0
-    """滚子半圆锥角 (度)，圆柱滚子 alfa=0"""
+    """Roller half cone angle (degrees), alfa=0 for cylindrical rollers"""
     
     tilt: float = 0.0
-    """滚子倾斜角度 (度)"""
+    """Roller tilt angle (degrees)"""
     
     crown_type: CrownType = CrownType.LOGARITHMIC
-    """凸度类型"""
+    """Crown modification type"""
     
     curve_q: float = 0.0
-    """设计载荷 (N)，用于对数凸度计算，0 表示使用实际载荷"""
+    """Design load (N), used for logarithmic crown calculation, 0 means use actual load"""
     
     def __post_init__(self):
-        """参数验证"""
+        """Parameter validation"""
         if self.d1 <= 0:
-            raise ValueError(f"滚子小端直径必须为正数，当前值: {self.d1}")
+            raise ValueError(f"Roller small end diameter must be positive, got: {self.d1}")
         if self.d2 <= 0:
-            raise ValueError(f"滚子大端直径必须为正数，当前值: {self.d2}")
+            raise ValueError(f"Roller large end diameter must be positive, got: {self.d2}")
         if self.length <= 0:
-            raise ValueError(f"滚子有效长度必须为正数，当前值: {self.length}")
+            raise ValueError(f"Roller effective length must be positive, got: {self.length}")
         if self.d1 > self.d2:
             import warnings
-            warnings.warn(f"滚子小端直径 d1={self.d1} 大于大端直径 d2={self.d2}，请确认")
+            warnings.warn(f"Roller small end diameter d1={self.d1} is greater than large end diameter d2={self.d2}, please verify")
         
-        # 转换枚举类型
+        # Convert enum type
         if isinstance(self.crown_type, int):
             self.crown_type = CrownType(self.crown_type)
     
     @property
     def is_cylindrical(self) -> bool:
-        """是否为圆柱滚子"""
+        """Whether this is a cylindrical roller"""
         return abs(self.d1 - self.d2) < 1e-6 and abs(self.alfa) < 1e-6
     
     @property
     def diameter(self) -> float:
-        """滚子直径（圆柱滚子）或平均直径（圆锥滚子）"""
+        """Roller diameter (cylindrical) or mean diameter (tapered)"""
         return (self.d1 + self.d2) / 2.0
 
 
 @dataclass
 class RacewayParams:
-    """滚道参数
+    """Raceway parameters.
     
-    定义滚道的几何特征。
+    Defines raceway geometric characteristics.
     
     Attributes:
-        diameter: 滚道直径 (mm)
-            - 内圈滚道：正值
-            - 外圈滚道：负值（Hertz 接触理论符号约定）
-        raceway_type: 滚道类型，见 RacewayType 枚举
-        fai: 滚道半圆锥角 (度)，圆柱滚子轴承为 0
+        diameter: Raceway diameter (mm)
+            - Inner ring raceway: positive value
+            - Outer ring raceway: negative value (Hertz contact theory sign convention)
+        raceway_type: Raceway type, see RacewayType enum
+        fai: Raceway half cone angle (degrees), 0 for cylindrical roller bearings
     
     Example:
-        >>> # 内圈滚道
+        >>> # Inner ring raceway
         >>> inner = RacewayParams(
         ...     diameter=110.0,
         ...     raceway_type=RacewayType.INNER,
         ...     fai=0.0
         ... )
         
-        >>> # 外圈滚道（注意负号）
+        >>> # Outer ring raceway (note negative sign)
         >>> outer = RacewayParams(
         ...     diameter=-150.0,
         ...     raceway_type=RacewayType.OUTER,
@@ -165,111 +167,111 @@ class RacewayParams:
         ... )
     
     Note:
-        外圈滚道 diameter 使用负值是 Hertz 接触理论的符号约定：
-        - 正曲率半径 → 凸面（滚子、内圈）
-        - 负曲率半径 → 凹面（外圈）
+        Outer ring raceway diameter uses negative value per Hertz contact theory convention:
+        - Positive radius of curvature → convex surface (roller, inner ring)
+        - Negative radius of curvature → concave surface (outer ring)
     """
     diameter: float
-    """滚道直径 (mm)，外圈使用负值"""
+    """Raceway diameter (mm), use negative value for outer ring"""
     
     raceway_type: RacewayType = RacewayType.INNER
-    """滚道类型"""
+    """Raceway type"""
     
     fai: float = 0.0
-    """滚道半圆锥角 (度)"""
+    """Raceway half cone angle (degrees)"""
     
     def __post_init__(self):
-        """参数验证"""
-        # 转换枚举类型
+        """Parameter validation"""
+        # Convert enum type
         if isinstance(self.raceway_type, int):
             self.raceway_type = RacewayType(self.raceway_type)
         
-        # 检查符号约定
+        # Check sign convention
         if self.raceway_type == RacewayType.OUTER and self.diameter > 0:
             import warnings
             warnings.warn(
-                f"外圈滚道 diameter 通常使用负值（当前值: {self.diameter}），"
-                "请确认是否正确"
+                f"Outer ring raceway diameter is typically negative (current value: {self.diameter}), "
+                "please verify if this is correct"
             )
 
 
 @dataclass
 class SliceResult:
-    """切片计算结果
+    """Slice calculation result.
     
-    包含滚子-滚道接触的切片应力分布计算结果。
+    Contains results of roller-raceway contact slice stress distribution calculation.
     
     Attributes:
-        n_slice: 切片数量
-        stress: 各切片接触中心应力 (MPa)
-        half_width: 各切片接触半宽度 (mm)
-        slice_force: 各切片接触力 (N)
-        deflection: 滚子变形量 (mm)
-        equilibrium_load: 平衡载荷 (N)
-        equilibrium_moment: 平衡力矩 (N·mm)
-        converged: 是否收敛
-        error_code: 错误码 (0=成功)
+        n_slice: Number of slices
+        stress: Contact center stress for each slice (MPa)
+        half_width: Contact half-width for each slice (mm)
+        slice_force: Contact force for each slice (N)
+        deflection: Roller deformation (mm)
+        equilibrium_load: Equilibrium load (N)
+        equilibrium_moment: Equilibrium moment (N·mm)
+        converged: Whether calculation converged
+        error_code: Error code (0=success)
     
     Example:
         >>> result = slice_stress(roller, raceway, load=1340.0, n_slice=30)
-        >>> print(f"最大应力: {result.max_stress:.0f} MPa")
-        >>> print(f"应力分布: {result.stress}")
-        >>> print(f"各切片力: {result.slice_force}")
+        >>> print(f"Max stress: {result.max_stress:.0f} MPa")
+        >>> print(f"Stress distribution: {result.stress}")
+        >>> print(f"Slice forces: {result.slice_force}")
     """
     n_slice: int
-    """切片数量"""
+    """Number of slices"""
     
     stress: NDArray[np.float64]
-    """各切片接触中心应力 (MPa)"""
+    """Contact center stress for each slice (MPa)"""
     
     half_width: NDArray[np.float64]
-    """各切片接触半宽度 (mm)"""
+    """Contact half-width for each slice (mm)"""
     
     slice_force: NDArray[np.float64]
-    """各切片接触力 (N)"""
+    """Contact force for each slice (N)"""
     
     deflection: float
-    """滚子变形量 (mm)"""
+    """Roller deformation (mm)"""
     
     equilibrium_load: float
-    """平衡载荷 (N)，应接近输入载荷"""
+    """Equilibrium load (N), should be close to input load"""
     
     equilibrium_moment: float
-    """平衡力矩 (N·mm)"""
+    """Equilibrium moment (N·mm)"""
     
     converged: bool = True
-    """是否收敛"""
+    """Whether calculation converged"""
     
     error_code: int = 0
-    """错误码: 0=成功, 1=方程求解失败, 2=切片数无效, 3=载荷无效"""
+    """Error code: 0=success, 1=equation solve failed, 2=invalid n_slice, 3=invalid load"""
     
     @property
     def max_stress(self) -> float:
-        """最大接触应力 (MPa)"""
+        """Maximum contact stress (MPa)"""
         return float(np.max(self.stress)) if len(self.stress) > 0 else 0.0
     
     @property
     def min_stress(self) -> float:
-        """最小接触应力 (MPa)，不包括 0（非接触区）"""
+        """Minimum contact stress (MPa), excluding 0 (non-contact zones)"""
         nonzero = self.stress[self.stress > 0]
         return float(np.min(nonzero)) if len(nonzero) > 0 else 0.0
     
     @property
     def mean_stress(self) -> float:
-        """平均接触应力 (MPa)，仅计算接触区"""
+        """Mean contact stress (MPa), calculated for contact zone only"""
         nonzero = self.stress[self.stress > 0]
         return float(np.mean(nonzero)) if len(nonzero) > 0 else 0.0
     
     @property
     def contact_slices(self) -> int:
-        """接触切片数量（应力 > 0）"""
+        """Number of slices in contact (stress > 0)"""
         return int(np.sum(self.stress > 0))
     
     @property
     def stress_uniformity(self) -> float:
-        """应力均匀度 (0~1)，1 表示完全均匀
+        """Stress uniformity (0~1), 1 means perfectly uniform.
         
-        定义为: 1 - (最大应力 - 最小应力) / 平均应力
+        Defined as: 1 - (max_stress - min_stress) / mean_stress
         """
         if self.mean_stress == 0:
             return 0.0
@@ -277,54 +279,54 @@ class SliceResult:
         return max(0.0, 1.0 - variation)
     
     def get_slice_positions(self, roller_length: float) -> NDArray[np.float64]:
-        """获取各切片的中心位置
+        """Get center position of each slice.
         
         Args:
-            roller_length: 滚子有效长度 (mm)
+            roller_length: Roller effective length (mm)
         
         Returns:
-            各切片中心位置，从 0 到 roller_length
+            Center position of each slice, from 0 to roller_length
         """
-        h = roller_length / self.n_slice / 2  # 半切片宽度
+        h = roller_length / self.n_slice / 2  # Half slice width
         positions = np.array([h * (2 * i + 1) for i in range(self.n_slice)])
         return positions
     
     def get_slice_width(self, roller_length: float) -> float:
-        """获取切片宽度
+        """Get slice width.
         
         Args:
-            roller_length: 滚子有效长度 (mm)
+            roller_length: Roller effective length (mm)
         
         Returns:
-            单个切片的宽度 (mm)
+            Width of a single slice (mm)
         """
         return roller_length / self.n_slice
     
     def get_slice_spacing(self, roller_length: float) -> float:
-        """获取相邻切片中心之间的间距
+        """Get spacing between adjacent slice centers.
         
-        注意：切片间距 = 切片宽度 = roller_length / n_slice
+        Note: Slice spacing = slice width = roller_length / n_slice
         
         Args:
-            roller_length: 滚子有效长度 (mm)
+            roller_length: Roller effective length (mm)
         
         Returns:
-            相邻切片中心之间的间距 (mm)
+            Spacing between adjacent slice centers (mm)
         """
         return roller_length / self.n_slice
     
     def print_slice_info(self, roller_length: float) -> None:
-        """打印切片划分信息
+        """Print slice division information.
         
         Args:
-            roller_length: 滚子有效长度 (mm)
+            roller_length: Roller effective length (mm)
         """
         width = self.get_slice_width(roller_length)
         positions = self.get_slice_positions(roller_length)
-        print(f"切片划分信息:")
-        print(f"  滚子有效长度: {roller_length} mm")
-        print(f"  切片数量: {self.n_slice}")
-        print(f"  切片宽度: {width:.6f} mm")
-        print(f"  切片宽度 × 切片数 = {width * self.n_slice:.6f} mm")
-        print(f"  第一片中心位置: {positions[0]:.6f} mm")
-        print(f"  最后片中心位置: {positions[-1]:.6f} mm")
+        print(f"Slice division info:")
+        print(f"  Roller effective length: {roller_length} mm")
+        print(f"  Number of slices: {self.n_slice}")
+        print(f"  Slice width: {width:.6f} mm")
+        print(f"  Slice width × n_slice = {width * self.n_slice:.6f} mm")
+        print(f"  First slice center position: {positions[0]:.6f} mm")
+        print(f"  Last slice center position: {positions[-1]:.6f} mm")