mechanical_objects ¶

property torque: Torque

Net torque applied on the DC motor. It must be an instance of Torque.

It is computed as the difference between driving_torque and load_torque.

Returns¶

Torque: Net torque applied on the DC motor.

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

class Flywheel(name: str, inertia_moment: InertiaMoment)

Bases: RotatingObject

Flywheel object.

Attributes¶

namestr: Name of the flywheel.
driven_byRotatingObject: Rotating object that drives the flywheel, for example a DCMotor or a gear (SpurGear, HelicalGear, WormGear, WormWheel).
drivesRotatingObject: Rotating object driven by the flywheel, it can be a gear (SpurGear, HelicalGear, WormGear, WormWheel).
master_gear_ratiofloat: Gear ratio of the fixed joint between the flywheel and its driving rotating object.
master_gear_efficiencyfloat or int: Efficiency of the fixed joint between the flywheel and its driving rotating object.
angular_positionAngularPosition: Angular position of the flywheel.
angular_speedAngularSpeed: Angular speed of the flywheel.
angular_accelerationAngularAcceleration: Angular acceleration of the flywheel.
torqueTorque: Net torque applied on the flywheel.
driving_torqueTorque: Driving torque applied on the flywheel by its driving rotating object.
load_torqueTorque: Load torque applied on the flywheel by its driven rotating object.
inertia_momentInertiaMoment: Moment of inertia of the flywheel.
time_variablesdict: Time variables of the flywheel.

Methods¶

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 flywheel. It must be an instance of AngularAcceleration.

Returns¶

AngularAcceleration: Angular acceleration of the flywheel.

Raises

TypeError: If angular_acceleration is not an instance of AngularAcceleration.

property angular_position: AngularPosition

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

Returns¶

AngularPosition: Angular position of the flywheel.

Raises

TypeError: If angular_position is not an instance of AngularPosition.

property angular_speed: AngularSpeed

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

Returns¶

AngularSpeed: Angular speed of the flywheel.

Raises

TypeError: If angular_speed is not an instance of AngularSpeed.

property driven_by: RotatingObject

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

To set this property use add_fixed_joint.

Returns¶

RotatingObject: Master rotating object that drives the flywheel.

Raises

TypeError: If driven_by is not an instance of RotatingObject.

property drives: RotatingObject

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

To set this property use add_fixed_joint.

Returns¶

RotatingObject: Rotating object driven by the flywheel.

Raises

TypeError: If drives is not an instance of RotatingObject.

property driving_torque: Torque

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

Returns¶

Torque: Driving torque applied on the flywheel by its driving rotating object.

Raises

TypeError: If driving_torque is not an instance of Torque.

property inertia_moment: InertiaMoment

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

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

Returns¶

InertiaMoment: Moment of inertia of the flywheel.

Raises

TypeError: If inertia_moment is not an instance of InertiaMoment.

property load_torque: Torque

Load torque applied on the flywheel by its driven rotating object. It must be an instance of Torque.

Returns¶

Torque: Load torque applied on the flywheel by its driven rotating object.

Raises

TypeError: If load_torque is not an instance of Torque.

property master_gear_efficiency: float | int

Efficiency of the fixed joint between the flywheel and its driving rotating object. Since the relation between the flywheel and its neighbor elements in the powertrain elements is always a fixed joint, the efficiency is always equal to 1 and cannot be overwritten.

Returns¶

float or int: Efficiency of the fixed joint between the flywheel and its driving rotating object.

property master_gear_ratio: float

Gear ratio of the fixed joint between the flywheel and its driving rotating object. It must be a positive a float. Since the relation between the flywheel and its neighbor elements in the powertrain elements is always a fixed joint, the gear ratio will be always set to 1 by add_fixed_joint.

To set this property use add_fixed_joint.

Returns¶

float: Gear ratio of the fixed joint between the flywheel and its driving rotating object.

Raises

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

property name: str

Name of the flywheel. 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 flywheel instantiation, it cannot be changed afterward.

Returns¶

str: Name of the flywheel.

Raises

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

property time_variables: dict[str, list[UnitBase]]

