WormGear¶

class WormGear(name: str, n_starts: int, inertia_moment: InertiaMoment, helix_angle: Angle, pressure_angle: Angle, reference_diameter: Length | None = None)¶

Bases: RotatingObject

WormGear object.

Attributes¶

namestr: Name of the worm gear.
n_startsint: Number of starts, which refers to the number of independent threads running around the length of the thread.
inertia_momentInertiaMoment: Moment of inertia of the gear.
helix_angleAngle: Helix angle of the worm gear.
pressure_angleAngle: Pressure angle of the worm gear.
reference_diameterLength: Reference diameter of the gear.
self_lockingbool: Whether the WormGear cannot be moved by the mating WormWheel.
driven_byRotatingObject: Rotating object that drives the gear, for example a DCMotor, a Flywheel or another gear (SpurGear, HelicalGear, WormGear, WormWheel).
drivesRotatingObject: Rotating object driven by the gear, it can be a Flywheel or another gear (SpurGear, HelicalGear, WormGear, WormWheel).
master_gear_ratiofloat: Gear ratio of the mating between the gear and its driving gear.
master_gear_efficiencyfloat or int: Efficiency of the gear mating between the gear and its driving gear.
mating_role: Role: The role of the gear in the gear mating.
angular_positionAngularPosition: Angular position of the gear.
angular_speedAngularSpeed: Angular speed of the gear.
angular_accelerationAngularAcceleration: Angular acceleration of the gear.
torqueTorque: Net torque applied on the gear.
driving_torqueTorque: Driving torque applied on the gear by its driving gear.
load_torqueTorque: Load torque applied on the gear by its driven gear or an external load.
tangential_forceForce: Tangential force applied on the gear threads by the mating gear.
tangential_force_is_computablebool: Whether is possible to compute the tangential_force on the gear threads.
time_variablesdict: Time variables of the gear.

Methods¶

compute_tangential_force(): It computes the tangential_force applied on the gear threads by the mating gear.
external_torque(): Custom function to compute the external torque applied on the gear.
update_time_variables(): It updates time_variables dictionary by appending the last value of each time variable to corresponding list.

property angular_acceleration: AngularAcceleration¶

Angular acceleration of the gear. It must be an instance of AngularAcceleration.

Returns¶

AngularAcceleration: Angular acceleration of the gear.

Raises

TypeError: If angular_acceleration is not an instance of AngularAcceleration.

property angular_position: AngularPosition¶

Angular position of the gear. It must be an instance of AngularPosition.

Returns¶

AngularPosition: Angular position of the gear.

Raises

TypeError: If angular_position is not an instance of AngularPosition.

property angular_speed: AngularSpeed¶

Angular speed of the gear. It must be an instance of AngularSpeed.

Returns¶

AngularSpeed: Angular speed of the gear.

Raises

TypeError: If angular_speed is not an instance of AngularSpeed.

compute_tangential_force() → None¶

It computes the tangential_force applied on the gear threads by the mating gear.

Considering a gear mating:

if the gear is the master one, then it takes into account the load_torque for the computation,
if the gear is the slave one, then it take into account the driving_torque for the computation.

The tangential force is computed dividing the just described reference torque by the reference radius (half of the reference_diameter).

Raises

ValueError: If a gear mating between two gears has not been set.

property driven_by: RotatingObject¶

Rotating object that drives the gear, for example a DCMotor, a Flywheel or another gear (SpurGear, HelicalGear, WormGear, WormWheel). It must be a RotatingObject.

To set this property use add_worm_gear_mating or add_fixed_joint.

Returns¶

RotatingObject: Master rotating object that drives the gear.

Raises

TypeError: If driven_by is not an instance of RotatingObject.

property drives: RotatingObject¶

Rotating object driven by the gear, it can be a Flywheel or another gear (SpurGear, HelicalGear, WormGear, WormWheel). It must be a RotatingObject.

To set this property use add_worm_gear_mating or add_fixed_joint.

Returns¶

RotatingObject: Rotating object driven by the gear.

Raises

TypeError: If drives is not an instance of RotatingObject.

property driving_torque: Torque¶

Driving torque applied on the gear by its driving gear. It must be an instance of Torque.

Returns¶

Torque: Driving torque applied on the gear by its driving gear.

Raises

TypeError: If driving_torque is not an instance of Torque.

property external_torque: Callable[[AngularPosition, AngularSpeed, Time], Torque]¶

Custom function to compute the external torque applied on the gear. It must be a function with parameters angular_position, angular_speed and time. The function must return an instance of Torque.

Returns¶

Callable: The function to compute the external torque applied on the gear.

Raises

TypeError: If external_torque() is not callable.
KeyError: If external_torque() misses parameters angular_position, angular_speed or time.

Examples

Constant torque, not dependent on angular_position, angular_speed or time.

>>> from gearpy.mechanical_objects import WormGear
>>> from gearpy.units import InertiaMoment, Torque, Angle
>>> gear = WormGear(
...     name='gear',
...     n_starts=1,
...     inertia_moment=InertiaMoment(1, 'kgm^2'),
...     pressure_angle = Angle(20, 'deg'),
...     helix_angle = Angle(10, 'deg')
... )
>>> gear.external_torque = \
...     lambda angular_position, angular_speed, time: Torque(5, 'Nm')

Torque dependent on angular_position and time.

In this case the gear gets a periodic load, dependent on time, and an extra load dependent on its angular position. The dependence by angular position may be used to model cases where cams are involved.

>>> import numpy as np
>>> from gearpy.units import AngularPosition, AngularSpeed, Time
>>> def custom_external_torque(
...     angular_position: AngularPosition,
...     angular_speed: AngularSpeed,
...     time: Time
... ) -> Torque:
>>>     return Torque(
...         value=angular_position.sin() +
...         np.cos(time.to('sec').value),
...         unit='Nm'
...     )
>>> gear.external_torque = custom_external_torque

