SpurGear¶

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

compute_bending_stress()

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

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

compute_contact_stress()

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

compute_contact_stress()

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

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

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

compute_tangential_force()

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

compute_tangential_force()

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

update_time_variables()

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