Time variables of the flywheel. Each time variable is stored as a dictionary key-value pair. The available time variables are:

angular_position: 'angular position',
angular_speed: 'angular speed',
angular_acceleration: 'angular acceleration',
torque: 'torque',
driving_torque: 'driving torque',
load_torque: 'load torque'.

Corresponding values of the dictionary are lists of the respective time variable values.

At each time iteration, the Solver appends every time variables’ values to the relative list in the dictionary.

Returns¶

dict: Time variables of the flywheel.

See Also

property torque: Torque

Net torque applied on the flywheel. It must be an instance of Torque.

It is computed as the difference between driving_torque and load_torque.

Returns¶

Torque: Net torque applied on the flywheel.

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

class GearBase(name: str, n_teeth: int, module: Length, face_width: Length, inertia_moment: InertiaMoment, elastic_modulus: Stress)

Bases: RotatingObject

GearBase object.

Abstract base class for creating gear objects.

See Also

HelicalGear

SpurGear

WormWheel

class HelicalGear(name: str, n_teeth: int, inertia_moment: InertiaMoment, helix_angle: Angle, module: Length | None = None, face_width: Length | None = None, elastic_modulus: Stress | None = None)

Bases: SpurGear

HelicalGear object.

Attributes¶

namestr: Name of the helical gear.
n_teethint: Number of gear teeth.
inertia_momentInertiaMoment: Moment of inertia of the gear.
helix_angleAngle: Helix angle of the helical gear.
moduleLength: Unit of the gear teeth size.
reference_diameterLength: Reference diameter of the gear.
face_widthLength: Face width of the gear.
elastic_modulusStress: Elastic modulus of the material of the gear.
lewis_factorfloat: Factor used to compute stresses on the gear tooth.
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 teeth by the mating gear.
tangential_force_is_computablebool: Whether is possible to compute the tangential_force on the gear teeth.
bending_stressStress: Bending stress applied on the gear teeth by the mating gear.
bending_stress_is_computablebool: Whether is possible to compute the bending_stress on the gear teeth.
contact_stressStress: The stress generated by the contact with mating gear teeth.
contact_stress_is_computablebool: Whether is possible to compute the contact_stress on the gear teeth.
time_variablesdict: Time variables of the gear.

Methods¶

compute_tangential_force(): It computes the tangential_force applied on the gear teeth by the mating gear.
compute_bending_stress(): It computes the bending_stress applied on the gear teeth by the mating gear.
compute_contact_stress(): It computes the contact_stress generated by the contact with mating gear teeth.
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.

property bending_stress: Stress

Bending stress applied on the gear teeth by the mating gear. It must be an instance of Stress.

Returns¶

Stress: Bending stress applied on the gear teeth by the mating gear.

Raises

TypeError: If bending_stress is not an instance of Stress.

See Also

property bending_stress_is_computable: bool

Whether is possible to compute the bending_stress on the gear teeth.

The bending stress computation depends on the value of module and face_width, so if these optional parameters have been set at helical gear instantiation, then it is possible to compute the bending stress and this property is True, otherwise is False.

Returns¶

bool: Whether is possible to compute the bending stress on the gear teeth.

See Also

compute_bending_stress() → None

It computes the bending_stress applied on the gear teeth by the mating gear.

Notes

The bending stress computation is based on the following assumptions:

the tooth is stressed by the overall force acting on the tip of the tooth itself,
the most unfavorable situation is considered in the calculation, as if there is only one pair of teeth in contact within the contact segment,
the component of the overall force that determines the bending on the tooth is the only one considered and, for simplicity, is taken as having a value equal to the tangential force on the reference diameter,
the radial component of the overall force that causes a compressive stress on the tooth is neglected.

The bending stress is computed with the following formula:

\[\sigma_b = \frac{F_t}{m \, b \, Y_{LW}}\]

where:

\(F_t\) is the tangential_force applied on the tooth,
\(m\) is the gear module,
\(b\) is the gear tooth face_width,
\(Y_{LW}\) is the gear lewis_factor.

compute_contact_stress() → None

It computes the contact_stress generated by the contact with mating gear teeth.

Raises

ValueError

