bstart-trb 0.2.2
Add your description here
Requires Python: >=3.11

# 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.