Suspension Kinematic#

Suspension files#

Suspension files#

This module provides functions to load and save suspension geometry data.

pymycar.SuspensionKinematic.suspension_files.load_defined_geometry(file_path)[source]#

Load suspension geometry data from a text file into a dictionary.

Parameters:
file_pathstr

The path to the text file containing the suspension geometry data.

Returns:
dict

A dictionary where the keys are the names of the suspension points and the values are numpy arrays containing the x, y, and z coordinates.

pymycar.SuspensionKinematic.suspension_files.saved_defined_geometry(data, file_path)[source]#

Save suspension geometry data from a dictionary to a text file.

Parameters:
datadict

A dictionary where the keys are the names of the suspension points and the values are numpy arrays containing the x, y, and z coordinates.

file_pathstr

The path to the text file where the suspension geometry data will be saved.

functions#

Functions: Suspension Kinematic Analysis#

pymycar.SuspensionKinematic.functions.generate_wheel_center_heights(wheel_center_i, max_height_increase, max_height_decrease, height_step)[source]#

Generate a range of wheel center heights based on the initial height and specified ranges.

Parameters: - wheel_center_i (numpy.ndarray): Initial wheel center position [x, y, z]. - max_height_increase (float): Maximum absolute height increase from the initial position. - max_height_decrease (float): Maximum absolute height decrease from the initial position. - height_step (float): Increment step for height adjustments.

Returns: - wheel_center_heights (numpy.ndarray): Array of wheel center heights. - initial_height_index (int): Index of the initial height in the resulting array.

Example: >>> import numpy as np >>> # Initial wheel center position [x, y, z] >>> wheel_center_i = np.array([0, 10, 0]) >>> # Absolute maximum height increase and decrease >>> max_height_increase = 2.0 >>> max_height_decrease = 1.0 >>> # Increment step for height adjustments >>> height_step = 0.5 >>> # Generate wheel center heights >>> wheel_center_heights, initial_height_index = generate_wheel_center_heights(wheel_center_i, max_height_increase, max_height_decrease, height_step) >>> print(“Wheel Center Heights:”, wheel_center_heights) >>> print(“Initial Height Index:”, initial_height_index) Wheel Center Heights: [ 9. 9.5 10. 10.5 11. ] Initial Height Index: 2

pymycar.SuspensionKinematic.functions.get_caster_angle(data, index=None)[source]#

Calculate the caster angle for a suspension system.

Parameters: - Suspension (object): Suspension object containing UCA and LCA data.

Returns: - caster_angle (numpy.ndarray): Array of caster angle values (in radians).

pymycar.SuspensionKinematic.functions.get_deflection(data, index=None)[source]#
pymycar.SuspensionKinematic.functions.get_geometric_suspension(data, index=None)[source]#
pymycar.SuspensionKinematic.functions.get_kingpin_angle(data, index=None)[source]#

Calculate the kingpin angle for a suspension system.

Parameters: - S1 (object): Suspension object containing UCA and LCA data.

Returns: - kingpin_angle (numpy.ndarray): Array of kingpin angle values (in radians).

pymycar.SuspensionKinematic.functions.get_suspension_ratio(data, index=None)[source]#

Calculate the installation ratio (suspension ratio) for a suspension system.

The installation ratio (λ) is the ratio between the vertical movement of the wheel and the movement produced in the spring/damper. It is calculated as the numerical derivative of the spring length with respect to the wheel jounce.

Parameters:
datadict

Dictionary containing suspension geometry data. Must include keys “l_spring_mount”, “U_SPRING_MOUNT”, and “index_reference”.

indexint, optional

Index to use as the reference position. If None, uses data[“index_reference”].

Returns:
rationumpy.ndarray

Array of installation ratio values (float) for each position.

Notes

The installation ratio is defined as:

λ = d_wheel / d_spring

where d_wheel is the vertical displacement of the wheel (jounce) and d_spring is the displacement of the spring/damper. This ratio is used to compute equivalent vertical stiffness and damping.

Examples

>>> ratio = get_suspension_ratio(data)
>>> print(ratio)
[ 0.95  0.96  0.97 ... ]
pymycar.SuspensionKinematic.functions.get_wheel(data, index=None)[source]#
pymycar.SuspensionKinematic.functions.get_wheel_base(data, index=None)[source]#