If a gear mating between two gears has not been set,
if mating_role is MatingMaster and its slave gear misses module parameter,
if mating_role is MatingMaster and its slave gear misses elastic_modulus parameter,
if mating_role is MatingSlave and its master gear misses module parameter,
if mating_role is MatingSlave and its master gear misses elastic_modulus parameter.

Notes

The contact stress computation is based on the following assumptions:

perfect elasticity of the materials the two mating gear,
absence of friction forces in the contact point,
small size of the contact surface compared to the size of the bodies between which contact occurs.

The contact stress is computed with the following formula:

\[\sigma_c = 0.262922 \, \sqrt{\frac{4 \, F_t \, \cos \beta}{b \, \cos \alpha_t \, \sin \alpha_t} \left( \frac{1}{D_1} + \frac{1}{D_2} \right) \, \frac{E_1 \, E_2}{E_1 + E_2}}\]

where:

\(F_t\) is the tangential_force applied on the tooth,
\(\beta\) is the gear helix_angle,
\(b\) is the gear face_width,
\(\alpha_t\) is the transverse pressure angle of the gear,
\(D_1\) is the gear reference_diameter,
\(D_2\) is the mating gear reference_diameter,
\(E_1\) is the gear elastic_modulus,
\(E_2\) is the mating gear elastic_modulus.

The transverse pressure angle of the gear can be computed with the formula:

\[\alpha_t = \tan^{-1} \frac{\tan \alpha}{\cos \beta}\]

where \(\alpha\) is the pressure angle of the gear, always equal to 20 degrees.

compute_tangential_force() → None

It computes the tangential_force applied on the gear teeth 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 contact_stress: Stress

Stress generated by the contact with mating gear teeth. It must be an instance of Stress.

Returns¶

Stress: The stress generated by the contact with mating gear teeth.

Raises

TypeError: If contact_stress is not an instance of Stress.

See Also

property contact_stress_is_computable: bool

Whether is possible to compute the contact_stress force on the gear teeth.

The contact stress computation depends on the value of module, face_width and elastic_modulus, so if these optional parameters have been set at helical gear instantiation, then it is possible to compute the contact stress and this property is True, otherwise is False.

Returns¶

bool: Whether is possible to compute the contact stress on the gear teeth.

See Also

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_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_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 elastic_modulus: Stress | None

Elastic modulus of the material of the gear. It must be an instance of Stress. It must be positive.

Returns¶

Stress: Elastic modulus of the material of the gear.

Raises

TypeError: If elastic_modulus is not an instance of Stress.
ValueError: If elastic_modulus value is negative or null.

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 HelicalGear
>>> from gearpy.units import InertiaMoment, Torque
>>> gear = HelicalGear(name = 'gear', n_teeth = 10, inertia_moment = InertiaMoment(1, 'kgm^2'))
>>> 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):
...     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):
...     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 face_width: Length | None

Face width of the gear. It must be an instance of Length.

Returns¶

Length: Face width of the gear.

Raises

TypeError: If face_width is not an instance of Length.

property helix_angle: Angle

Helix angle of the helical gear. It must be an instance of Angle lower than 90 degrees.

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

Returns¶

Angle: The helix angle of the helical gear.

Raises

TypeError: If helix_angle is not an instance of Angle.
ValueError: If helix_angle is greater than or equal to 90 degrees.

property inertia_moment: InertiaMoment

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

Once set at the helical 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 lewis_factor: float | None

Factor used to compute stresses on the gear tooth.

It is a tabular value that in general depends on the number of gear teeth, the pressure angle and the helix angle. In this case, the considered pressure angle is always 20 degrees, so the Lewis factor depends only on the number of gear teeth n_teeth and the helix_angle.

Returns¶

float: Factor used to compute stresses on the gear tooth.

Notes

The Lewis factor is a tabular value that depends on the helical gear virtual number of teeth, which can be computed as:

\[z_v = \frac{z}{\cos^2 \beta_b \, \cos \beta}\]

where:

\(z\) is the gear number of teeth n_teeth,
\(\beta\) is the gear helix_angle,
\(\beta_b\) is the gear base helix angle.

