utils

class StopCondition(sensor: SensorBase, threshold: UnitBase, operator: OperatorBase)

Bases: object

StopCondition object.

Attributes

sensorSensorBase

The sensor to be monitored to check if the stop condition is valid.

thresholdUnitBase

The threshold value that triggers the stop condition.

operatorOperatorBase

The comparison operator to use to check if the stop condition is valid.

Methods

check_condition()

It applies the comparison operator to the sensor value and the threshold value to check if the stop condition is valid.

check_condition() → bool

It applies the comparison operator to the sensor value and the threshold value to check if the stop condition is valid.

If the stop condition is valid, then the Solver stops the computation even if it is not completed to the final simulation time.

Returns

bool

Whether stop condition is valid.

equal_to = <gearpy.utils.stop_condition.operator.EqualTo object>

greater_than = <gearpy.utils.stop_condition.operator.GreaterThan object>

greater_than_or_equal_to = <gearpy.utils.stop_condition.operator.GreaterThanOrEqualTo object>

less_than = <gearpy.utils.stop_condition.operator.LessThan object>

less_than_or_equal_to = <gearpy.utils.stop_condition.operator.LessThanOrEqualTo object>

property operator: OperatorBase

The comparison operator to use to check if the stop condition is valid.

The available operators are:

• StopCondition.greater_than to check if the sensor value is greater than the threshold value,

• StopCondition.greater_than_or_equal_to to check if the sensor value is greater than or equal to the threshold value,

• StopCondition.equal_to to check if the sensor value is equal to the threshold value,

• StopCondition.less_than to check if the sensor value is less than the threshold value,

• StopCondition.less_than_or_equal_to to check if the sensor value is less than or equal to the threshold value.

Returns

OperatorBase

The comparison operator to use to check if the stop condition is valid.

Raises

TypeError

If operator is not an instance of OperatorBase.

property sensor: SensorBase

The sensor to be monitored to check if the stop condition is valid.

Returns

SensorBase

The sensor to be monitored to check if the stop condition is valid.

Raises

TypeError

If sensor is not an instance of SensorBase.

See Also

AbsoluteRotaryEncoder

Amperometer

Tachometer

property threshold: UnitBase

The threshold value that triggers the stop condition.

Returns

UnitBase

The threshold value that triggers the stop condition.

Raises

TypeError

If threshold is not an instance of UnitBase.

add_fixed_joint(master: RotatingObject, slave: RotatingObject) → None

It creates a fixed joint between a master rotating object and a slave one. The fixed joint forces the two elements to rotate at the same angular position, speed and acceleration.

The master rotating object is closest to the powertrain driving motor (or it is actually it) and transfers the whole driving torque to the slave one.

Parameters

masterRotatingObject

Driving rotating object, it must be an instance of RotatingObject.

slaveRotatingObject

Driven rotating object, it must be an instance of RotatingObject, but not an instance of MotorBase.

Raises

TypeError

• If master is not an instance of RotatingObject,

• if slave is not an instance of RotatingObject,

• if slave is an instance of MotorBase.

ValueError

If master and slave are the same rotating object.

See Also

DCMotor.drives

Flywheel.drives

Flywheel.driven_by

Flywheel.master_gear_ratio

SpurGear.drives

SpurGear.driven_by

SpurGear.master_gear_ratio

HelicalGear.drives

HelicalGear.driven_by

HelicalGear.master_gear_ratio

WormGear.drives

WormGear.driven_by

WormGear.master_gear_ratio

WormWheel.drives

WormWheel.driven_by

WormWheel.master_gear_ratio

add_gear_mating(master: GearBase, slave: GearBase, efficiency: float | int) → None

It creates a gear mating between two existing gears. This mating is used to compose the Powertrain.

The ratio of the angular speed of the master gear over the angular speed of the slave gear is equal to the ratio of the slave gear number of teeth over the master gear number of teeth.

The master gear is closest to the motor and transfers a fraction of the driving torque to the slave one, based on the efficiency value: the higher the efficiency, the higher the fraction of transferred driving torque.

Parameters

masterGearBase

Driving gear. It must be an instance of GearBase.

slaveGearBase

Driven gear. It must be an instance of GearBase.

efficiencyfloat or int

Mechanical efficiency of the gear mating. It must be a float or an int between 0 and 1.

Raises

TypeError

• If master is not an instance of GearBase,

• if slave is not an instance of GearBase,

• if efficiency is not a float or an int.

ValueError

• If master and slave are the same gear,

• if efficiency is not within 0 and 1,

• if master and slave have different values for module (see SpurGear.module or HelicalGear.module)

• if master is an instance of HelicalGear but slave is not,

• if slave is an instance of HelicalGear but master is not,

• if both master and slave are instances of HelicalGear, but they have different HelicalGear.helix_angle.

See Also

SpurGear

SpurGear.master_gear_ratio

SpurGear.master_gear_efficiency

SpurGear.mating_role

SpurGear.drives

SpurGear.driven_by

SpurGear.module

HelicalGear

HelicalGear.master_gear_ratio

HelicalGear.master_gear_efficiency

HelicalGear.mating_role