Calculate the wheel base (longitudinal displacement) for a suspension system.

The wheel base is the longitudinal displacement of the wheel center along the vehicle’s X-axis, referenced to a given position (usually the static or initial position). It is positive when the displacement is forward.

Parameters:
datadict

Dictionary containing suspension geometry data. Must include the key “wheel_center” as an array of wheel center coordinates and “index_reference” as the reference index.

indexint, optional

Index to use as the reference position. If None, uses data[“index_reference”].

Returns:
wheel_basenumpy.ndarray

Array of wheel base values (float), representing the longitudinal displacement for each position.

Notes

The wheel base is calculated as the difference in the X-coordinate of the wheel center relative to the reference index.

Examples

>>> wheel_base = get_wheel_base(data)
>>> print(wheel_base)
[ 0.   10.   20.  ... ]
pymycar.SuspensionKinematic.functions.get_wheel_jounce(data, index=None)[source]#

Calculate the wheel jounce (vertical displacement) for a suspension system.

The wheel jounce is the vertical displacement of the wheel center along the vehicle’s Z-axis, referenced to a given position. It is positive when the displacement is upward.

Parameters:
datadict

Dictionary containing suspension geometry data. Must include the key “wheel_center” as an array of wheel center coordinates and “index_reference” as the reference index.

indexint, optional

Index to use as the reference position. If None, uses data[“index_reference”].

Returns:
wheel_jouncenumpy.ndarray

Array of wheel jounce values (float), representing the vertical displacement for each position.

Notes

The wheel jounce is calculated as the difference in the Z-coordinate of the wheel center relative to the reference index.

Examples

>>> wheel_jounce = get_wheel_jounce(data)
>>> print(wheel_jounce)
[ 0.   2.   4.  ... ]
pymycar.SuspensionKinematic.functions.get_wheel_track(data, index=None)[source]#

Calculate the wheel track (lateral displacement) for a suspension system.

The wheel track is the lateral displacement of the wheel center along the vehicle’s Y-axis, referenced to a given position. It is positive when the displacement is outward.

Parameters:
datadict

Dictionary containing suspension geometry data. Must include the key “wheel_center” as an array of wheel center coordinates and “index_reference” as the reference index.

indexint, optional

Index to use as the reference position. If None, uses data[“index_reference”].

Returns:
wheel_tracknumpy.ndarray

Array of wheel track values (float), representing the lateral displacement for each position.

Notes

The wheel track is calculated as the difference in the Y-coordinate of the wheel center relative to the reference index.

Examples

>>> wheel_track = get_wheel_track(data)
>>> print(wheel_track)
[ 0.   -5.   -10.  ... ]
pymycar.SuspensionKinematic.functions.rotm2eul(rotm, order='ZYX')[source]#

Converts a rotation matrix to Euler angles.

Parameters:

rotm (array-like): 3x3 rotation matrix. order (str): Order of the Euler angles (default is ‘ZYX’).

Returns:

eul (array): Euler angles in radians.

pymycar.SuspensionKinematic.functions.solve(wheel, index, initial_guess, residual, jacobian=None)[source]#

Solves a system of nonlinear equations for a sequence of wheel positions using the fsolve algorithm. This function iteratively solves for the unknowns at each wheel position, first moving forward from the given index to the end of the wheel array, then backward from the index to the start. The solutions are stored in a 2D array. Parameters ———- wheel : array_like

Array of wheel positions or values to iterate over.

indexint

Starting index in the wheel array for the forward and backward solution process.

initial_guessarray_like

Initial guess for the unknowns to be solved by fsolve.

residualcallable

Function that computes the residuals of the system of equations. Should have the signature residual(x, wheel_center_z).

jacobiancallable, optional

Function that computes the Jacobian matrix of the system. Should have the signature jacobian(x, wheel_center_z). Default is None.

Returns#

solution_savendarray

2D array of solutions for each wheel position. Each row corresponds to a wheel position, and each column to a solved variable.

Notes#

  • Uses scipy.optimize.fsolve for solving the nonlinear system.

  • The function modifies initial_guess during the process.

  • The function assumes that the length of initial_guess times 3 matches the number of variables to be solved for each wheel position.