The gear base helix angle \(\beta_b\) can be computed as:

\[\beta_b = \tan^{-1} \left( \cos \alpha_t \, \cos \beta \right)\]

where the \(\alpha_t\) is the gear transverse pressure angle, which can be computed as:

\[\alpha_t = \tan^{-1} \frac{\tan \alpha}{\cos \beta}\]

where \(\alpha\) is the pressure angle of the gear, always equal to 20 degrees.

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_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 gear is fixed to another driving RotatingObject, then the ratio is 1, otherwise it is defined as the ratio between the gear number of teeth n_teeth and the same parameter of the master (driving) gear.

To set this property use add_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_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 module: Length | None

Unit of the gear teeth size. It must be an instance of Length.

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

Returns¶

Length: Unit of the gear teeth size.

Raises

TypeError: If module is not an instance of Length.

property n_teeth: int

Number of gear teeth. It must be a positive int.

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

Returns¶

int: Number of gear teeth.

Raises

TypeError: If n_teeth is not an int.
ValueError: If n_teeth is less than the minimum number of teeth, based on Lewis Factor table.

property name: str

Name of the helical 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 helical gear instantiation, it cannot be changed afterward.

Returns¶

str: Name of the helical gear.

Raises

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

property reference_diameter: Length | None

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

It is computed as the product of n_teeth times module at the helical gear instantiation and it cannot be changed afterward.

Returns¶

Length: Reference diameter of the gear.

property tangential_force: Force

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

Returns¶

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

Raises

TypeError: If tangential_force is not an instance of Force.

See Also

property tangential_force_is_computable: bool

Whether is possible to compute the tangential_force on the gear teeth.

The tangential force computation depends on the value of module, so if this optional parameter has been set at helical gear instantiation, then it is possible to compute the tangential force and this property is True, otherwise is False.

Returns¶

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

See Also

property time_variables: dict[str, list[UnitBase]]

Time variables of the gear. Each time variable is stored as a dictionary key-value pair. The available time variables are:

angular_position: 'angular position',
angular_speed: 'angular speed',
angular_acceleration: 'angular acceleration',
torque: 'torque',
driving_torque: 'driving torque',
load_torque: 'load torque',
tangential_force: 'tangential force',
bending_stress: 'bending stress',
contact_stress: 'contact stress'.

'tangential force', 'bending stress' and 'contact stress' are listed among time variables only if they are computable indeed, depending on which gear parameters are set at gear instantiation; see tangential_force_is_computable, bending_stress_is_computable and contact_stress_is_computable for more details.

Corresponding values of the dictionary are lists of the respective time variable values.

At each time iteration, the Solver appends every time variables’ values to the relative list in the dictionary.

Returns¶

dict: Time variables of the gear.

See Also

property torque: Torque

Net torque applied on the gear. It must be an instance of Torque.

It is computed as the difference between driving_torque and load_torque.

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

class MatingMaster

Bases: Role

MatingMaster object.

Role of the master gear in a gear mating.

class MatingSlave

Bases: Role

MatingSlave object.

Role of the slave gear in a gear mating.

class MechanicalObject(name: str)

Bases: ABC

MechanicalObject object.

Abstract base class for creating mechanical objects.

See Also

class MotorBase(name: str, inertia_moment: InertiaMoment)

Bases: RotatingObject

MotorBase object.

Abstract base class for creating motor objects.

See Also

DCMotor

class Role

Bases: ABC

Role object.

Abstract base class for creating role objects.

See Also

MatingMaster

MatingSlave

class RotatingObject(name: str, inertia_moment: InertiaMoment)

Bases: MechanicalObject

RotatingObject object.

Abstract base class for creating rotating objects.

See Also

class SpurGear(name: str, n_teeth: int, inertia_moment: InertiaMoment, module: Length | None = None, face_width: Length | None = None, elastic_modulus: Stress | None = None)

Bases: GearBase

SpurGear object.

Attributes¶

