eytelwein.belt_conveyor_design.core.belt_tensions_and_takeup_forces module

Public API for belt tensions and takeup forces calculations.

This module provides the Quantity-based public interface for calculations in the belt-tensions-and-takeup-forces domain. Each public function wraps the corresponding private helper with unit conversion, validation, and output formatting.

class eytelwein.belt_conveyor_design.core.belt_tensions_and_takeup_forces.EffortForceAndRopeTravel(effort_force: Quantity, rope_travel: Quantity)

Bases: object

Coupled result of effort-side force and rope travel transformations.

This result type pairs effort-side force and rope travel to prevent design errors where one transform is applied but the other is forgotten.

effort_force

Effort-side force quantity (usually in kilonewton).

Type:

Quantity

rope_travel

Rope-side travel distance (usually in meter).

Type:

Quantity

effort_force: Quantity

rope_travel: Quantity

class eytelwein.belt_conveyor_design.core.belt_tensions_and_takeup_forces.LoadForceAndTravel(load_force: Quantity, takeup_travel: Quantity)

Bases: object

Coupled result of load-side force and takeup travel transformations.

This result type pairs load-side force and takeup travel to prevent design errors where one transform is applied but the other is forgotten.

load_force

Load-side force quantity (usually in kilonewton).

Type:

Quantity

takeup_travel

Takeup-side travel distance (usually in meter).

Type:

Quantity

load_force: Quantity

takeup_travel: Quantity

eytelwein.belt_conveyor_design.core.belt_tensions_and_takeup_forces.effort_force_and_rope_travel_from_load_force_and_takeup_travel(load_force: Quantity, takeup_travel: Quantity, strand_count: int = 1, force_unit: str = 'kilonewton', travel_unit: str = 'meter', precision: int | None = None) → EffortForceAndRopeTravel

Calculate coupled effort-side force and rope travel from load-side force and takeup travel.

This coupled transform operates on force (not weight) with explicit effort/load terminology. It prevents field errors by returning both the force and travel transformations together. In ideal reeving, applying only one without the other violates energy conservation.

Parameters:

• load_force (Quantity) – Load-side force in newtons or equivalent force units.

• takeup_travel (Quantity) – Takeup-side travel distance in meters or equivalent length units.

• strand_count (int, optional) – Number of strands in ideal reeving system (default: 1). Must be a positive integer >= 1.

• force_unit (str, optional) – Output unit for effort force result (default: “kilonewton”). Must be a force unit.

• travel_unit (str, optional) – Output unit for rope travel result (default: “meter”). Must be a length unit.

• precision (int or None, optional) – Decimal places to round the results to (default: None). If None, no rounding is applied.

Returns:

Frozen dataclass with effort_force and rope_travel Quantity fields.

Return type:

EffortForceAndRopeTravel

Raises:

ValueError – If unit conversion fails, physical constraints are violated, or strand_count is not a positive integer.

Examples

>>> from pint import Quantity
>>> from eytelwein.main.units import get_unit_registry
>>> u = get_unit_registry()
>>> result = effort_force_and_rope_travel_from_load_force_and_takeup_travel(
...     load_force=Quantity(29419.95, u.newton),
...     takeup_travel=Quantity(1.5, u.meter),
...     strand_count=2,
... )
>>> result.effort_force
14.709975... kilonewton
>>> result.rope_travel
3.0 meter

eytelwein.belt_conveyor_design.core.belt_tensions_and_takeup_forces.effort_force_from_load_force(load_force: Quantity, strand_count: int = 1, unit: str = 'kilonewton', precision: int | None = None) → Quantity

Calculate effort force from load force using ideal reeving.

This function converts a load force to an effort force using the ideal reeving relationship where effort = load / strand_count. All inputs must be strict Quantity objects with explicit units.

Parameters:

• load_force (Quantity) – Load force in newtons or equivalent force units.

• strand_count (int, optional) – Number of strands in ideal reeving system (default: 1). Must be a positive integer >= 1. This is a plain integer configuration parameter, not a Quantity.

• unit (str, optional) – Output unit for effort force result (default: “kilonewton”). Common values: “newton”, “kilonewton”. Must be a force unit.

• precision (int or None, optional) – Decimal places to round the result to (default: None). If None, no rounding is applied.

Returns:

Effort force in the specified output unit.

Return type:

