Eytelwein

Open-source belt conveyor calculation library for Python

Eytelwein provides production-grade engineering calculations for belt conveyor systems — from steady-state resistance and drive layout to idler roll loading and horizontal curve forces. All public functions use Pint Quantity objects for full dimensional safety: units in, units out, no silent conversion errors.

Active Development Notice

This repository is under active development. APIs, behaviors, and available functionality may change between releases while features are expanded and refined.

Highlights

• Dimensionally safe — every input and output carries explicit physical units
• Dual-layer architecture — bare-math _module.py (fast, unit-free) + public module.py (Quantity-wrapped, validated)
• Comprehensive test suite — 1 455 tests covering core and extended calculations
• Typed — py.typed marker, compatible with mypy strict mode

Module Overview

Installation

With uv (recommended):

uv pip install eytelwein

With pip:

pip install eytelwein

Development installation from source:

# Clone the repository
git clone https://github.com/mdVoith/eytelwein.git
cd eytelwein

# Create the project environment
uv sync

Documentation

Hosted documentation (GitHub Pages):

• https://mdvoith.github.io/eytelwein/

Build docs locally from repository root:

uv run sphinx-apidoc -o docs/source src/eytelwein --force --separate
uv run sphinx-build -b html docs/source docs/_build/html

Generated HTML entry page:

• docs/_build/html/index.html

Quick Start

from eytelwein.main.units import get_unit_registry
u = get_unit_registry()

from eytelwein.belt_conveyor_design import usable_belt_width

# Calculate usable belt width for a 1200 mm belt
b = usable_belt_width(belt_width=1200 * u.mm)
print(b)  # 1050.0 millimeter

Real-World Example Script

For a more practical, end-to-end workflow, run the example script in examples/real_world_cross_section_flow.py.

It demonstrates a compact sizing pipeline with hard-coded values:

• usable belt width from belt geometry
• cross-section of fill from trough geometry
• volume flow from cross-section and belt speed
• mass flow from volume flow and bulk density
• inverse cross-check for required usable width

python examples/real_world_cross_section_flow.py

Feature Examples

Dedicated, runnable scripts are available under examples/features/.

• a_output_unit_minimum_tension.py Demonstrates changing output units for the same calculation (minimum belt tension in N and kN).
• b_imperial_input_dual_output.py Uses imperial inputs and calls the same function twice to produce imperial output and SI output.
• c_unit_errors_are_caught.py Shows dimensional unit mismatch handling (expected ValueError).
• d_physically_invalid_inputs_are_caught.py Shows physically invalid input handling (expected ValueError).
• e_output_precision_control.py Shows how to control rounding with precision (default, custom, and unrounded output).
• f_round_trip_consistency.py Shows forward/inverse round-trip checks and validates numerical consistency within explicit tolerances.
• g_constants_and_enums.py Shows using public enums (IdlerSets) and shared constants in practical calculations.

Run each from repository root:

python examples/features/a_output_unit_minimum_tension.py
python examples/features/b_imperial_input_dual_output.py
python examples/features/c_unit_errors_are_caught.py
python examples/features/d_physically_invalid_inputs_are_caught.py
python examples/features/e_output_precision_control.py
python examples/features/f_round_trip_consistency.py
python examples/features/g_constants_and_enums.py

Advanced Example (Private API, Not Recommended)

Advanced example scripts live under examples/advanced/ and are intentionally separate from the standard feature examples.

Use this path only if you explicitly accept the tradeoffs:

• advanced
• unstable API surface
• no unit safety
• no backwards-compatibility promise

h_private_functions_not_recommended.py compares public and private calls with the same intended inputs, shows that private angle inputs must be radians, and demonstrates that private helpers can skip public-layer validation.

Run from repository root:

python examples/advanced/h_private_functions_not_recommended.py

Architecture

src/eytelwein/
├── belt_conveyor_design/
│   ├── core/           # Fundamental steady-state calculations
│   │   ├── _module.py  # Pure math (float in / float out)
│   │   └── module.py   # Quantity-wrapped public API
│   ├── extended/       # Additional / derived calculations
│   ├── data/           # Lookup tables (CSV)
│   └── constants.py    # Enums & domain constants
├── idler_design/
│   └── core/           # Idler roll load factors
├── horizontal_curves/
│   └── core/           # Lateral force components
└── main/
    ├── units.py        # UnitRegistry singleton
    └── constants.py    # Physical constants (via scipy)

Mathematical Background

The calculations implement established belt conveyor engineering methodologies covering:

• Resistance and power — main, secondary, and gradient resistances for steady-state operation
• Belt tensions — minimum tensions from sag constraints, tension distribution across belt width
• Drive system layout — torque, power, and speed relationships for single and multi-drive configurations
• Volume and mass flow — cross-sectional fill geometry, reduction factors for inclined conveyors
• Minimum pulley diameters — based on belt tension member type and load classification
• Idler roll loading — load distribution factors for various trough configurations
• Horizontal curves — centripetal, gravity, and tilted-idler restraining forces (conventional and improved methods)

Development

# Clone and install
git clone https://github.com/mdVoith/eytelwein.git
cd eytelwein
uv sync

# Run checks
uv run pytest               # 1455 tests
uv run ruff check src/ tests/
uv run mypy src/
uv run sphinx-apidoc -o docs/source src/eytelwein --force --separate
uv run sphinx-build -b html docs/source docs/_build/html

Contributing

See CONTRIBUTING.md for development guidelines.

Please note: because the project is actively evolving, contribution targets and public interfaces can change over time.

License

Apache-2.0 — see LICENSE and NOTICE.

Copyright (c) Voith Group.