namestr: Name of the spur gear.
n_teethint: Number of gear teeth.
inertia_momentInertiaMoment: Moment of inertia of the gear.
moduleLength: Unit of the gear teeth size.
reference_diameterLength: Reference diameter of the gear.
face_widthLength: Face width of the gear.
elastic_modulusStress: Elastic modulus of the material of the gear.
lewis_factorfloat: Factor used to compute stresses on the gear tooth.
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 teeth by the mating gear.
tangential_force_is_computablebool: Whether is possible to compute the tangential_force on the gear teeth.
bending_stressStress: Bending stress applied on the gear teeth by the mating gear.
bending_stress_is_computablebool: Whether is possible to compute the bending_stress on the gear teeth.
contact_stressStress: The stress generated by the contact with mating gear teeth.
contact_stress_is_computablebool: Whether is possible to compute the contact_stress on the gear teeth.
time_variablesdict: Time variables of the gear.

Methods¶

compute_tangential_force(): It computes the tangential_force applied on the gear teeth by the mating gear.
compute_bending_stress(): It computes the bending_stress applied on the gear teeth by the mating gear.
compute_contact_stress(): It computes the contact_stress generated by the contact with mating gear teeth.
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.

property bending_stress: Stress

Bending stress applied on the gear teeth by the mating gear. It must be an instance of Stress.

Returns¶

Stress: Bending stress applied on the gear teeth by the mating gear.

Raises

TypeError: If bending_stress is not an instance of Stress.

See Also

property bending_stress_is_computable: bool

Whether is possible to compute the bending_stress on the gear teeth.

The bending stress computation depends on the value of module and face_width, so if these optional parameters have been set at spur gear instantiation, then it is possible to compute the bending stress and this property is True, otherwise is False.

Returns¶

bool: Whether is possible to compute the bending stress on the gear teeth.

See Also

compute_bending_stress() → None

It computes the bending_stress applied on the gear teeth by the mating gear.

Notes

The bending stress computation is based on the following assumptions:

the tooth is stressed by the overall force acting on the tip of the tooth itself,
the most unfavorable situation is considered in the calculation, as if there is only one pair of teeth in contact within the contact segment,
the component of the overall force that determines the bending on the tooth is the only one considered and, for simplicity, is taken as having a value equal to the tangential force on the reference diameter,
the radial component of the overall force that causes a compressive stress on the tooth is neglected.

The bending stress is computed with the following formula:

\[\sigma_b = \frac{F_t}{m \, b \, Y_{LW}}\]

where:

\(F_t\) is the tangential_force applied on the tooth,
\(m\) is the gear module,
\(b\) is the gear tooth face_width,
\(Y_{LW}\) is the gear lewis_factor.

compute_contact_stress() → None

It computes the contact_stress generated by the contact with mating gear teeth.

Raises

ValueError

If a gear mating between two gears has not been set,
if mating_role is MatingMaster and its slave gear misses module parameter,
if mating_role is MatingMaster and its slave gear misses elastic_modulus parameter,
if mating_role is MatingSlave and its master gear misses module parameter,
if mating_role is MatingSlave and its master gear misses elastic_modulus parameter.

Notes

The contact stress computation is based on the following assumptions:

perfect elasticity of the materials the two mating gear,
absence of friction forces in the contact point,
small size of the contact surface compared to the size of the bodies between which contact occurs.

The contact stress is computed with the following formula:

\[\sigma_c = 0.262922 \, \sqrt{\frac{4 \, F_t}{b \, \cos \alpha \, \sin \alpha} \left( \frac{1}{D_1} + \frac{1}{D_2} \right) \, \frac{E_1 \, E_2}{E_1 + E_2}}\]

where:

\(F_t\) is the tangential_force tangential force applied on the tooth,
\(b\) is the gear face_width,
\(\alpha\) is the pressure angle of the gear, always equal to 20 degrees,
\(D_1\) is the gear reference_diameter,
\(D_2\) is the mating gear reference_diameter,
\(E_1\) is the gear elastic_modulus,
\(E_2\) is the mating gear elastic_modulus.

compute_tangential_force() → None

It computes the tangential_force applied on the gear teeth 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 contact_stress: Stress

Stress generated by the contact with mating gear teeth. It must be an instance of Stress.

Returns¶

Stress: The stress generated by the contact with mating gear teeth.

Raises

