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

bstart_trb-0.2.1/.python-version

@@ -0,0 +1 @@
+3.11

bstart_trb-0.2.1/BUILDING.md

@@ -0,0 +1,117 @@
+# Building Guide
+
+This guide explains how to build `bstart-trb` wheel packages for distribution.
+
+## Prerequisites
+
+### Windows
+
+1. **Install MSYS2** (provides gfortran):
+   - Download from https://www.msys2.org/
+   - After installation, open MSYS2 terminal and run:
+     ```bash
+     pacman -S mingw-w64-ucrt-x86_64-gcc-fortran
+     ```
+   - Add `C:\msys64\ucrt64\bin` to your system PATH
+
+2. **Install Python 3.10+**:
+   - Download from https://www.python.org/downloads/
+
+3. **Install uv** (recommended):
+   ```powershell
+   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+   ```
+
+### macOS
+
+```bash
+# Install gfortran
+brew install gfortran
+
+# Install uv
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+### Linux
+
+```bash
+# Install gfortran
+sudo apt install gfortran  # Debian/Ubuntu
+sudo yum install gcc-gfortran  # RHEL/CentOS
+
+# Install uv
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+---
+
+## Build Steps
+
+### 1. Clone the repository
+
+```bash
+git clone https://github.com/youjunxiaji/bstart-trb.git
+cd bstart-trb
+```
+
+### 2. Install dependencies with uv
+
+```bash
+uv sync
+```
+
+This automatically creates a virtual environment and installs all dependencies.
+
+### 3. Build the wheel
+
+```bash
+uv run python -m build --wheel
+```
+
+The wheel file will be created in the `dist/` directory.
+
+---
+
+## Alternative: Direct f2py Build
+
+If meson build fails, you can compile the Fortran module directly:
+
+```bash
+cd slice_wrapper
+uv run python -m numpy.f2py -c taper_slice.f90 -m _taper_slice
+```
+
+---
+
+## Publishing to PyPI
+
+### 1. Install twine
+
+```bash
+uv pip install twine
+```
+
+### 2. Create PyPI API token
+
+1. Log in to https://pypi.org
+2. Go to Account settings → API tokens → Add API token
+3. Save the token securely
+
+### 3. Upload the wheel
+
+```bash
+uv run twine upload dist/*.whl
+```
+
+When prompted:
+- Username: `__token__`
+- Password: Your API token (starts with `pypi-`)
+
+---
+
+## Notes
+
+- Each Python version (3.10, 3.11, 3.12) needs a separate wheel
+- Windows wheels have `.whl` suffix like `*-win_amd64.whl`
+- macOS wheels: `*-macosx_*_arm64.whl` (Apple Silicon) or `*-macosx_*_x86_64.whl` (Intel)
+- Linux wheels: `*-manylinux*.whl`

bstart_trb-0.2.1/PACKAGE_SUMMARY.md

