Powertrain

class Powertrain(motor: MotorBase)

Bases: object

Powertrain object.

Attributes

elementstuple

Elements in the powertrain.

timelist

Simulated time steps.

self_lockingbool

Whether the powertrain can only be moved by the motor and not by the effect of the load.

Methods

plot()

It plots time variables for each element in the powertrain’s elements.

reset()

It resets the computed time variables.

snapshot()

Computes a snapshot of the time variables of the elements in the powertrain at the specified target_time.

update_time()

It updates the time by appending the instant simulated time step.

export_time_variables()

It exports the powertrain’s rotating objects’ computed time variables to some files.

Raises

TypeError

If motor parameter is not an instance of MotorBase.

ValueError

If motor is not connected to any other element.

NameError

If two or more elements in the powertrain elements share the same name.

property elements: tuple[RotatingObject]

Rotating objects in the powertrain.

The first element is the driving motor, the next elements are in order, from the closest to the farthest from the motor. Each element is driven by the previous one and it drives the following one.

Returns

tuple

Rotating objects in the powertrain.

See Also

DCMotor

Flywheel

HelicalGear

SpurGear

WormGear

WormWheel

export_time_variables(folder_path: str, 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 exports the powertrain’s elements’ computed time variables to some files.

It creates a file for each rotating object in the powertrain’s elements. The file name is taken from the rotating object’s name.

The exported files are a .csv files. 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

folder_pathstr

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

time_unitstr, optional

Symbol of the unit of measurement to which convert the time values in the exported files. 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 files. 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 files. 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 files. 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 files. 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 driving torque values in the exported files. 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 load torque values in the exported files. 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 files. 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 files. 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 files. It must be a str. Default is 'A'. See Current.unit for more details.

Raises

TypeError

• If folder_path is not 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 folder_path is an empty str.

plot(elements: list[RotatingObject | str] | None = None, variables: list[str] | None = None, 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', force_unit: str | None = 'N', stress_unit: str | None = 'MPa', current_unit: str | None = 'A', time_unit: str | None = 'sec', figsize: tuple | None = None) → None

It plots time variables for selected elements in the powertrain’s elements.

It generates a grid of subplots, one column for each selected element of the powertrain’s elements and one row for each selected time variable.

The available elements are listed in elements and the available variables are: 'angular position', 'angular speed', 'angular acceleration', 'torque', 'driving torque' and 'load torque'. The motor can have additional variables electric current and pwm while gears can have additional variables tangential force, bending stress and contact stress, depending on instantiation parameters.

The time variables are plotted in the described order, from the top row to the bottom one; torques are grouped together in a single row as well as stresses are grouped together. Plotted values’ units are managed with optional parameters.

Elements to be plotted can be passed as instances or names (str) in a list.

Parameters

elementslist, optional

Elements of the powertrain’s elements which time variables have to be plotted. Each single element can be passed as instance or name (str). Default is all elements in the powertrain’s elements.

variableslist, optional

Time variables to be plotted. Default is all available time variables.

angular_position_unitstr, optional

Symbol of the unit of measurement to which convert the angular position values in the plot. 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 plot. 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 plot. 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 plot. 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 plot. 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 plot. 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 plot. It must be a str. Default is 'A'. See Current.unit for more details.

time_unitstr, optional

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

figsizetuple, optional

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

Raises

TypeError

• If elements is not a list,

• if an element of elements is not an instance of RotatingObject or a str,

• if variables is not a list,

• if an element of variables 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 force_unit is not a str,

• if stress_unit is not a str,

• if current_unit is not a str,

• if time_unit is not a str,

• if figsize is not a tuple,

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

ValueError

• If elements is an empty list,

• if an element of elements is not in elements,

• if variables is an empty list,

• if an element of variables is not a valid time variable,

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

See Also

time

elements

DCMotor.time_variables

Flywheel.time_variables

HelicalGear.time_variables

SpurGear.time_variables

WormGear.time_variables

WormWheel.time_variables

reset() → None

It resets the computed time variables.

For each element in the powertrain’s elements, it resets each time variables and also time property.

See Also

DCMotor.time_variables

Flywheel.time_variables

HelicalGear.time_variables

SpurGear.time_variables

WormGear.time_variables

WormWheel.time_variables

property self_locking: bool

Whether the powertrain can only be moved by the motor and not by the effect of the load.

This property is given by the presence of a self-locking mating between a WormGear and a WormWheel in the powertrain. This type of 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 powertrain is self-locking, then it can only be moved by the motor and not by the load, even if the load torque is greater than the motor driving torque.

Once the property is defined at the Powertrain instantiation, it cannot be changed afterward.

Returns

bool

Whether the powertrain can only be moved by the motor and not by the effect of the load.

See Also

WormGear.self_locking

snapshot(target_time: Time, variables: list[str] | None = None, 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', print_data: bool | None = True) → DataFrame

It computes a snapshot of the time variables of the elements in the powertrain at the specified target_time.

It returns a pandas.DataFrame with the computed time variables. Each element in the powertrain’s elements is a row of the DataFrame, while the columns are the time variables 'angular position', 'angular speed', 'angular acceleration', 'torque', 'driving torque' and 'load torque'. The motor can have additional variables 'electric current' and 'pwm', while gears can have additional parameters 'tangential force', 'bending stress' and 'contact stress', depending on instantiation parameters.

It is possible to select the variables to be printed with the variables parameter.

Each time variable is converted to the relative unit passed as optional parameter.

If the target_time is not among simulated time steps in the time property, it computes a linear interpolation from the two closest simulated time steps.

Parameters

target_timeTime

The time to which compute the powertrain time variables’ snapshot. It must be an instance of Time, whose value must be within minimum and maximum simulated time steps in time property.

variableslist, optional

Time variables to be printed. It must be a list. Default is all available time variables.

angular_position_unitstr, optional

Symbol of the unit of measurement to which convert the angular position values in the DataFrame. 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 DataFrame. 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 DataFrame. 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 DataFrame. 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 driving torque values in the DataFrame. 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 load torque values in the DataFrame. 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 DataFrame. 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 DataFrame. 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 DataFrame. It must be a str. Default is 'A'. See Current.unit for more details.

print_databool, optional

Whether to print the computed time variables DataFrame. Default is True.

Returns

pandas.DataFrame

The DataFrame containing time variables values at the specified target_time for each element in the powertrain’s elements.

Raises

TypeError

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

• if target_time is not an instance of Time,

• if variables is not a list,

• if an element of variables 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,

• if print_data is not a bool.

ValueError

• If time is an empty list,

• if target_time is outside simulation interval,

• if variables is an empty list,

• if an element of variables is not a valid time variable.

See Also

time

elements

DCMotor.time_variables

Flywheel.time_variables

HelicalGear.time_variables

SpurGear.time_variables

WormGear.time_variables

WormWheel.time_variables

property time: list[Time]

List of the simulated time steps.

During computation, the solver appends a simulated time step to this list at each iteration.

Every element of this list must be an instance of Time.

Returns

list

The list of the simulated time steps.

See Also

Solver.run()

update_time(instant: Time) → None

It updates the time by appending the instant simulated time step.

Parameters

instantTime

Simulated time step to be added to time.

Raises

TypeError

If instant is not an instance of Time.