eytelwein 0.1.0

Belt conveyor calculation library

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.

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

Module	Description
eytelwein.belt_conveyor_design.core	Volume/mass flow, belt tensions, drive layout, belt design, tension distribution, minimum pulley diameters, resistance & power
eytelwein.belt_conveyor_design.extended	Extended methods — mass inertia, design of conveyor belt, additional drive layout functions
eytelwein.idler_design	Idler roll load factor calculations
eytelwein.horizontal_curves	Lateral force analysis for horizontally curved belt conveyors
eytelwein.main	Shared utilities — unit registry singleton, physical constants

Installation

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

# Create the project environment
uv sync

PyPI packages and wheels are not published yet. Use a local clone (or download the repository as a ZIP) and run commands from the project root.

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.

License

Apache-2.0 — see LICENSE and NOTICE.

Copyright (c) Voith Group.