HelicalGear.drives

HelicalGear.driven_by

HelicalGear.module

add_worm_gear_mating(master: WormGear | WormWheel, slave: WormGear | WormWheel, friction_coefficient: float | int) → None

It creates a gear mating between a worm gear and a worm wheel. This mating is used to compose the Powertrain.

The master gear is closest to the motor and transfers a fraction of the driving torque to the slave one, based on the mating efficiency, which depends on the friction_coefficient: the higher the friction_coefficient, the lower the fraction of transferred driving torque.

Parameters

masterWormGear or WormWheel

Driving gear. It must be an instance of WormGear or WormWheel, but different from slave.

slaveWormGear or WormWheel

Driven gear. It must be an instance of WormGear or WormWheel, but different from master.

friction_coefficientfloat or int

Static friction coefficient of the gear mating. It must be a float or an int between 0 and 1.

Raises

TypeError

• If master is not an instance of WormGear or WormWheel,

• if slave is not an instance of WormGear or WormWheel,

• if both master and slave are instances of WormGear,

• if both master and slave are instances of WormWheel,

• if friction_coefficient is not a float or an int.

ValueError

• If friction_coefficient is not within 0 and 1,

• if master and slave have different values for pressure_angle (see WormGear.pressure_angle or WormWheel.pressure_angle)

Notes

The gear ratio of the mating can be computed with the following relationship, regardless of master or slave roles:

\[\tau = \frac{n_z}{n_s}\]

where:

• \(\tau\) is the gear ratio, the ratio between the worm gear angular speed and the worm wheel angular speed,

• \(n_z\) is the worm wheel number of teeth,

• \(n_s\) is the worm gear number of starts.

If the WormGear is the master and the WormWheel is the slave, then the gear mating efficiency can be computed with the relationship:

\[\eta = \frac{\cos \alpha - f \, \tan \beta}{\cos \alpha + \frac{f}{\tan \beta}}\]

otherwise, if the WormGear is the slave and the WormWheel is the master, then the gear mating efficiency can be computed with the relationship:

\[\eta = \frac{\cos \alpha - \frac{f}{\tan \beta}}{\cos \alpha + f \, \tan \beta}\]

where:

• \(\eta\) is the gear mating efficiency,

• \(\alpha\) is the gear pressure angle, equal for both worm gear and worm wheel (WormGear.pressure_angle or WormWheel.pressure_angle),

• \(f\) is the friction_coefficient,

• \(\beta\) is the gear helix angle (WormGear.helix_angle or WormWheel.helix_angle).

The mating self-locking condition can be checked as:

\[f > \cos \alpha \, \tan \beta\]

See Also

WormGear

WormGear.master_gear_ratio

WormGear.master_gear_efficiency

WormGear.mating_role

WormGear.drives

WormGear.driven_by

WormGear.pressure_angle

WormGear.helix_angle

WormGear.self_locking

WormWheel

WormWheel.master_gear_ratio

WormWheel.master_gear_efficiency

WormWheel.mating_role

WormWheel.drives

WormWheel.driven_by

WormWheel.pressure_angle

WormWheel.helix_angle

dc_motor_characteristics_animation(motor: DCMotor, time: list[Time], interval: float | int | None = 200, torque_speed_curve: bool | None = True, torque_current_curve: bool | None = True, angular_speed_unit: str | None = 'rad/s', torque_unit: str | None = 'Nm', current_unit: str | None = 'A', figsize: tuple | None = None, line_color: str | None = None, marker_color: str | None = None, marker_size: float | int | None = None, padding: float | int | None = 0.1, title_decimals: int | None = 2, show: bool | None = True) → FuncAnimation

It generates an animation of a DCMotor torque-speed and torque-current characteristic curves and relative working points during the simulation.

Each simulated time step is a frame on the animation.

It generates two subplots, one for each characteristic curve. It is possible to isolate a single characteristic to be plotted with optional parameters torque_speed_curve and torque_current_curve.

The characteristic curves can be modified by the motor pulse width modulation DCMotor.pwm.

Plotted values’ units are managed with optional parameters angular_speed_unit, torque_unit and current_unit.

Aesthetic parameters are managed with optional parameters figsize, line_color, marker_color, marker_size and padding.

Parameters

motorDCMotor

DC motor whose characteristic curves and working point have to be animated.

timelist

The list of Time computed by the solver.

intervalfloat or int, optional

Delay between animation frames in milliseconds. If not provided defaults to 200.

torque_speed_curvebool, optional

Whether to plot the torque-speed characteristic curve. Default is True.

torque_current_curvebool, optional

Whether to plot the torque-current characteristic curve. Default is True.

angular_speed_unitstr, optional

Symbol of the unit of measurement to which convert the angular speed values in the plot. It must be a string. Default is 'rad/s'. See AngularSpeed.unit for more details.

torque_unitstr, optional

Symbol of the unit of measurement to which convert the torque values in the plot. It must be a string. Default is 'Nm'. See Torque.unit for more details.

current_unitstr, optional

Symbol of the unit of measurement to which convert the electric current values in the plot. It must be a string. Default is 'A'. See Current.unit for more details.