TypeError: If contact_stress is not an instance of Stress.

See Also

property contact_stress_is_computable: bool

Whether is possible to compute the contact_stress force on the gear teeth.

The contact stress computation depends on the value of module, face_width and elastic_modulus, so if these optional parameters have been set at spur gear instantiation, then it is possible to compute the contact stress and this property is True, otherwise is False.

Returns¶

bool: Whether is possible to compute the contact stress on the gear teeth.

See Also

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_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_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 elastic_modulus: Stress | None

Elastic modulus of the material of the gear. It must be an instance of Stress. It must be positive.

Returns¶

Stress: Elastic modulus of the material of the gear.

Raises

TypeError: If elastic_modulus is not an instance of Stress.
ValueError: If elastic_modulus value is negative or null.

property external_torque: Callable[[AngularPosition, AngularSpeed, Time], 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 SpurGear
>>> from gearpy.units import InertiaMoment, Torque
>>> gear = SpurGear(name = 'gear', n_teeth = 10, inertia_moment = InertiaMoment(1, 'kgm^2'))
>>> gear.external_torque = lambda angular_position, angular_speed, time: Torque(5, 'Nm')

Torque dependent on angular_position and time.

>>> import numpy as np
>>> from gearpy.units import AngularPosition, AngularSpeed, Time
>>> def custom_external_torque(angular_position: AngularPosition,
...                            angular_speed: AngularSpeed,
...                            time: Time):
...     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):
...     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 face_width: Length | None

Face width of the gear. It must be an instance of Length.

Returns¶

Length: Face width of the gear.

Raises

TypeError: If face_width is not an instance of Length.

property inertia_moment: InertiaMoment

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

Once set at the spur 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 lewis_factor: float | None

Factor used to compute stresses on the gear tooth.

It is a tabular value that in general depends on the number of gear teeth and the pressure angle. In this case, the considered pressure angle is always 20 degrees, so the Lewis factor depends only on the number of gear teeth n_teeth.

Returns¶

float: Factor used to compute stresses on the gear tooth.

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

To set this property use add_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_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 module: Length | None

Unit of the gear teeth size. It must be an instance of Length.

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

Returns¶

Length: Unit of the gear teeth size.

Raises

TypeError: If module is not an instance of Length.

property n_teeth: int

Number of gear teeth. It must be a positive integer.

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

Returns¶

int: Number of gear teeth.

Raises

TypeError: If n_teeth is not an int.
ValueError: If n_teeth is less than the minimum number of teeth, based on Lewis Factor table.

property name: str

Name of the spur 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 spur gear instantiation, it cannot be changed afterward.

Returns¶

str: Name of the spur gear.

Raises

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

property reference_diameter: Length | None

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

It is computed as the product of n_teeth times module at the spur gear instantiation and it cannot be changed afterward.

Returns¶

Length: Reference diameter of the gear.

property tangential_force: Force

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

Returns¶

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

Raises

TypeError: If tangential_force is not an instance of Force.

See Also

property tangential_force_is_computable: bool

Whether is possible to compute the tangential_force on the gear teeth.

The tangential force computation depends on the value of module, so if this optional parameter has been set at spur gear instantiation, then it is possible to compute the tangential force and this property is True, otherwise is False.

Returns¶

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

See Also

property time_variables: dict[str, list[UnitBase]]

Time variables of the gear. Each time variable is stored as a dictionary key-value pair. The available time variables are:

angular_position: 'angular position',
angular_speed: 'angular speed',
angular_acceleration: 'angular acceleration',
torque: 'torque',
driving_torque: 'driving torque',
load_torque: 'load torque',
tangential_force: 'tangential force',
bending_stress: 'bending stress',
contact_stress: 'contact stress'.

Corresponding values of the dictionary are lists of the respective time variable values.

At each time iteration, the Solver appends every time variables’ values to the relative list in the dictionary.

Returns¶

dict: Time variables of the gear.

See Also

property torque: Torque

Net torque applied on the gear. It must be an instance of Torque.

It is computed as the difference between driving_torque and load_torque.

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

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]

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.