Quantity

Raises:

• ValueError – If unit conversion fails due to incompatible input units.

• ValueError – If load_force is negative.

• ValueError – If unit is invalid or incompatible with force.

• ValueError – If strand_count is not a positive integer.

Examples

>>> from pint import Quantity
>>> from eytelwein.main.units import get_unit_registry
>>> u = get_unit_registry()
>>> result = effort_force_from_load_force(
...     load_force=Quantity(2000.0, u.newton), strand_count=2
... )
>>> result
1.0 kilonewton

eytelwein.belt_conveyor_design.core.belt_tensions_and_takeup_forces.load_force_and_takeup_travel_from_effort_force_and_rope_travel(effort_force: Quantity, rope_travel: Quantity, strand_count: int = 1, force_unit: str = 'kilonewton', travel_unit: str = 'meter', precision: int | None = None) → LoadForceAndTravel

Calculate coupled load-side force and takeup travel from effort-side force and rope travel (inverse).

This coupled inverse transform operates on force (not weight) with explicit effort/load terminology. It prevents field errors by returning both the force and travel transformations together. In ideal reeving, applying only one without the other violates energy conservation.

Parameters:

• effort_force (Quantity) – Effort-side force in newtons or equivalent force units.

• rope_travel (Quantity) – Rope-side travel distance in meters or equivalent length units.

• strand_count (int, optional) – Number of strands in ideal reeving system (default: 1). Must be a positive integer >= 1.

• force_unit (str, optional) – Output unit for load force result (default: “kilonewton”). Must be a force unit.

• travel_unit (str, optional) – Output unit for takeup travel result (default: “meter”). Must be a length unit.

• precision (int or None, optional) – Decimal places to round the results to (default: None). If None, no rounding is applied.

Returns:

Frozen dataclass with load_force and takeup_travel Quantity fields.

Return type:

LoadForceAndTravel

Raises:

ValueError – If unit conversion fails, physical constraints are violated, or strand_count is not a positive integer.

Examples

>>> from pint import Quantity
>>> from eytelwein.main.units import get_unit_registry
>>> u = get_unit_registry()
>>> result = load_force_and_takeup_travel_from_effort_force_and_rope_travel(
...     effort_force=Quantity(14709.975, u.newton),
...     rope_travel=Quantity(3.0, u.meter),
...     strand_count=2,
...     force_unit="newton",
... )
>>> result.load_force
29419.95 newton
>>> result.takeup_travel
1.5 meter

eytelwein.belt_conveyor_design.core.belt_tensions_and_takeup_forces.load_force_from_effort_force(effort_force: Quantity, strand_count: int = 1, unit: str = 'kilonewton', precision: int | None = None) → Quantity

Calculate load force from effort force using ideal reeving.

This function converts an effort force to a load force using the ideal reeving relationship where load = effort * strand_count. All inputs must be strict Quantity objects with explicit units.

Parameters:

• effort_force (Quantity) – Effort force in newtons or equivalent force units.

• strand_count (int, optional) – Number of strands in ideal reeving system (default: 1). Must be a positive integer >= 1. This is a plain integer configuration parameter, not a Quantity.

• unit (str, optional) – Output unit for load force result (default: “kilonewton”). Common values: “newton”, “kilonewton”. Must be a force unit.

• precision (int or None, optional) – Decimal places to round the result to (default: None). If None, no rounding is applied.

Returns:

Load force in the specified output unit.

Return type:

Quantity

Raises:

• ValueError – If unit conversion fails due to incompatible input units.

• ValueError – If effort_force is negative.

• ValueError – If unit is invalid or incompatible with force.

• ValueError – If strand_count is not a positive integer.

Examples

>>> from pint import Quantity
>>> from eytelwein.main.units import get_unit_registry
>>> u = get_unit_registry()
>>> result = load_force_from_effort_force(
...     effort_force=Quantity(1000.0, u.newton), strand_count=2
... )
>>> result
2.0 kilonewton

eytelwein.belt_conveyor_design.core.belt_tensions_and_takeup_forces.minimum_belt_tension_from_sag_carry(line_load_belt: Quantity, line_load_material: Quantity, idler_spacing: Quantity, allowable_sag: Quantity, unit: str = 'kilonewton', precision: int | None = None) → Quantity

Calculate minimum belt tension from sag during carry run.