pymycar.SuspensionKinematic.functions.wheel_angles(solution, index=None, degrees=False)[source]#

Double Whisbone#

Suspension: Double Wishbone#

This module provides functions to analyze and simulate the behavior of a double wishbone suspension system. The double wishbone suspension is a type of vehicle suspension design that uses two wishbone-shaped arms (or control arms) to locate the wheel. This type of suspension is widely used in various vehicles, from road cars to competition vehicles.

pymycar.SuspensionKinematic.double_whisbone.double_whisbone_base(data, max_height_increase, max_height_decrease, height_step, save_to_txt=True, result_folder_name='results', path=None)[source]#

Computes and solves the geometric constraints for a double wishbone suspension system.

The function generates different wheel center heights based on input constraints, then calculates the residuals for a non-linear optimization problem to find the correct configuration of the suspension system.

Parameters:
datadict

A dictionary containing the initial measurements and reference points for the suspension system. Expected keys include:

  • ‘wheel_center’: The initial wheel center position.

  • ‘uca_outer’: The outer UCA (Upper Control Arm) position.

  • ‘UCA_FRONT’: The front reference point for the UCA.

  • ‘UCA_REAR’: The rear reference point for the UCA.

  • ‘lca_outer’: The outer LCA (Lower Control Arm) position.

  • ‘LCA_FRONT’: The front reference point for the LCA.

  • ‘LCA_REAR’: The rear reference point for the LCA.

  • ‘tierod_outer’: The outer tierod position.

  • ‘TIEROD_INNER’: The inner reference point for the tierod.

max_height_increasefloat

Maximum increase in wheel center height for the analysis.

max_height_decreasefloat

Maximum decrease in wheel center height for the analysis.

height_stepfloat

Step size for incrementing and decrementing the wheel center height.

save_to_txtbool, optional

If True, the results will be saved to a text file. Default is True.

result_folder_namestr, optional

The name of the folder where results will be saved. Default is “results”.

pathstr, optional

The path where the results folder will be created. If None, the current working directory is used. Default is None.

Returns:
solutiondict
A dictionary with the optimized suspension parameters and their values:

  • ‘UCA_FRONT’: The front UCA position.

  • ‘UCA_REAR’: The rear UCA position.

  • ‘LCA_FRONT’: The front LCA position.

  • ‘LCA_REAR’: The rear LCA position.

  • ‘TIEROD_INNER’: The inner tierod position.

  • ‘uca_outer’: Optimized outer UCA positions.

  • ‘lca_outer’: Optimized outer LCA positions.

  • ‘tierod_outer’: Optimized outer tierod positions.

  • ‘wheel_center’: Optimized wheel center positions.

  • ‘index_reference’: Index reference for the wheel center heights.

Notes

The function utilizes an optimization algorithm to solve for the configuration of the suspension system that satisfies the geometric constraints. The geometric model assumes a double wishbone suspension layout with specific reference points for each component.

#
#                    ///    
#                    \-/ 
#             UCA_REAR* 
#                    /
#                   / 
#   -----------    /
#    |       |    /
#    |       |   *----------*UCA_FRONT
#    |       | uca_outer   /⁻\ 
#    |       |             /// 
#    |       |
#    |  wheel center
#    |   *   |        tierod_outer
#    |       |       *--------------------*TIEROD_INNER
#    |       |
#    |       |
#    |       |       lca_outer
#    |       |      *------------*LCA_REAR
#   -----------     \           /⁻\ 
#                    \          ///
#                     \ 
#                      *LCA_FRONT
#                     /⁻\ 
#                     ///

Points Name

Description

Type

wheel center

Center of the Wheel

mobile

UCA FRONT

Upper Control Arm Front

fixed

UCA REAR

Upper Control Arm Rear

fixed

uca outer

Upper Control Arm Outer

mobile

LCA FRONT

Lower Control Arm Front

fixed

LCA REAR

Lower Control Arm Rear

fixed

lca outer

Lower Control Arm Outer

mobile

TIEROD INNER

Inner Tie Rod

fixed

tierod outer

Outer Tie Rod

mobile
pymycar.SuspensionKinematic.double_whisbone.double_whisbone_configuration_1(data, max_height_increase, max_height_decrease, height_step, save_to_txt=True, result_folder_name='results', path=None)[source]#