@@ -0,0 +1,208 @@
+# bstart-trb PyPI 包配置总结
+
+## 完成的工作
+
+### 1. 包配置 (`pyproject.toml`)
+
+✅ **配置内容**：
+- 包名：`bstart-trb`
+- 版本：`0.1.0`
+- 描述：Cylindrical/Tapered Roller Bearing Slice Stress Calculation Module
+- Python 版本：>= 3.12
+- 许可证：MIT
+- 依赖：仅 `numpy >= 2.0.0`
+
+✅ **构建配置**：
+- 使用 `hatchling` 作为构建后端
+- 仅打包 `slice_wrapper` 目录
+- 包含预编译的二进制文件（`.pyd`）
+- 排除 Fortran 源码（`.f90`）和构建脚本（`build.py`）
+
+### 2. 文件修改
+
+✅ **新增文件**：
+- `README_PYPI.md` - PyPI 包说明文档（英文）
+- `PUBLISHING.md` - 发布指南（中文）
+- `test_install.py` - 安装测试脚本
+- `PACKAGE_SUMMARY.md` - 本文件
+
+✅ **修改文件**：
+- `pyproject.toml` - 完整的包配置
+- `.gitignore` - 允许跟踪 `.pyd` 文件
+- `slice_wrapper/__init__.py` - 版本号改为 0.1.0
+
+✅ **添加到 Git**：
+- `slice_wrapper/_taper_slice.cp312-win_amd64.pyd` - 预编译的 Fortran 模块
+
+### 3. 构建和测试
+
+✅ **构建结果**：
+```
+dist/
+├── bstart_trb-0.1.0-py3-none-any.whl    # Wheel 包
+└── bstart_trb-0.1.0.tar.gz              # 源码包
+```
+
+✅ **包内容验证**：
+- ✅ Python 源码文件
+- ✅ 预编译的 `.pyd` 文件（139 KB）
+- ✅ 类型提示文件（`.pyi`）
+- ✅ LICENSE 文件
+- ❌ Fortran 源码（已排除）
+- ❌ 构建脚本（已排除）
+
+✅ **功能测试**：
+```
+[OK] 包版本: 0.1.0
+[OK] Fortran 模块可用: True
+[OK] 收敛: True
+[OK] 错误码: 0
+[OK] 滚子变形: 0.006387 mm
+[OK] 平衡载荷: 1338.12 N
+[OK] 最大应力: 1299 MPa
+[SUCCESS] 所有测试通过!
+```
+
+## 包的特点
+
+### ✅ 优点
+
+1. **无需编译**：用户安装时不需要 Fortran 编译器
+2. **开箱即用**：pip 安装后立即可用
+3. **保密源码**：不包含 Fortran 源代码
+4. **类型安全**：完整的类型提示
+5. **体积小**：仅约 150 KB
+
+### ⚠️ 限制
+
+1. **平台限制**：当前只支持 Windows x64
+2. **Python 版本**：仅支持 Python 3.12
+3. **扩展性**：添加新平台需要重新编译
+
+## 安装和使用
+
+### 用户安装
+
+```bash
+pip install bstart-trb
+```
+
+### 快速开始
+
+```python
+from slice_wrapper import (
+    slice_stress,
+    RollerParams,
+    RacewayParams,
+    CrownType,
+    RacewayType,
+)
+
+# 定义参数
+roller = RollerParams(
+    d1=10.0, d2=10.0, length=9.6,
+    crown_type=CrownType.LOGARITHMIC,
+    curve_q=14100.0
+)
+
+raceway = RacewayParams(
+    diameter=-150.0,
+    raceway_type=RacewayType.OUTER
+)
+
+# 计算
+result = slice_stress(roller, raceway, load=1340.86, n_slice=30)
+print(f"Max stress: {result.max_stress:.0f} MPa")
+```
+
+## 发布流程
+
+### 1. 测试 PyPI（推荐）
+
+```bash
+# 上传到测试环境
+uv run twine upload --repository testpypi dist/*
+
+# 测试安装
+pip install --index-url https://test.pypi.org/simple/ \
+    --extra-index-url https://pypi.org/simple/ bstart-trb
+```
+
+### 2. 生产 PyPI
+
+```bash
+# 上传到生产环境
+uv run twine upload dist/*
+```
+
+### 3. Git 标签
+
+```bash
+git commit -m "v0.1.0  发布到 PyPI"
+git tag v0.1.0
+git push origin main --tags
+```
+
+## 后续工作
+
+### 可选优化
+
+1. **多平台支持**：
+   - 在 Linux 上编译 `.so` 文件
+   - 在 macOS 上编译 `.so` 文件
+   - 上传多个平台特定的 wheel
+
+2. **多 Python 版本**：
+   - 在 Python 3.11, 3.13 等版本下编译
+   - 上传多个版本特定的 wheel
+
+3. **CI/CD**：
+   - 设置 GitHub Actions 自动构建
+   - 自动测试和发布
+
+4. **文档**：
+   - 添加 Sphinx 文档
+   - 发布到 Read the Docs
+
+## 文件清单
+
+### 项目根目录
+```
+bstart-trb/
+├── slice_wrapper/                    # 主包目录
+│   ├── __init__.py                  # 包初始化（版本 0.1.0）
+│   ├── models.py                    # 数据模型
+│   ├── wrapper.py                   # Python 包装器
+│   ├── _taper_slice.pyi             # 类型提示
+│   ├── py.typed                     # PEP 561 标记
+│   ├── _taper_slice.cp312-win_amd64.pyd  # 预编译模块 ⭐
+│   ├── taper_slice.f90              # Fortran 源码（不打包）
+│   └── build.py                     # 构建脚本（不打包）
+├── dist/                            # 构建产物
+│   ├── bstart_trb-0.1.0-py3-none-any.whl
+│   └── bstart_trb-0.1.0.tar.gz
+├── pyproject.toml                   # 包配置 ⭐
+├── README_PYPI.md                   # PyPI 说明 ⭐
+├── PUBLISHING.md                    # 发布指南 ⭐
+├── test_install.py                  # 测试脚本 ⭐
+├── PACKAGE_SUMMARY.md               # 本文件 ⭐
+├── LICENSE                          # MIT 许可证
+├── .gitignore                       # Git 忽略（已修改）⭐
+└── uv.lock                          # 依赖锁定
+
+⭐ = 新增或重要修改的文件
+```
+
+## 参考文档
+
+- **用户文档**：`README_PYPI.md`
+- **发布指南**：`PUBLISHING.md`
+- **构建文档**：`BUILDING.md`
+- **原始说明**：`README.md`（中文技术文档）
+
+## 联系方式
+
+- 作者：Gu Lei
+- 许可证：MIT
+- Python 版本：>= 3.12
+- 平台：Windows x64

