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

bstart_trb/wrapper.py

@@ -1,8 +1,8 @@
 """
-Python 包装层
+Python Wrapper Layer
 
-提供圆柱/圆锥滚子轴承切片应力计算的高级 Python 接口。
-封装底层 Fortran 计算核心（通过 f2py）。
+Provides high-level Python interface for cylindrical/tapered roller bearing
+slice stress calculation. Wraps the underlying Fortran computational core (via f2py).
 """
 
 from typing import Optional, Sequence, Callable, Tuple
@@ -17,7 +17,7 @@ from .models import (
     SliceResult,
 )
 
-# 尝试导入 f2py 编译的模块
+# Try to import f2py compiled module
 _FORTRAN_AVAILABLE = False
 _taper_calculate: Optional[Callable[..., Tuple[
     NDArray[np.float64], NDArray[np.float64], NDArray[np.float64], float, float, float, int
@@ -30,8 +30,8 @@ try:
 except ImportError:
     import warnings
     warnings.warn(
-        "Fortran 计算核心未编译，请运行 'python build.py' 编译模块。"
-        "当前切片计算功能不可用。"
+        "Fortran core not compiled. Please run 'python build.py' to compile. "
+        "Slice calculation functionality is currently unavailable."
     )
 
 
@@ -41,73 +41,73 @@ def slice_stress(
     load: float,
     n_slice: int = 30,
 ) -> SliceResult:
-    """计算滚子-滚道接触的切片应力分布
+    """Calculate slice stress distribution for roller-raceway contact.
     
-    使用影响系数法（Influence Coefficient Method）计算滚子与滚道
-    接触时各切片的应力分布，考虑凸度修形和滚子倾斜的影响。
+    Uses the Influence Coefficient Method to calculate stress distribution
+    across slices, considering crown modification and roller tilt effects.
     
     Args:
-        roller: 滚子几何参数
-        raceway: 滚道参数
-        load: 滚子载荷 (N)
-        n_slice: 切片数量 (1-50)，默认 30
+        roller: Roller geometry parameters
+        raceway: Raceway parameters
+        load: Roller load (N)
+        n_slice: Number of slices (1-50), default 30
     
     Returns:
-        SliceResult: 包含各切片应力、接触半宽度等计算结果
+        SliceResult: Contains stress, contact half-width, and other results for each slice
     
     Raises:
-        RuntimeError: Fortran 模块未编译时抛出
-        ValueError: 参数无效时抛出
+        RuntimeError: When Fortran module is not compiled
+        ValueError: When parameters are invalid
     
     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 roller parameters
         >>> roller = RollerParams(
         ...     d1=10.0, d2=10.0, length=9.6,
         ...     crown_type=CrownType.LOGARITHMIC,
         ...     curve_q=14100.0
         ... )
         >>> 
-        >>> # 定义外圈滚道参数（注意直径为负值）
+        >>> # Define outer ring raceway parameters (note negative diameter)
         >>> raceway = RacewayParams(
         ...     diameter=-150.0,
         ...     raceway_type=RacewayType.OUTER
         ... )
         >>> 
-        >>> # 计算切片应力
+        >>> # Calculate slice stress
         >>> result = slice_stress(roller, raceway, load=1340.0, n_slice=30)
-        >>> print(f"最大应力: {result.max_stress:.0f} MPa")
-        >>> print(f"应力均匀度: {result.stress_uniformity:.2%}")
+        >>> print(f"Max stress: {result.max_stress:.0f} MPa")
+        >>> print(f"Stress uniformity: {result.stress_uniformity:.2%}")
     
     Note:
-        - 切片数 n_slice 最大支持 50
-        - 对数凸度 (crown_type=2) 在 load == curve_q 时可实现均匀应力分布
-        - 外圈滚道的 diameter 应使用负值（Hertz 接触符号约定）
+        - Maximum n_slice is 50
+        - Logarithmic crown (crown_type=2) achieves uniform stress when load == curve_q
+        - Outer ring raceway diameter should be negative (Hertz contact sign convention)
     
     Theory:
-        该函数使用影响系数法求解滚子-滚道接触问题：
-        1. 将滚子沿轴向分成 n_slice 个切片
-        2. 建立切片间的弹性耦合关系（影响系数矩阵）
-        3. 使用高斯消元法求解线性方程组
-        4. 迭代收敛得到各切片的接触应力分布
+        This function uses the influence coefficient method to solve roller-raceway contact:
+        1. Divides roller axially into n_slice slices
+        2. Establishes elastic coupling between slices (influence coefficient matrix)
+        3. Solves linear system using Gaussian elimination
+        4. Iterates to convergence to obtain contact stress distribution
     """
     if not _FORTRAN_AVAILABLE or _taper_calculate is None:
         raise RuntimeError(
-            "Fortran 计算核心未编译。请先运行 'python build.py' 编译模块。"
+            "Fortran core not compiled. Please run 'python build.py' first."
         )
     
-    # 参数验证
+    # Parameter validation
     if load <= 0:
-        raise ValueError(f"载荷必须为正数，当前值: {load}")
+        raise ValueError(f"Load must be positive, got: {load}")
     if not 1 <= n_slice <= 50:
-        raise ValueError(f"切片数必须在 1-50 之间，当前值: {n_slice}")
+        raise ValueError(f"n_slice must be between 1-50, got: {n_slice}")
     
-    # 确定设计载荷
+    # Determine design load
     curve_q = roller.curve_q if roller.curve_q > 0 else load
     
-    # 调用 Fortran 计算（此时 _taper_calculate 已确保不为 None）
+    # Call Fortran calculation (_taper_calculate is guaranteed non-None here)
     p, a, q_slice, dc, q1, qm, ierr = _taper_calculate(
         d1=roller.d1,
         d2=roller.d2,
@@ -123,7 +123,7 @@ def slice_stress(
         curveq=curve_q,
     )
     
-    # 构建结果
+    # Build result
     return SliceResult(
         n_slice=n_slice,
         stress=np.array(p, dtype=np.float64),
@@ -143,25 +143,26 @@ def batch_slice_stress(
     loads: Sequence[float],
     n_slice: int = 30,
 ) -> list[SliceResult]:
-    """批量计算多个载荷下的切片应力分布
+    """Batch calculate slice stress distribution for multiple loads.
     
-    对多个载荷值进行切片应力计算，适用于载荷分布已知的情况。
+    Calculates slice stress for multiple load values, suitable when
+    load distribution is known.
     
     Args:
-        roller: 滚子几何参数
-        raceway: 滚道参数
-        loads: 载荷序列 (N)，支持 list[int], list[float], NDArray 等
-        n_slice: 切片数量，默认 30
+        roller: Roller geometry parameters
+        raceway: Raceway parameters
+        loads: Load sequence (N), supports list[int], list[float], NDArray, etc.
+        n_slice: Number of slices, default 30
     
     Returns:
-        list[SliceResult]: 各载荷对应的计算结果列表
+        list[SliceResult]: List of calculation results for each load
     
     Example:
-        >>> # 假设已知各滚子的载荷分布
+        >>> # Assuming known load distribution for each roller
         >>> loads = [1340.0, 1128.3, 689.2, 324.8]
         >>> results = batch_slice_stress(roller, raceway, loads)
         >>> for i, result in enumerate(results):
-        ...     print(f"载荷 {loads[i]:.1f}N: 最大应力 {result.max_stress:.0f} MPa")
+        ...     print(f"Load {loads[i]:.1f}N: Max stress {result.max_stress:.0f} MPa")
     """
     results = []
     for load in loads:
@@ -169,7 +170,7 @@ def batch_slice_stress(
             result = slice_stress(roller, raceway, load, n_slice)
             results.append(result)
         else:
-            # 无载荷，返回零结果
+            # Zero load, return zero result
             results.append(SliceResult(
                 n_slice=n_slice,
                 stress=np.zeros(n_slice),
@@ -185,9 +186,9 @@ def batch_slice_stress(
 
 
 def is_fortran_available() -> bool:
-    """检查 Fortran 计算核心是否可用
+    """Check if Fortran computational core is available.
     
     Returns:
-        bool: True 表示 Fortran 模块已编译可用
+        bool: True if Fortran module is compiled and available
     """
     return _FORTRAN_AVAILABLE

bstart_trb-0.2.2.dist-info/METADATA

@@ -0,0 +1,289 @@
+Metadata-Version: 2.4
+Name: bstart-trb
+Version: 0.2.2
+Summary: Add your description here
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: numpy>=2.0.0
+Provides-Extra: demo
+Requires-Dist: openpyxl>=3.1.5; extra == 'demo'
+Requires-Dist: pandas>=2.0.0; extra == 'demo'
+Requires-Dist: plotly>=5.0.0; extra == 'demo'
+Description-Content-Type: text/markdown
+
+# BSTART-TRB
+
+**Cylindrical/Tapered Roller Bearing Slice Stress Calculation Module**
+
+A high-performance Python package for calculating contact stress distribution in roller bearings using the slice method with Fortran computational core.
+
+## Features
+
+- 🚀 **Fast Fortran Core**: Compiled Fortran code via f2py for optimal performance
+- 📦 **Pre-compiled Binary**: No Fortran compiler required for installation
+- 🎯 **Type-Safe**: Complete type hints and IDE support
+- 🔬 **Accurate**: Uses influence coefficient method based on elastic contact theory
+- 📊 **Flexible**: Supports various crown types (linear, circular, logarithmic)
+
+## Installation
+
+```bash
+pip install bstart-trb
+```
+
+**Note**: This package includes pre-compiled binaries for Windows (x64) + Python 3.11. Support for other platforms coming soon.
+
+## Quick Start
+
+```python
+from bstart_trb import (
+    slice_stress,
+    RollerParams,
+    RacewayParams,
+    CrownType,
+    RacewayType,
+)
+
+# Define cylindrical roller parameters
+roller = RollerParams(
+    d1=10.0,              # Small end diameter (mm)
+    d2=10.0,              # Large end diameter (mm)
+    length=9.6,           # Effective length (mm)
+    alfa=0.0,             # Half cone angle (degrees)
+    tilt=0.0,             # Tilt angle (degrees)
+    crown_type=CrownType.LOGARITHMIC,
+    curve_q=14100.0,      # Design load (N)
+)
+
+# Define outer ring raceway parameters
+raceway = RacewayParams(
+    diameter=-150.0,      # Negative for concave surface (mm)
+    raceway_type=RacewayType.OUTER,
+    fai=0.0,              # Half cone angle (degrees)
+)
+
+# Calculate slice stress distribution
+result = slice_stress(roller, raceway, load=1340.86, n_slice=30)
+
+# Access scalar results
+print(f"Converged: {result.converged}")
+print(f"Max stress: {result.max_stress:.0f} MPa")
+print(f"Mean stress: {result.mean_stress:.0f} MPa")
+print(f"Contact deflection: {result.deflection:.6f} mm")
+print(f"Stress uniformity: {result.stress_uniformity:.2%}")
+print(f"Contact slices: {result.contact_slices}/{result.n_slice}")
+
+# Access array results
+print(f"Stress distribution: {result.stress}")         # MPa per slice
+print(f"Contact half-widths: {result.half_width}")     # mm per slice
+print(f"Slice forces: {result.slice_force}")           # N per slice
+
+# Get slice positions along roller length
+positions = result.get_slice_positions(roller.length)  # mm
+print(f"Slice positions: {positions}")
+```
+
+## Return Value: `SliceResult`
+
+The `slice_stress()` function returns a `SliceResult` object containing:
+
+### Array Attributes
+
+| Attribute | Type | Unit | Description |
+|-----------|------|------|-------------|
+| `stress` | `NDArray[float64]` | MPa | Contact stress at each slice center |
+| `half_width` | `NDArray[float64]` | mm | Contact half-width at each slice |
+| `slice_force` | `NDArray[float64]` | N | Contact force at each slice |
+
+### Scalar Attributes
+
+| Attribute | Type | Unit | Description |
+|-----------|------|------|-------------|
+| `n_slice` | `int` | - | Number of slices |
+| `deflection` | `float` | mm | Roller deformation |
+| `equilibrium_load` | `float` | N | Equilibrium load (should match input) |
+| `equilibrium_moment` | `float` | N·mm | Equilibrium moment |
+| `converged` | `bool` | - | Whether the iteration converged |
+| `error_code` | `int` | - | 0=success, 1=solve failed, 2=invalid n_slice, 3=invalid load |
+
+### Computed Properties
+
+| Property | Type | Unit | Description |
+|----------|------|------|-------------|
+| `max_stress` | `float` | MPa | Maximum contact stress |
+| `min_stress` | `float` | MPa | Minimum contact stress (non-zero) |
+| `mean_stress` | `float` | MPa | Mean contact stress (contact zone only) |
+| `contact_slices` | `int` | - | Number of slices in contact (stress > 0) |
+| `stress_uniformity` | `float` | 0~1 | Stress uniformity (1 = perfectly uniform) |
+
+### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `get_slice_positions(roller_length)` | `NDArray[float64]` | Center position of each slice (mm) |
+| `get_slice_width(roller_length)` | `float` | Width of each slice (mm) |
+| `get_slice_spacing(roller_length)` | `float` | Spacing between slice centers (mm) |
+
+## Other Functions
+
+### `batch_slice_stress()`
+
+Calculate stress for multiple loads at once:
+
+```python
+from bstart_trb import batch_slice_stress
+
+loads = [1340.0, 1128.3, 689.2, 324.8]
+results = batch_slice_stress(roller, raceway, loads, n_slice=30)
+
+for i, result in enumerate(results):
+    print(f"Load {loads[i]:.1f}N: Max stress {result.max_stress:.0f} MPa")
+```
+
+### `is_fortran_available()`
+
+Check if Fortran core is available:
+
+```python
+from bstart_trb import is_fortran_available
+
+if is_fortran_available():
+    print("Fortran core ready")
+else:
+    print("Fortran core not compiled")
+```
+
+## Enum Types
+
+### `CrownType` - Crown Modification Types
+
+| Value | Name | Description |
+|-------|------|-------------|
+| 0 | `STRAIGHT` | No crown modification - high edge stress |
+| 1 | `ARC` | Circular crown - requires arc radius |
+| 2 | `LOGARITHMIC` | Logarithmic crown (recommended) - optimal stress distribution |
+
+### `RacewayType` - Raceway Types
+
+| Value | Name | Description |
+|-------|------|-------------|
+| 0 | `PLANE` | Flat surface contact |
+| 1 | `INNER` | Inner ring raceway (convex surface) |
+| 2 | `OUTER` | Outer ring raceway (concave surface) - use negative diameter |
+
+## Key Parameters Explained
+
+### Roller Parameters
+
+| Parameter | Unit | Description |
+|-----------|------|-------------|
+| `d1` | mm | Roller small end diameter (equal to d2 for cylindrical) |
+| `d2` | mm | Roller large end diameter |
+| `length` | mm | Effective roller length |
+| `alfa` | deg | Roller half cone angle (0 for cylindrical) |
+| `tilt` | deg | Roller tilt angle (see below) |
+| `crown_type` | - | Crown modification type (see enum) |
+| `curve_q` | N | Design load for crown optimization (see below) |
+
+### Raceway Parameters
+
+| Parameter | Unit | Description |
+|-----------|------|-------------|
+| `diameter` | mm | Raceway diameter (**negative for outer ring**) |
+| `raceway_type` | - | Inner/Outer raceway type |
+| `fai` | deg | Raceway half cone angle |
+
+### Calculation Parameters
+
+| Parameter | Unit | Description |
+|-----------|------|-------------|
+| `load` | N | Applied load on roller |
+| `n_slice` | - | Number of slices (default 30, max 50) |
+
+### Understanding `curve_q` (Design Load)
+
+The `curve_q` parameter determines the logarithmic crown profile. It affects stress distribution:
+
+| Condition | Stress Distribution |
+|-----------|---------------------|
+| `load == curve_q` | **Uniform** - optimal crown compensation |
+| `load < curve_q` | Center high, edge low - edge may lose contact |
+| `load > curve_q` | Edge high, center low - edge stress concentration |
+
+**Tip**: Set `curve_q` to your most common operating load.
+
+### Understanding `tilt` (Tilt Angle)
+
+Roller tilt causes asymmetric stress distribution:
+
+```
+tilt = 0 (normal):          tilt > 0 (tilted):
+┌──────────────────┐        ┌──────────────────┐
+│  uniform stress  │        │ high │    low    │
+└──────────────────┘        └──────────────────┘
+```
+
+Sources of tilt: shaft deflection, mounting errors, housing deformation.
+
+### Why Outer Ring Uses Negative Diameter?
+
+Hertz contact theory sign convention:
+- **Positive curvature** → Convex surface (roller, inner ring)
+- **Negative curvature** → Concave surface (outer ring)
+
+Example: Outer ring with 150mm diameter → `diameter = -150.0`
+
+## What is Slice Calculation?
+
+The slice method divides the roller-raceway contact into multiple slices along the roller length to accurately calculate stress distribution. This is essential for:
+
+- Capturing edge stress concentration effects
+- Analyzing the impact of crown modifications
+- Predicting bearing life more accurately
+- Understanding load distribution along roller length
+
+## Theory
+
+This package implements the **influence coefficient method** based on elastic half-space contact theory:
+
+1. Discretizes roller into slices
+2. Calculates elastic coupling between slices (influence coefficient matrix)
+3. Solves linear system using Gaussian elimination
+4. Iterates to convergence for contact area and load balance
+
+The method is more accurate than simplified Hertz formulas as it accounts for:
+- Elastic coupling between slices
+- Dynamic contact area determination
+- Edge loading effects
+- Crown modification influence
+
+## Requirements
+
+- Python >= 3.11
+- NumPy >= 2.0.0
+
+## Platform Support
+
+| Platform | Status |
+|----------|--------|
+| Windows (x64) | ✅ Supported |
+| Linux | 🚧 Coming soon |
+| macOS | 🚧 Coming soon |
+
+## License
+
+MIT License - See LICENSE file for details.
+
+## Author
+
+Gu Lei
+
+## References
+
+- Harris, T.A., Kotzalas, M.N. - *Rolling Bearing Analysis*, 5th Edition
+- Johnson, K.L. - *Contact Mechanics*
+- ISO/TS 16281:2008 - Rolling bearings calculation methods
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit issues or pull requests.

bstart_trb-0.2.2.dist-info/RECORD

@@ -0,0 +1,11 @@
+bstart_trb/__init__.py,sha256=32QmnLdTE53qkVgDvDZBH2Z1v3I-4qG8JlcVlQDcbU4,1560
+bstart_trb/_taper_slice.pyi,sha256=X5xMWlbdGl46RQmunOaFbh9BFjeqTMP0Hp7b_waJuaA,4896
+bstart_trb/libtaper_sl.J4R3HUMRYTOGZPKAVTEOISVEHZMIJTJT.gfortran-win_amd64.dll,sha256=9fWV89mKt1_6Q8f_votoG1vlvxsy4qgDVWXQAZ0vmUA,108562
+bstart_trb/models.py,sha256=tRpkcJE50I9jL3y03EgITJ1iMv57gRFkr1tl6OeXDWw,11503
+bstart_trb/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+bstart_trb/wrapper.py,sha256=CadOcW31MVZ8WsTwG5Ksp_ZAacf_D96XJJ4gqYb70MM,6565
+bstart_trb/_taper_slice.cp311-win_amd64.pyd,sha256=WDAXF_NTj7DRIEA6--kX1W3TMPGQD5u8JVRt-hR_9L4,64000
+bstart_trb-0.2.2.dist-info/METADATA,sha256=jRClXe7c3JBUEWgsMsYT9vkUTWjldlM5aLma2y1ZogQ,9502
+bstart_trb-0.2.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+bstart_trb-0.2.2.dist-info/licenses/LICENSE,sha256=YCXLtJfjUPyklZ7pN5gxOeMOr5QCAvip4Sdnl_xcCu8,1084
+bstart_trb-0.2.2.dist-info/RECORD,,