Torque dependent on angular_position, angular_speed and time.

With respect ot the previous case, the gear gets an extra load dependent on its angular speed. The dependence by angular speed may be used to model cases where air friction is not negligible.

>>> def complex_external_torque(
...     angular_position: AngularPosition,
...     angular_speed: AngularSpeed,
...     time: Time
... ) -> Torque:
>>>     return Torque(
...         value=angular_position.sin() +
...         0.001*(angular_speed.to('rad/s').value)**2 +
...         np.cos(time.to('sec').value),
...         unit='Nm'
...     )
>>> gear.external_torque = complex_external_torque

property helix_angle: Angle¶

Helix angle of the worm gear. It must be an instance of Angle.

The maximum allowable value of helix angle depends on the pressure_angle.

Once set at the worm gear instantiation, it cannot be changed afterward.

Returns¶

Angle: The helix angle of the worm gear.

Raises

TypeError: If helix_angle is not an instance of Angle.
ValueError: If helix_angle is greater than the maximum allowable helix angle, depending on pressure_angle value.

property inertia_moment: InertiaMoment¶

Moment of inertia of the gear. It must be an instance of InertiaMoment.

Once set at the worm gear instantiation, it cannot be changed afterward.

Returns¶

InertiaMoment: Moment of inertia of the gear.

Raises

TypeError: If inertia_moment is not an instance of InertiaMoment.

property load_torque: Torque¶

Load torque applied on the gear by its driven gear or an external load. It must be an instance of Torque.

Returns¶

Torque: Load torque applied on the gear by its driven gear or an external load.

Raises

TypeError: If load_torque is not an instance of Torque.

property master_gear_efficiency: float | int¶

Efficiency of the gear mating between the gear and its driving gear. It must be a float or an int within 0 and 1.

To set this property use add_worm_gear_mating or add_fixed_joint.

Returns¶

float or int: Efficiency of the gear mating between the gear and its driving gear.

Raises

TypeError: If master_gear_efficiency is not a float or an int.
ValueError: If master_gear_efficiency is not within 0 and 1.

property master_gear_ratio: float¶

Gear ratio of the mating between the gear and its driving gear. It must be a positive a float.

If the worm gear is fixed to another driving RotatingObject, then the ratio is 1, otherwise it is defined as the ratio between the worm gear number of starts n_starts and the driving wheel gear number of teeth WormWheel.n_teeth.

To set this property use add_worm_gear_mating or add_fixed_joint.

Returns¶

float: Gear ratio of the mating between the gear and its driving gear.

Raises

TypeError: If master_gear_ratio is not a float.
ValueError: If master_gear_ratio is negative or null.

property mating_role: Role¶

Role of the gear in the gear mating.

If the gear drives the mate one, then it is the “master” gear and its role is MatingMaster, otherwise it is the “slave” one and its role is MatingSlave.

To set this parameter use add_worm_gear_mating.

Returns¶

Role: The role of the gear in the gear mating.

Raises

ValueError: If mating_role is not a subclass of Role.

property n_starts: int¶

Number of starts, which refers to the number of independent threads running around the length of the thread. It must be a positive int equal to or greater than 1.

Once set at the worm gear instantiation, it cannot be changed afterward.

Returns¶

int: Number of starts, which refers to the number of independent threads running around the length of the thread.

Raises

TypeError: If n_starts is not an int.
ValueError: If n_starts is lower than 1.

property name: str¶

Name of the worm gear. It must be a non-empty str.

It must be a unique name, not shared by other elements in the powertrain elements.

Once set at the worm gear instantiation, it cannot be changed afterward.

Returns¶

str: Name of the worm gear.

Raises

TypeError: If name is not a str.
ValueError: If name is an empty str.

property pressure_angle: Angle¶

Pressure angle of the worm gear. It must be an instance of Angle and its value must be one of: 14.5 deg, 20 deg, 25 deg or 30 deg.

Once set at the worm gear instantiation, it cannot be changed afterward.

Returns¶

Angle: The pressure angle of the worm gear.

Raises

TypeError: If pressure_angle is not an instance of Angle.
ValueError: If pressure_angle value is not among available ones: 14.5 deg, 20 deg, 25 deg or 30 deg.

property reference_diameter: Length | None¶

Reference diameter of the gear. It must be an instance of Length.

Once set at the worm gear instantiation, it cannot be changed afterward.

Returns¶

Length: Reference diameter of the gear.

Raises

TypeError: If reference_diameter is not an instance of Length.

property self_locking: bool¶

Whether the WormGear cannot be moved by the mating WormWheel.

The gear mating can be self-locking if the amount of friction is high enough with respect to the gear pressure and helix angles.

If the mating is self-locking, then the WormGear cannot be moved by the mating WormWheel.

To set this property use add_worm_gear_mating.

Returns¶

bool: Whether the WormGear cannot be moved by the mating WormWheel.

property tangential_force: Force¶

Tangential force applied on the gear threads by the mating gear. It must be an instance of Force.

Returns¶

Force: Tangential force applied on the gear threads by the mating gear.

Raises

TypeError: If tangential_force is not an instance of Force.

Returns¶

bool: Whether is possible to compute the tangential force on the gear threads.

Returns¶

dict: Time variables of the gear.

Returns¶

Torque: Net torque applied on the gear.

Raises

TypeError: If torque is not an instance of Torque.

update_time_variables() → None¶: It updates time_variables dictionary by appending the last value of each time variable (key of the dictionary) to corresponding list (value of the dictionary).