{bstart_trb-0.1.0 → bstart_trb-0.2.1}/PKG-INFO

@@ -1,26 +1,14 @@
 Metadata-Version: 2.4
 Name: bstart-trb
-Version: 0.1.0
-Summary: Cylindrical/Tapered Roller Bearing Slice Stress Calculation Module
-Project-URL: Homepage, https://github.com/yourusername/bstart-trb
-Project-URL: Repository, https://github.com/yourusername/bstart-trb
-Project-URL: Documentation, https://github.com/yourusername/bstart-trb#readme
-Author-email: Gu Lei <gulei@example.com>
-License: MIT
+Version: 0.2.1
+Summary: Add your description here
 License-File: LICENSE
-Keywords: bearing,contact,f2py,fortran,hertz,roller,stress
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Manufacturing
-Classifier: Intended Audience :: Science/Research
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: Microsoft :: Windows
-Classifier: Programming Language :: Fortran
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Topic :: Scientific/Engineering
-Classifier: Topic :: Scientific/Engineering :: Physics
-Requires-Python: >=3.12
+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
@@ -48,7 +36,7 @@ pip install bstart-trb
 ## Quick Start
 
 ```python
-from slice_wrapper import (
+from bstart_trb import (
     slice_stress,
     RollerParams,
     RacewayParams,
@@ -135,7 +123,7 @@ The method is more accurate than simplified Hertz formulas as it accounts for:
 
 ## Requirements
 
-- Python >= 3.12
+- Python >= 3.11
 - NumPy >= 2.0.0
 
 ## Platform Support

bstart_trb-0.2.1/PUBLISHING.md

@@ -0,0 +1,224 @@
+# PyPI 发布指南
+
+本文档介绍如何将 `bstart-trb` 包发布到 PyPI。
+
+## 准备工作
+
+### 1. 确保代码已更新并测试通过
+
+```bash
+# 运行测试
+uv run python test_install.py
+```
+
+### 2. 更新版本号
+
+编辑以下两个文件中的版本号：
+- `pyproject.toml` - 第 3 行的 `version`
+- `slice_wrapper/__init__.py` - 最后一行的 `__version__`
+
+版本号格式：`major.minor.patch`
+- **major**: 重大功能更新或不兼容的 API 变更
+- **minor**: 新增功能或模块（向下兼容）
+- **patch**: Bug 修复、代码优化、小改动
+
+示例：
+```
+0.1.0 -> 0.1.1  (Bug 修复)
+0.1.1 -> 0.2.0  (新增功能)
+0.2.0 -> 1.0.0  (重大更新)
+```
+
+### 3. 确保 `.pyd` 文件是最新的
+
+如果修改了 Fortran 代码，需要重新编译：
+
+```bash
+cd slice_wrapper
+uv run python build.py
+```
+
+## 构建包
+
+### 1. 清理旧的构建产物
+
+```bash
+Remove-Item -Path "dist" -Recurse -Force -ErrorAction SilentlyContinue
+```
+
+### 2. 构建 wheel 和 sdist
+
+```bash
+uv build
+```
+
+这将在 `dist/` 目录下生成两个文件：
+- `bstart_trb-{version}-py3-none-any.whl` - wheel 包（包含预编译的 .pyd）
+- `bstart_trb-{version}.tar.gz` - 源码发行版
+
+### 3. 验证构建的包
+
+检查 wheel 内容：
+```bash
+python -m zipfile -l dist\bstart_trb-{version}-py3-none-any.whl
+```
+
+确认包含以下文件：
+- ✅ `slice_wrapper/__init__.py`
+- ✅ `slice_wrapper/models.py`
+- ✅ `slice_wrapper/wrapper.py`
+- ✅ `slice_wrapper/_taper_slice.pyi`
+- ✅ `slice_wrapper/py.typed`
+- ✅ `slice_wrapper/_taper_slice.cp312-win_amd64.pyd`  ← **重要！预编译的二进制文件**
+- ❌ `taper_slice.f90` - **应该被排除**
+- ❌ `build.py` - **应该被排除**
+
+## 发布到 PyPI
+
+### 1. 注册 PyPI 账号
+
+- 生产环境：https://pypi.org/account/register/
+- 测试环境：https://test.pypi.org/account/register/
+
+### 2. 创建 API Token
+
+1. 登录 PyPI
+2. 进入账户设置 -> API tokens
+3. 创建新的 token（选择 "Entire account" 或指定项目）
+4. 保存 token（只显示一次！）
+
+### 3. 配置 twine
+
+创建 `~/.pypirc` 文件（Windows: `C:\Users\{用户名}\.pypirc`）：
+
+```ini
+[distutils]
+index-servers =
+    pypi
+    testpypi
+
+[pypi]
+username = __token__
+password = pypi-AgEIcHlwaS5vcmcC...你的token...
+
+[testpypi]
+repository = https://test.pypi.org/legacy/
+username = __token__
+password = pypi-AgENdGVzdC5weXBpLm9yZwI...你的token...
+```
+
+**注意**：将 `.pypirc` 添加到 `.gitignore`，不要提交到 Git！
+
+### 4. 上传到测试 PyPI（推荐先测试）
+
+```bash
+uv run twine upload --repository testpypi dist/*
+```
+
+测试安装：
+```bash
+pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ bstart-trb
+```
+
+### 5. 上传到生产 PyPI
+
+确认测试无误后：
+
+```bash
+uv run twine upload dist/*
+```
+
+## 发布后
+
+### 1. 测试安装
+
+```bash
+# 在新的虚拟环境中测试
+pip install bstart-trb
+```
+
+### 2. 创建 Git 标签
+
+```bash
+git add pyproject.toml slice_wrapper/__init__.py
+git commit -m "v0.1.0  发布到 PyPI"
+git tag v0.1.0
+git push origin main --tags
+```
+
+### 3. 创建 GitHub Release（可选）
+
+1. 前往 GitHub 仓库的 "Releases" 页面
+2. 点击 "Create a new release"
+3. 选择刚才创建的标签
+4. 编写 Release Notes
+5. 附加构建的 wheel 文件
+
+## 常见问题
+
+### Q: 如何支持多个 Python 版本？
+
+A: 当前包只包含 Python 3.12 的编译文件（`cp312`）。如需支持其他版本：
+1. 在不同 Python 版本下重新编译 `.pyd` 文件
+2. 将所有 `.pyd` 文件添加到 `slice_wrapper/` 目录
+3. 重新构建包
+
+### Q: 如何支持 Linux 和 macOS？
+
+A: 需要在对应平台上编译：
+1. 在 Linux 上运行 `python build.py`，生成 `.so` 文件
+2. 在 macOS 上运行 `python build.py`，生成 `.so` 文件
+3. 将所有编译文件添加到包中
+4. 重新构建并上传
+
+### Q: 上传失败：文件已存在
+
+A: PyPI 不允许覆盖已发布的版本。解决方案：
+1. 递增版本号（如 0.1.0 -> 0.1.1）
+2. 重新构建并上传
+
+### Q: 用户安装后提示找不到 Fortran 模块
+
+A: 检查：
+1. 用户的 Python 版本是否为 3.12（当前只支持 3.12）
+2. 用户的操作系统是否为 Windows x64
+3. 包是否正确包含了 `.pyd` 文件
+
+## 自动化发布（高级）
+
+可以使用 GitHub Actions 自动发布：
+
+```yaml
+# .github/workflows/publish.yml
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  deploy:
+    runs-on: windows-latest
+    steps:
+    - uses: actions/checkout@v3
+    - uses: actions/setup-python@v4
+      with:
+        python-version: '3.12'
+    - name: Install dependencies
+      run: |
+        pip install uv
+        uv pip install hatchling twine
+    - name: Build package
+      run: uv build
+    - name: Publish to PyPI
+      env:
+        TWINE_USERNAME: __token__
+        TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+      run: uv run twine upload dist/*
+```
+
+## 参考链接
+
+- [PyPI 官方文档](https://packaging.python.org/tutorials/packaging-projects/)
+- [Twine 文档](https://twine.readthedocs.io/)
+- [PEP 517 构建系统](https://peps.python.org/pep-0517/)