This function applies the relationship between belt tension, belt and material line loads, idler spacing, and allowable sag. All inputs must be strict Quantity objects with explicit units.

Parameters:

• line_load_belt (Quantity) – Belt line load (mass per unit length) in kg/m or equivalent units.

• line_load_material (Quantity) – Material line load (mass per unit length) in kg/m or equivalent units.

• idler_spacing (Quantity) – Distance between consecutive idlers (e.g., 1.5 meter).

• allowable_sag (Quantity) – Allowable sag as a dimensionless fraction of idler spacing (e.g., 0.01 for 1%). Must be a Quantity with dimensionless units.

• unit (str, optional) – Output unit for tension result (default: “kilonewton”). Common values: “newton”, “kilonewton”. Must be a force unit.

• precision (int or None, optional) – Decimal places to round the result to (default: None). If None, no rounding is applied.

Returns:

Minimum belt tension in the specified output unit.

Return type:

Quantity

Raises:

• ValueError – If unit conversion fails due to incompatible input units.

• ValueError – If line_load_belt is negative.

• ValueError – If line_load_material is negative.

• ValueError – If idler_spacing is negative.

• ValueError – If allowable_sag is not positive or invalid.

Examples

>>> from pint import Quantity
>>> from eytelwein.main.units import get_unit_registry
>>> u = get_unit_registry()
>>> result = minimum_belt_tension_from_sag_carry(
...     line_load_belt=Quantity(5.0, u.kilogram / u.meter),
...     line_load_material=Quantity(10.0, u.kilogram / u.meter),
...     idler_spacing=Quantity(1.5, u.meter),
...     allowable_sag=Quantity(0.01, u.dimensionless),
... )
>>> result
2.75812... kilonewton

eytelwein.belt_conveyor_design.core.belt_tensions_and_takeup_forces.rope_travel_from_takeup_travel(takeup_travel: Quantity, strand_count: int = 1, unit: str = 'meter', precision: int | None = None) → Quantity

Calculate rope travel from takeup travel in an ideal reeving system.

This function converts a takeup travel distance to a rope travel distance using the ideal reeving relationship. For ideal reeving, the rope travels a distance equal to the takeup travel multiplied by the strand count. All inputs must be strict Quantity objects with explicit units.

Parameters:

• takeup_travel (Quantity) – Takeup travel distance in meters or equivalent length units.

• strand_count (int, optional) – Number of strands in ideal reeving system (default: 1). Must be a positive integer >= 1. This is a plain integer configuration parameter, not a Quantity.

• unit (str, optional) – Output unit for travel result (default: “meter”). Common values: “meter”, “millimeter”. Must be a length unit.

• precision (int or None, optional) – Decimal places to round the result to (default: None). If None, no rounding is applied.

Returns:

Rope travel distance in the specified output unit.

Return type:

Quantity

Raises:

• ValueError – If unit conversion fails due to incompatible input units.

• ValueError – If takeup_travel is negative.

• ValueError – If unit is invalid or incompatible with length.

• ValueError – If strand_count is not a positive integer.

Notes

Why strand_count is plain int, not Quantity: Discrete configuration counts like strand_count represent the logical structure of a reeving system (2-part, 4-part, etc.), not measured values. They are always plain integers, while measured travel distances and dimensionless computed ratios use Quantity objects.

Field-error prevention: The coupled force/travel transforms help prevent a common design error: if a load calculation divides force by strand_count for mechanical advantage while forgetting the reciprocal travel penalty (multiplying by strand_count), the system appears to gain energy. Using coupled APIs ensures both transforms are applied correctly.

Examples

>>> from pint import Quantity
>>> from eytelwein.main.units import get_unit_registry
>>> u = get_unit_registry()
>>> result = rope_travel_from_takeup_travel(
...     takeup_travel=Quantity(1.5, u.meter), strand_count=2
... )
>>> result
3.0 meter

eytelwein.belt_conveyor_design.core.belt_tensions_and_takeup_forces.takeup_travel_from_rope_travel(rope_travel: Quantity, strand_count: int = 1, unit: str = 'meter', precision: int | None = None) → Quantity

Calculate takeup travel from rope travel in an ideal reeving system (inverse).

This function converts a rope travel distance to a takeup travel distance using the inverse ideal reeving relationship. For ideal reeving, the takeup travel is the rope travel divided by the strand count. All inputs must be strict Quantity objects with explicit units.

