bstart-trb 0.2.1__tar.gz → 0.2.2__tar.gz

bstart_trb-0.2.2/LOGS.md

@@ -0,0 +1,135 @@
+# 开发日志
+
+## 2026-02-05 - v0.2.1 发布到 PyPI
+
+### 问题解决
+
+#### 1. Fortran 模块编译问题
+
+**问题描述：**
+运行 `main.py` 时报错 `RuntimeError: Fortran 计算核心未编译`
+
+**解决步骤：**
+
+1. 检查系统 gfortran 编译器 - 已安装 v16.0.0
+2. 运行 `python slice_wrapper/build.py` 编译 Fortran 模块
+3. 发现 DLL 加载失败：`.pyd` 文件无法找到依赖的 DLL
+4. 将 `.libs/` 目录中的 DLL 复制到 `.pyd` 同级目录
+5. 发现 NumPy 版本不兼容：系统 Python 使用 NumPy 1.x 编译，但 uv 环境使用 NumPy 2.x
+6. 使用 `uv run python slice_wrapper/build.py` 在正确的环境中重新编译
+7. 编译成功，模块可用
+
+**关键点：**
+- `.pyd` 文件是 Python 版本特定的（如 `cp311` = Python 3.11.x）
+- 需要在目标 Python 环境中编译才能正确链接 NumPy
+- Windows 上的 DLL 需要与 `.pyd` 文件放在同一目录
+
+#### 2. 包名重构
+
+**需求：** 将导入方式从 `from slice_wrapper import ...` 改为 `from bstart_trb import ...`
+
+**操作：**
+1. 重命名 `slice_wrapper/` → `bstart_trb/`
+2. 更新 `main.py` 中的导入语句
+3. 更新 `pyproject.toml` 的包配置
+
+#### 3. PyPI 打包配置
+
+**需求：** 
+- 包含 `.pyd` 和 `.dll` 文件
+- 排除 `.f90` 源文件和 `build.py`
+
+**pyproject.toml 配置：**
+
+```toml
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["bstart_trb"]
+artifacts = [
+    "*.pyd",
+    "*.dll",
+]
+exclude = [
+    "*.f90",
+    "build.py",
+    "_taper_slice/**",
+    "__pycache__/**",
+]
+
+[tool.hatch.build.targets.wheel.force-include]
+"bstart_trb/_taper_slice.cp311-win_amd64.pyd" = "bstart_trb/_taper_slice.cp311-win_amd64.pyd"
+```
+
+**关键点：**
+- `artifacts` 配置告诉 hatch 包含通常被忽略的二进制文件
+- `force-include` 确保 `.pyd` 文件一定被包含
+- 删除 `_taper_slice/` 子目录，避免重复的 DLL 文件
+
+#### 4. 依赖精简
+
+**问题：** 原配置包含了 `pandas`, `openpyxl`, `plotly` 等不必要的依赖
+
+**解决：**
+
+```toml
+dependencies = [
+    "numpy>=2.0.0",
+]
+
+[project.optional-dependencies]
+demo = [
+    "openpyxl>=3.1.5",
+    "pandas>=2.0.0",
+    "plotly>=5.0.0",
+]
+```
+
+用户如需 demo 依赖可以安装：`pip install bstart-trb[demo]`
+
+### 版本发布历史
+
+| 版本 | 日期 | 说明 |
+|------|------|------|
+| 0.2.1 | 2026-02-05 | 修复 README，精简依赖 |
+| 0.2.0 | 2026-02-05 | 首次成功发布，包名改为 bstart_trb |
+
+### 构建命令参考
+
+```bash
+# 编译 Fortran 模块
+uv run python bstart_trb/build.py
+
+# 复制 DLL 到包目录（如果需要）
+Copy-Item "bstart_trb\_taper_slice\.libs\*.dll" -Destination "bstart_trb\" -Force
+
+# 构建包
+uv build
+
+# 检查 wheel 内容
+python -m zipfile -l dist\bstart_trb-*.whl
+
+# 上传到 PyPI
+uv run twine upload dist/*
+```
+
+### 测试验证
+
+```bash
+# 在新目录创建测试环境
+mkdir test_env && cd test_env
+uv init --name test-pkg
+uv add bstart-trb==0.2.1 --refresh
+
+# 测试导入
+uv run python -c "from bstart_trb import slice_stress, is_fortran_available; print(is_fortran_available())"
+```
+
+### 注意事项
+
+1. **Python 版本兼容性**：当前仅支持 Python 3.11（`cp311`）
+2. **平台支持**：当前仅支持 Windows x64
+3. **编译依赖**：编译需要 gfortran 和 MSVC
+4. **版本覆盖**：PyPI 不允许覆盖已发布版本，需递增版本号

bstart_trb-0.2.2/PKG-INFO

@@ -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/README_PYPI.md

@@ -0,0 +1,276 @@
+# 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.