Computes and solves the geometric constraints for a double wishbone suspension system.

The function generates different wheel center heights based on input constraints, then calculates the residuals for a non-linear optimization problem to find the correct configuration of the suspension system.

Parameters:
Datadict

A dictionary containing the initial measurements and reference points for the suspension system. Expected keys include:

  • ‘wheel_center’: The initial wheel center position.

  • ‘uca_outer’: The outer UCA (Upper Control Arm) position.

  • ‘UCA_FRONT’: The front reference point for the UCA.

  • ‘UCA_REAR’: The rear reference point for the UCA.

  • ‘lca_outer’: The outer LCA (Lower Control Arm) position.

  • ‘LCA_FRONT’: The front reference point for the LCA.

  • ‘LCA_REAR’: The rear reference point for the LCA.

  • ‘tierod_outer’: The outer tierod position.

  • ‘TIEROD_INNER’: The inner reference point for the tierod.

max_height_increasefloat

Maximum increase in wheel center height for the analysis.

max_height_decreasefloat

Maximum decrease in wheel center height for the analysis.

height_stepfloat

Step size for incrementing and decrementing the wheel center height.

save_to_txtbool, optional

If True, the results will be saved to a text file. Default is True.

Returns:
solutiondict
A dictionary with the optimized suspension parameters and their values:

  • ‘UCA_FRONT’: The front UCA position.

  • ‘UCA_REAR’: The rear UCA position.

  • ‘LCA_FRONT’: The front LCA position.

  • ‘LCA_REAR’: The rear LCA position.

  • ‘TIEROD_INNER’: The inner tierod position.

  • ‘uca_outer’: Optimized outer UCA positions.

  • ‘lca_outer’: Optimized outer LCA positions.

  • ‘tierod_outer’: Optimized outer tierod positions.

  • ‘wheel_center’: Optimized wheel center positions.

  • ‘index_reference’: Index reference for the wheel center heights.

Notes

The function utilizes an optimization algorithm to solve for the configuration of the suspension system that satisfies the geometric constraints. The geometric model assumes a double wishbone suspension layout with specific reference points for each component.

#                        
#                    ///    
#                    \-/  
#             UCA_REAR* 
#                    /
#                   /              
#   -----------    /
#    |       |    /
#    |       |   *----------*UCA_FRONT
#    |       | uca_outer   /⁻\ 
#    |       |             ///
#    |       |                        * U_SPRING_MOUNT
#    |  wheel center                 /
#    |   *   |        tierod_outer  .
#    |       |       *-------------/------*TIEROD_INNER
#    |       |                    .
#    |       |                   /
#    |       |     lca_outer    .
#    |       |     *-----------/-*LCA_REAR
#    |       |      \         . /⁻\ 
#   -----------      \       /  ///
#                     \     .
#                      \   * l_spring_mount 
#                       \ 
#                        *LCA_FRONT
#                       /⁻\ 
#                       ///

Points Name

Description

Type

wheel center

Center of the Wheel

mobile

UCA FRONT

Upper Control Arm Front

fixed

UCA REAR

Upper Control Arm Rear

fixed

uca outer

Upper Control Arm Outer

mobile

LCA FRONT

Lower Control Arm Front

fixed

LCA REAR

Lower Control Arm Rear

fixed

lca outer

Lower Control Arm Outer

mobile

TIEROD INNER

Inner Tie Rod

fixed

tierod outer

Outer Tie Rod

mobile

Spring/Damper Upper Mount

Supensión Superior

mobile

Spring/Damper Lower Mount

Supensión Inferior

mobile
pymycar.SuspensionKinematic.double_whisbone.double_whisbone_configuration_2(data, max_height_increase, max_height_decrease, height_step, save_to_txt=True, result_folder_name='results', path=None)[source]#

Computes and solves the geometric constraints for a double wishbone suspension system.

The function generates different wheel center heights based on input constraints, then calculates the residuals for a non-linear optimization problem to find the correct configuration of the suspension system.

Parameters:
datadict