figsizetuple, optional

Width and height of the window size, in inches. If not provided defaults to [6.4, 4.8].

line_colorstr, optional

Color of the characteristic curve lines. If not provided defaults to '#1f77b4'.

marker_colorstr, optional

Color of the motor working point marker. If not provided defaults to '#ff7f0e'.

marker_sizefloat or int, optional

Size, in points, of the motor working point marker. If not provided defaults to 6.

paddingfloat or int, optional

Extra-space to be taken around each motor characteristics extreme points. It is expressed in percent points of the extreme point value. Default is 0.1, so it is taken 10% space around each characteristic extreme points.

Added in version 1.3.0.

title_decimalsint, optional

Number of decimals for time and PWM value reported in the title.

showbool, optional

Whether to show the animation. Default is True.

Raises

TypeError

• If motor is not an instance of DCMotor,

• if time is not a list,

• if an element of time is not an instance of Time,

• if interval is not a float or an int,

• if torque_speed_curve is not a bool,

• if torque_current_curve is not a bool,

• if angular_speed_unit is not a str,

• if torque_unit is not a str,

• if current_unit is not a str,

• if figsize is not a tuple,

• if an element of figsize is not a float or an int,

• if line_color is not a str,

• if marker_color is not a str,

• if marker_size is not a float or an int,

• if padding is not a float or an int,

• if title_decimals is not a int,

• if show is not a bool.

ValueError

• If time is an empty list,

• if both torque_speed_curve and torque_current_curve are set to False,

• if torque_current_curve is set to True but motor cannot compute DCMotor.electric_current property,

• if figsize has not exactly two elements: one for width and the other for height,

• if padding is negative.

See Also

DCMotor.angular_speed

DCMotor.driving_torque

DCMotor.electric_current

DCMotor.time_variables

DCMotor.pwm

export_time_variables(rotating_object: RotatingObject, file_path: str, time_array: list[Time], time_unit: str | None = 'sec', angular_position_unit: str | None = 'rad', angular_speed_unit: str | None = 'rad/s', angular_acceleration_unit: str | None = 'rad/s^2', torque_unit: str | None = 'Nm', driving_torque_unit: str | None = 'Nm', load_torque_unit: str | None = 'Nm', force_unit: str | None = 'N', stress_unit: str | None = 'MPa', current_unit: str | None = 'A') → None

It xports the computed time variables of a rotating object to a file.

The exported file is a .csv file. The time variables are exported in a tabular form, in which each column is a time variable and each row is a simulated time step. The columns are separated by a comma. The first column reports the simulated time steps and the first row reports the column names.

Parameters

rotating_objectRotatingObject

The rotating object whose time variables are to be exported.

file_pathstr

Path to the file in which to save the time variables. It must be a non-empty str.

time_arraylist

Simulated time steps. It must be a non-empty list.

time_unitstr, optional

Symbol of the unit of measurement to which convert the time values in the exported file. It must be a str. Default is 'sec'. See Time.unit for more details.

angular_position_unitstr, optional

Symbol of the unit of measurement to which convert the angular position values in the exported file. It must be a str. Default is 'rad'. See AngularPosition.unit for more details.

angular_speed_unitstr, optional

Symbol of the unit of measurement to which convert the angular speed values in the exported file. It must be a str. Default is 'rad/s'. See AngularSpeed.unit for more details.

angular_acceleration_unitstr, optional

Symbol of the unit of measurement to which convert the angular acceleration values in the exported file. It must be a str. Default is 'rad/s^2'. See AngularAcceleration.unit for more details.

torque_unitstr, optional

Symbol of the unit of measurement to which convert the torque values in the exported file. It must be a str. Default is 'Nm'. See Torque.unit for more details.

driving_torque_unitstr, optional

Symbol of the unit of measurement to which convert the torque values in the exported file. It must be a str. Default is 'Nm'. See Torque.unit for more details.

load_torque_unitstr, optional

Symbol of the unit of measurement to which convert the torque values in the exported file. It must be a str. Default is 'Nm'. See Torque.unit for more details.

force_unitstr, optional

Symbol of the unit of measurement to which convert the force values in the exported file. It must be a str. Default is 'N'. See Force.unit for more details.

stress_unitstr, optional

Symbol of the unit of measurement to which convert the stress values in the exported file. It must be a str. Default is 'MPa'. See Stress.unit for more details.

current_unitstr, optional

Symbol of the unit of measurement to which convert the electric current values in the exported file. It must be a str. Default is 'A'. See Current.unit for more details.

Raises

TypeError

• If rotating_object is not an instance of RotatingObject,

• if file_path is not a str,

• if time_array is not a list,

• if an element of time_array is not an instance of Time or a str,

• if time_unit is not a str,

• if angular_position_unit is not a str,

• if angular_speed_unit is not a str,

• if angular_acceleration_unit is not a str,

• if torque_unit is not a str,

• if driving_torque_unit is not a str,

• if load_torque_unit is not a str,

• if force_unit is not a str,

• if stress_unit is not a str,

• if current_unit is not a str.

ValueError

• If file_path is an empty str,

• if time_array is an empty list.