>>> import numpy as np
>>> from gearpy.units import AngularPosition, AngularSpeed, Time
>>> def custom_external_torque(angular_position: AngularPosition,
...                            angular_speed: AngularSpeed,
...                            time: Time):
...     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):
...     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.

See Also

property tangential_force_is_computable: bool

Whether is possible to compute the tangential_force on the gear threads.

The tangential force computation depends on the value of reference_diameter, so if this optional parameter has been set at worm gear instantiation, then it is possible to compute the tangential force and this property is True, otherwise is False.

Returns¶

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

See Also

property time_variables: dict[str, list[UnitBase]]

Time variables of the gear. Each time variable is stored as a dictionary key-value pair. The available time variables are:

angular_position: 'angular position',
angular_speed: 'angular speed',
angular_acceleration: 'angular acceleration',
torque: 'torque',
driving_torque: 'driving torque',
load_torque: 'load torque',
tangential_force: 'tangential force'

'tangential force' is listed among time variables only if they are computable indeed, depending on which gear parameters are set at gear instantiation; see tangential_force_is_computable.

Corresponding values of the dictionary are lists of the respective time variable values.

At each time iteration, the Solver appends every time variables’ values to the relative list in the dictionary.

Returns¶

dict: Time variables of the gear.

See Also

property torque: Torque

Net torque applied on the gear. It must be an instance of Torque.

It is computed as the difference between driving_torque and load_torque.

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

class WormWheel(name: str, n_teeth: int, inertia_moment: InertiaMoment, helix_angle: Angle, pressure_angle: Angle, module: Length | None = None, face_width: Length | None = None)

Bases: HelicalGear

WormWheel object.

Attributes¶

namestr: Name of the worm wheel.
n_teethint: Number of gear teeth.
inertia_momentInertiaMoment: Moment of inertia of the gear.
helix_angleAngle: Helix angle of the worm wheel.
pressure_angleAngle: Pressure angle of the worm wheel.
moduleLength: Unit of the gear teeth size.
reference_diameterLength: Reference diameter of the gear.
face_widthLength: Face width of the gear.
lewis_factorfloat: Factor used to compute stresses on the gear tooth.
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 teeth by the mating gear.
tangential_force_is_computablebool: Whether is possible to compute the tangential_force on the gear teeth.
bending_stressStress: Bending stress applied on the gear teeth by the mating gear.
bending_stress_is_computablebool: Whether is possible to compute the bending_stress on the gear teeth.
time_variablesdict: Time variables of the gear.

Methods¶

compute_tangential_force(): It computes the tangential_force applied on the gear teeth by the mating gear.
compute_bending_stress(): It computes the bending_stress applied on the gear teeth 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.

property bending_stress: Stress

Bending stress applied on the gear teeth by the mating gear. It must be an instance of Stress.

Returns¶

Stress: Bending stress applied on the gear teeth by the mating gear.

Raises

TypeError: If bending_stress is not an instance of Stress.

See Also

property bending_stress_is_computable: bool

Whether is possible to compute the bending_stress on the gear teeth.

The bending stress computation depends on the value of module and face_width and the reference_diameter of the mating WormGear, so if these optional parameters have been set at worm wheel and worm gear instantiations, then it is possible to compute the bending stress and this property is True, otherwise is False.

Returns¶

bool: Whether is possible to compute the bending stress on the gear teeth.

See Also

compute_bending_stress() → None

It computes the bending_stress applied on the gear teeth by the mating gear.

Notes

The bending stress computation is based on the following assumptions:

the tooth is stressed by the overall force acting on the tip of the tooth itself,
the most unfavorable situation is considered in the calculation, as if there is only one pair of teeth in contact within the contact segment,
the component of the overall force that determines the bending on the tooth is the only one considered and, for simplicity, is taken as having a value equal to the tangential force on the reference diameter,
the radial component of the overall force that causes a compressive stress on the tooth is neglected.

The bending stress is computed with the following formula:

\[\sigma_b = \frac{F_t}{p_n \, b_{eff} \, Y_{LW}}\]

where:

\(F_t\) is the tangential_force applied on the tooth,
\(p_n\) is the normal pitch,
\(b_{eff}\) is the effective tooth face width,
\(Y_{LW}\) is the gear Lewis factor lewis_factor.