Parameters:

• rope_travel (Quantity) – Rope travel distance in meters or equivalent length units.

• strand_count (int, optional) – Number of strands in ideal reeving system (default: 1). Must be a positive integer >= 1. This is a plain integer configuration parameter, not a Quantity.

• unit (str, optional) – Output unit for travel result (default: “meter”). Common values: “meter”, “millimeter”. Must be a length unit.

• precision (int or None, optional) – Decimal places to round the result to (default: None). If None, no rounding is applied.

Returns:

Takeup travel distance in the specified output unit.

Return type:

Quantity

Raises:

• ValueError – If unit conversion fails due to incompatible input units.

• ValueError – If rope_travel is negative.

• ValueError – If unit is invalid or incompatible with length.

• ValueError – If strand_count is not a positive integer.

Notes

Why strand_count is plain int, not Quantity: Discrete configuration counts like strand_count represent the logical structure of a reeving system (2-part, 4-part, etc.), not measured values. They are always plain integers, while measured travel distances and dimensionless computed ratios use Quantity objects.

Field-error prevention: The coupled force/travel transforms help prevent a common design error: if a load calculation divides force by strand_count for mechanical advantage while forgetting the reciprocal travel penalty (multiplying by strand_count), the system appears to gain energy. Using coupled APIs ensures both transforms are applied correctly.

Examples

>>> from pint import Quantity
>>> from eytelwein.main.units import get_unit_registry
>>> u = get_unit_registry()
>>> result = takeup_travel_from_rope_travel(
...     rope_travel=Quantity(3.0, u.meter), strand_count=2
... )
>>> result
1.5 meter

eytelwein.belt_conveyor_design.core.belt_tensions_and_takeup_forces.takeup_weight_force_from_takeup_weight(takeup_weight: Quantity, unit: str = 'kilonewton', precision: int | None = None) → Quantity

Calculate takeup weight force from takeup weight.

This function converts a mass-based takeup weight to a force quantity using the standard gravitational acceleration constant. All inputs must be strict Quantity objects with explicit units.

Parameters:

• takeup_weight (Quantity) – Takeup weight in kg or equivalent mass units.

• unit (str, optional) – Output unit for force result (default: “kilonewton”). Common values: “newton”, “kilonewton”. Must be a force unit.

• precision (int or None, optional) – Decimal places to round the result to (default: None). If None, no rounding is applied.

Returns:

Takeup weight force in the specified output unit.

Return type:

Quantity

Raises:

• ValueError – If unit conversion fails due to incompatible input units.

• ValueError – If takeup_weight is negative.

• ValueError – If unit is invalid or incompatible with force.

Examples

>>> from pint import Quantity
>>> from eytelwein.main.units import get_unit_registry
>>> u = get_unit_registry()
>>> result = takeup_weight_force_from_takeup_weight(
...     takeup_weight=Quantity(3000.0, u.kilogram)
... )
>>> result
29.41995... kilonewton

eytelwein.belt_conveyor_design.core.belt_tensions_and_takeup_forces.takeup_weight_from_takeup_weight_force(takeup_weight_force: Quantity, unit: str = 'kilogram', precision: int | None = None) → Quantity

Calculate takeup weight from takeup weight force.

This function converts a force-based takeup weight force to a mass quantity using the standard gravitational acceleration constant. All inputs must be strict Quantity objects with explicit units.

Parameters:

• takeup_weight_force (Quantity) – Takeup weight force in newtons or equivalent force units.

• unit (str, optional) – Output unit for mass result (default: “kilogram”). Common values: “kilogram”, “gram”. Must be a mass unit.

• precision (int or None, optional) – Decimal places to round the result to (default: None). If None, no rounding is applied.

Returns:

Takeup weight in the specified output unit.

Return type:

Quantity

Raises:

• ValueError – If unit conversion fails due to incompatible input units.

• ValueError – If takeup_weight_force is negative.

• ValueError – If unit is invalid or incompatible with mass.

Examples

>>> from pint import Quantity
>>> from eytelwein.main.units import get_unit_registry
>>> u = get_unit_registry()
>>> result = takeup_weight_from_takeup_weight_force(
...     takeup_weight_force=Quantity(29419.95, u.newton)
... )
>>> result
3000.0... kilogram