A dictionary containing the initial measurements and reference points for the suspension system. Expected keys include:

  • ‘wheel_center’: The initial wheel center position.

  • ‘uca_outer’: The outer UCA (Upper Control Arm) position.

  • ‘UCA_FRONT’: The front reference point for the UCA.

  • ‘UCA_REAR’: The rear reference point for the UCA.

  • ‘lca_outer’: The outer LCA (Lower Control Arm) position.

  • ‘LCA_FRONT’: The front reference point for the LCA.

  • ‘LCA_REAR’: The rear reference point for the LCA.

  • ‘tierod_outer’: The outer tierod position.

  • ‘TIEROD_INNER’: The inner reference point for the tierod.

  • ‘push_rod_outer’: The outer push rod position.

  • ‘push_rod_inner’: The inner push rod position.

  • ‘ROCKER_PIVOT’: The rocker pivot position.

  • ‘ROCKER_PIVOT_AXIS’: The rocker pivot axis position.

  • ‘l_spring_mount’: The lower spring mount position.

  • ‘U_SPRING_MOUNT’: The upper spring mount position.

max_height_increasefloat

Maximum increase in wheel center height for the analysis.

max_height_decreasefloat

Maximum decrease in wheel center height for the analysis.

height_stepfloat

Step size for incrementing and decrementing the wheel center height.

save_to_txtbool, optional

If True, the results will be saved to a text file. Default is True.

result_folder_namestr, optional

The name of the folder where results will be saved. Default is “results”.

pathstr, optional

The path where the results folder will be created. If None, the current working directory is used. Default is None.

Returns:
solutiondict
A dictionary with the optimized suspension parameters and their values:

  • ‘UCA_FRONT’: The front UCA position.

  • ‘UCA_REAR’: The rear UCA position.

  • ‘LCA_FRONT’: The front LCA position.

  • ‘LCA_REAR’: The rear LCA position.

  • ‘TIEROD_INNER’: The inner tierod position.

  • ‘uca_outer’: Optimized outer UCA positions.

  • ‘lca_outer’: Optimized outer LCA positions.

  • ‘tierod_outer’: Optimized outer tierod positions.

  • ‘wheel_center’: Optimized wheel center positions.

  • ‘push_rod_outer’: Optimized outer push rod positions.

  • ‘push_rod_inner’: Optimized inner push rod positions.

  • ‘l_spring_mount’: Optimized lower spring mount positions.

  • ‘index_reference’: Index reference for the wheel center heights.

Notes

The function utilizes an optimization algorithm to solve for the configuration of the suspension system that satisfies the geometric constraints. The geometric model assumes a double wishbone suspension layout with specific reference points for each component.

#                                        l_spring_mount
#                                        *-\/\/\/\/\/\/\/\/\/\/\--* U_SPRING_MOUNT
#                    ///                /|                      /⁻\ 
#                    \-/  pushrod inner* |  *ROCKER PIVOT AXIS  ///
#             uca_rear*               / \| /
#                    /               /   *ROCKER PIVOT
#                   /               /   /⁻\ 
#   -----------    /  pushrod outer*    ///
#    |       |    /
#    |       |   *----------*uca_front
#    |       | uca_outer   /⁻\ 
#    |       |             ///
#    |       |
#    |  wheel center 
#    |   *   |        tierod_outer
#    |       |       *--------------------*tierod_inner
#    |       |
#    |       |
#    |       |   lca_outer
#    |       |      *------------*lca_rear
#   -----------     \           /⁻\ 
#                    \          ///
#                     \ 
#                      *lca_front
#                     /⁻\ 
#                     ///

Points Name

Description

Type

wheel center

Center of the Wheel

mobile

UCA FRONT

Upper Control Arm Front

fixed

UCA REAR

Upper Control Arm Rear

fixed

uca outer

Upper Control Arm Outer

mobile

LCA FRONT

Lower Control Arm Front

fixed

LCA REAR

Lower Control Arm Rear

fixed

lca outer

Lower Control Arm Outer

mobile

TIEROD INNER

Inner Tie Rod

fixed

tierod outer

Outer Tie Rod

mobile

pushrod outer

Pushrod Exterior

mobile

pushrod inner

Pushrod Interior

mobile

ROCKER PIVOT

Rocker pivot

fixed

ROCKER PIVOT AXIS

Rocker pivot axis

fixed

U SPRING MOUNT
Spring/damper

Upper Mount

fixed

l spring mount

Spring/Damper Lower Mount

mobile