The normal pitch can be computed with:

\[p_n = \frac{\pi d_{wg} \sin \beta}{N}\]

where:

\(d_{wg}\) is the mating worm gear reference_diameter,
\(\beta\) is the mating worm gear helix_angle,
\(N\) is the worm wheel number of teeth n_teeth.

The effective tooth face width \(b_{eff}\) is the minimum between the worm wheel face width face_width and the mating worm gear reference diameter multiplied by 0.67.

compute_tangential_force() → None

It computes the tangential_force applied on the gear teeth 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]

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 WormWheel
>>> from gearpy.units import InertiaMoment, Torque
>>> gear = WormWheel(name = 'gear', n_teeth = 10, inertia_moment = InertiaMoment(1, 'kgm^2'))
>>> gear.external_torque = lambda angular_position, angular_speed, time: Torque(5, 'Nm')

Torque dependent on angular_position and time.

>>> import numpy as np
>>> from gearpy.units import AngularPosition, AngularSpeed, Time
>>> def custom_external_torque(angular_position: AngularPosition,
...                            angular_speed: AngularSpeed,
...                            time: Time):
...     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):
...     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 face_width: Length | None

Face width of the gear. It must be an instance of Length.

Returns¶

Length: Face width of the gear.

Raises

TypeError: If face_width is not an instance of Length.

property helix_angle: Angle

Helix angle of the worm wheel. 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 wheel.

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 wheel 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 lewis_factor: float | None

Factor used to compute stresses on the gear tooth.

It is a tabular value that depends on the pressure_angle.

Returns¶

float: Factor used to compute stresses on the gear tooth.

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 wheel gear is fixed to another driving RotatingObject, then the ratio is 1, otherwise it is defined as the ratio between the worm wheel number of teeth n_teeth and the driving worm gear number of starts WormGear.n_starts.

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 module: Length | None

Unit of the gear teeth size. It must be an instance of Length.

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

Returns¶

Length: Unit of the gear teeth size.

Raises

TypeError: If module is not an instance of Length.

property n_teeth: int

Number of gear teeth. It must be a positive int.

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

Returns¶

int: Number of gear teeth.

Raises

TypeError: If n_teeth is not an int.
ValueError: If n_teeth is less than the minimum number of teeth, based on Lewis Factor table.

property name: str

Name of the worm wheel. 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 wheel instantiation, it cannot be changed afterward.

Returns¶

str: Name of the worm wheel.

Raises

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

property pressure_angle: Angle

Pressure angle of the worm wheel. 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 wheel instantiation, it cannot be changed afterward.

Returns¶

Angle: The pressure angle of the worm wheel.

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.

It is computed as the product of n_teeth times module at the worm wheel instantiation and it cannot be changed afterward.

Returns¶

Length: Reference diameter of the gear.

property tangential_force: Force

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

Returns¶

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

Raises

TypeError: If tangential_force is not an instance of Force.

See Also

property tangential_force_is_computable: bool

Whether is possible to compute the tangential_force on the gear teeth.

The tangential force computation depends on the value of module, so if this optional parameter has been set at worm wheel instantiation, then it is possible to compute the tangential force and this property is True, otherwise is False.

Returns¶

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

See Also

property time_variables: dict[str, list[UnitBase]]

Time variables of the worm wheel. Each time variable is stored as a dictionary key-value pair. The available time variables are:

angular_position: 'angular position',
angular_speed: 'angular speed',
angular_acceleration: 'angular acceleration',
torque: 'torque',
driving_torque: 'driving torque',
load_torque: 'load torque',
tangential_force: 'tangential force',
bending_stress: 'bending stress'.

'tangential force' and 'bending stress' are listed among time variables only if they are computable indeed, depending on which gear parameters are set at worm wheel instantiation; see tangential_force_is_computable and bending_stress_is_computable.

Corresponding values of the dictionary are lists of the respective time variable values.

At each time iteration, the Solver appends every time variables’ values to the relative list in the dictionary.

Returns¶

dict: Time variables of the worm wheel.

See Also