Engee documentation

Vehicle Body

The model is a two-axle vehicle travelling in a longitudinal direction.

vehicle body

Description

Block Vehicle Body Represents the two-axle body of a vehicle in longitudinal motion. The vehicle may have the same or different number of wheels on each axle. For example, two wheels on the front axle and one wheel on the rear axle. It is assumed that the wheels of the vehicle are the same size. The centre of mass (CG) of the vehicle may be at or below the level of the plane of travel.

The unit takes into account vehicle mass, aerodynamic drag, road inclination and weight distribution between axles as a function of acceleration and road profile. Optionally, the vehicle pitch turn can be taken into account and suspension dynamics can be calculated. The vehicle does not move vertically relative to the ground.

The unit may include an external mass and an external inertia. The mass, inertia and centre of mass of the vehicle body may change during the simulation in response to changes in the system.

Model

The axes of the vehicle are parallel and form a plane. The longitudinal direction, , lies in this plane and is perpendicular to the axles. If the vehicle is travelling on an inclined plane with a slope , the normal direction, , is not parallel to gravity but is always perpendicular to the longitudinal plane of the vehicle axles.

The figure shows the variables of the vehicle motion model.

vehicle body 1

Variables that define the movement of the vehicle:

  • - parameter value Gravitational acceleration;

  • - road slope angle, value at port β;

  • - vehicle mass, determined from the parameters Mass and from the value at port M, if used;

  • - height of the vehicle centre of mass above the ground;

  • - the distance to the front and rear axles respectively from the point of normal projection of the vehicle centre of mass onto the common plane of the axles;

  • - the speed of the vehicle. When , the vehicle is travelling forwards. When , the vehicle is travelling backwards;

  • - wind speed. When , the wind is oncoming. When , the wind is crosswind;

  • - parameter value Number of wheels per axle. You can use an integer or a two-element vector, where the elements represent the front and rear axes, respectively;

  • - the longitudinal forces on each wheel at the front and rear ground contact points, respectively;

  • - normal load forces on each wheel at the front and rear ground contact points, respectively;

  • - midship area;

  • - aerodynamic drag coefficient;

  • - mass density of air;

  • - aerodynamic drag force.

Equations

Vehicle Dynamics

The motion of a vehicle is the result of all forces and torques acting on it. The longitudinal forces of the tyres push the vehicle forwards or backwards. The gravity force of the vehicle acts through its centre of mass. Depending on the angle of inclination, gravity pulls the vehicle towards the ground and the vehicle drives forwards or backwards under its influence. Whether the vehicle is travelling forwards or backwards, aerodynamic drag slows the vehicle down. For simplicity, it is assumed that the point of application of the aerodynamic drag force coincides with the centre of mass.

Zero normal acceleration and zero torque determine the normal force at each front and rear wheel.

The normal forces of the wheels fulfil the requirements:

If an externally given mass or inertia is included in the equation, the associated parameters in the equations change by the amount of the input.

Pitch body tilt dynamics.

The angular acceleration of body roll in the pitch plane depends on the three components of torque and vehicle inertia:

where

  • - is the angular acceleration at pitch rotation;

  • - longitudinal force;

  • - height of the centre of mass measured parallel to the axis ;

  • - inertia.

If a linear model for suspension stiffness and damping is selected, the block uses an approximation with the assumption of small angles for pitch angle calculations. If a tabulated model is selected, the block uses the specified vectors to calculate the pitch plane dynamics. For the rigid limiter equations, see Translational Hard Stop.

Limitations and assumptions

The block Vehicle Body only allows modelling of longitudinal dynamics parallel to the ground and oriented along the direction of travel. The vehicle is assumed to be in equilibrium along the longitudinal and normal axis. The unit does not model roll or vertical motion. Therefore, the equations assume that the wheels never lose contact. This limitation can result in negative normal forces.

Ports

Conserving

# H — horizontal movement
`translational mechanics'

Details

A mechanical non-directional port associated with the horizontal movement of the vehicle body. Connect tyre traction to this port.

Program usage name

flange

Output

# V — longitudinal velocity, m/s
scalar

Details

The longitudinal velocity of the vehicle in the associated coordinate system, in m/s.

Data types

Float64.

Complex numbers support

No

# NR — normal force on the rear axle, N
scalar

Details

Normal force on the rear axle, in N. Wheel forces are considered positive when acting downwards.

Data types

Float64.

Complex numbers support

No

# NF — normal force on the front axle, N
scalar

Details

Normal force on the front axle, in N. The forces on the wheels are considered positive if they act downwards.

Data types

Float64.

Complex numbers support

No

Input

# W — headwind speed, m/s
scalar

Details

Speed of the headwind, in m/s.

Data types

Float64.

Complex numbers support

No

# β — is the road slope angle, rad.
scalar

Details

the angle of inclination of the road, in rad.

Data types

Float64.

Complex numbers support

No

# CGX — position of the centre of mass along the x axis, m
scalar

Details

Position of the centre of mass of an external defined mass relative to the centre of mass of the vehicle body in the x axis, in m.

Dependencies

To use this parameter, select the check box. Externally-defined additional mass.

Data types

Float64.

Complex numbers support

No

# CGY — position of the centre of mass along the y axis, m
scalar

Details

Position of the centre of mass of an external defined mass relative to the centre of mass of the vehicle body in the y axis, in m.

Dependencies

To use this parameter, select the check box. Externally-defined additional mass.

Data types

Float64.

Complex numbers support

No

# M — mass, kg
scalar

Details

The value of an external defined mass, in kg.

Dependencies

To use this parameter, select the check box. Externally-defined additional mass.

Data types

Float64.

Complex numbers support

No

# J — external moment of inertia, kg⋅m2
scalar

Details

Moment of inertia of an external given mass, in kg⋅m2.

Dependencies

To use this parameter, select the checkbox Externally-defined additional mass и Pitch dynamics.

Data types

Float64.

Complex numbers support

No

Parameters

Main

# Mass — vehicle weight
g | t | kg | mg | oz | lbm | slug

Details

Vehicle Weight.

Units

g | t | kg | mg | oz | lbm | slug

Default value

1200.0 kg

Program usage name

m

Evaluatable

Yes

# Number of wheels per axle — number of wheels per axle

Details

Number of wheels on front and rear axles. If the input value is a scalar, the number of wheels on the front and rear axles is assumed to be the same. For example, if the input value is 2, it is assumed that the front and rear axles have two wheels each.

If the input value is a two-element vector, the first number is the number of wheels on the front axle and the second number is the number of wheels on the rear axle. For example, if the input is an array [2, 1], it is assumed that the front axle has two wheels and the rear axle has one wheel.

Default value

2

Program usage name

wheels_per_axle_count

Evaluatable

Yes

# Horizontal distance from CG to front axle — Distance from centre of mass to front axle
m | cm | ft | in | km | mi | mm | um | yd

Details

Horizontal distance, , from the centre of mass to the front wheel axle of the vehicle.

Units

m | cm | ft | in | km | mi | mm | um | yd

Default value

1.4 m

Program usage name

front_axle_distance

Evaluatable

Yes

# Horizontal distance from CG to rear axle — Distance from centre of mass to rear axle
m | cm | ft | in | km | mi | mm | um | yd

Details

Horizontal distance, , from the centre of mass to the rear wheel axle of the vehicle.

Units

m | cm | ft | in | km | mi | mm | um | yd

Default value

1.6 m

Program usage name

rear_axle_distance

Evaluatable

Yes

# CG height above ground — distance from the centre of mass to the ground
m | cm | ft | in | km | mi | mm | um | yd

Details

Distance, , between the vehicle’s centre of mass and the ground.

Units

m | cm | ft | in | km | mi | mm | um | yd

Default value

0.5 m

Program usage name

gravity_center_height

Evaluatable

Yes

# Externally-defined additional mass — variable mass inclusion

Details

Option to include mass as a time or event variable that affects the mass and centre of mass of the vehicle body. Use this option to account for vehicle occupants or bodies that are not rigidly attached.

Default value

false (switched off)

Program usage name

enable_additional_mass

Evaluatable

No

# Gravitational acceleration — free-fall acceleration
gee | m/(s^2) | cm/(s^2) | ft/(s^2) | in/(s^2) | km/(s^2) | mi/(s^2) | mm/(s^2)

Details

The acceleration caused by the gravitational force acting on the vehicle’s centre of mass.

Units

gee | m/(s^2) | cm/(s^2) | ft/(s^2) | in/(s^2) | km/(s^2) | mi/(s^2) | mm/(s^2)

Default value

9.81 m/(s^2)

Program usage name

g

Evaluatable

Yes

Drag

# Frontal area — effective cross-sectional area
m^2 | cm^2 | ft^2 | in^2 | km^2 | mi^2 | mm^2 | um^2 | yd^2

Details

Effective cross-sectional area of the front of the vehicle, . The unit uses this value to calculate the aerodynamic drag force of the vehicle.

Units

m^2 | cm^2 | ft^2 | in^2 | km^2 | mi^2 | mm^2 | um^2 | yd^2

Default value

3.0 m^2

Program usage name

midsection_area

Evaluatable

Yes

# Drag coefficient — aerodynamic drag coefficient

Details

Aerodynamic drag coefficient, . The unit uses this value to calculate the aerodynamic drag force of the vehicle.

Default value

0.4

Program usage name

C_d

Evaluatable

Yes

# Air density — ambient air density
g/cm^3 | kg/m^3 | lbm/gal

Details

The density of the air surrounding the vehicle.

Units

g/cm^3 | kg/m^3 | lbm/gal

Default value

1.18 kg/m^3

Program usage name

rho_air

Evaluatable

Yes

Pitch

# Pitch dynamics — suspension dynamics option

Details

Select this checkbox if you want to model suspension dynamics.

Default value

false (switched off)

Program usage name

enable_pitch_dynamics

Evaluatable

No

# Pitch moment of inertia — vehicle moment of inertia
g*cm^2 | kg*m^2 | lbm*ft^2 | lbm*in^2 | slug*ft^2 | slug*in^2

Details

Moment of inertia of the vehicle with respect to the transverse axis of rotation.

Dependencies

To use this parameter, select the check box. Pitch dynamics.

Units

g*cm^2 | kg*m^2 | lbm*ft^2 | lbm*in^2 | slug*ft^2 | slug*in^2

Default value

4000.0 kg*m^2

Program usage name

I_pitch

Evaluatable

Yes

# Suspension model — suspension parameterization method
Linear | By table lookup

Details

Parameterization method for suspension modelling. To specify data using scalar values, select Linear. To specify data using vector values, select . By table lookup.

Dependencies

To use this parameters, select the check box Pitch dynamics.

Values

Linear | By table lookup

Default value

Linear

Program usage name

suspension_parameterization

Evaluatable

No

# Front suspension stiffness — elasticity coefficient of the front suspension
N/m | lbf/ft | lbf/in

Details

Front suspension elasticity coefficient per axle.

Dependencies

To use this parameter, select the check box. Pitch dynamics*and for the parameters *Suspension model set the value Linear.

Units

N/m | lbf/ft | lbf/in

Default value

1e4 N/m

Program usage name

k_front_axle

Evaluatable

Yes

# Front suspension damping — front suspension damping
kg/s | N*s/m | N/(m/s) | lbf/(ft/s) | lbf/(in/s)

Details

Front suspension damping per axle.

Dependencies

To use this parameter, select the check box. Pitch dynamics*and for the parameters *Suspension model set the value Linear.

Units

kg/s | N*s/m | N/(m/s) | lbf/(ft/s) | lbf/(in/s)

Default value

1e4 N/(m/s)

Program usage name

C_front_axle

Evaluatable

Yes

# Rear suspension stiffness — rear suspension elasticity coefficient
N/m | lbf/ft | lbf/in

Details

Rear suspension elasticity coefficient per axle.

Dependencies

To use this parameter, select the check box. Pitch dynamics*and for the parameters *Suspension model set the value Linear.

Units

N/m | lbf/ft | lbf/in

Default value

1e4 N/m

Program usage name

k_rear_axle

Evaluatable

Yes

# Rear suspension damping — rear suspension damping coefficient
kg/s | N*s/m | N/(m/s) | lbf/(ft/s) | lbf/(in/s)

Details

Rear suspension damping coefficient per axle.

Dependencies

To use this parameter, select the check box. Pitch dynamics*and for the parameters *Suspension model set the value Linear.

Units

kg/s | N*s/m | N/(m/s) | lbf/(ft/s) | lbf/(in/s)

Default value

1e4 N/(m/s)

Program usage name

C_rear_axle

Evaluatable

Yes

# Front suspension stiffness force vector — elastic force of the front suspension
N | kN | lb | mN | dyn | lbf

Details

The elastic force of the front suspension. Set the output values for the interpolation table as a vector. The number of elements in the output vector must be the same as the number of elements in the input vector. The parameters of the input vector are the parameter Front suspension deformation vector.

Dependencies

To use this parameter, tick the checkbox. Pitch dynamics*and for the parameters *Suspension model set the value By table lookup.

Units

N | kN | lb | mN | dyn | lbf

Default value

[-2000.0, -1000.0, 0.0, 1000.0, 2000.0] N

Program usage name

k_front_axle_vector

Evaluatable

Yes

# Front suspension deformation vector — front suspension deformation
m | cm | ft | in | km | mi | mm | um | yd

Details

Deformation of the front suspension axle, given in terms of displacement. Set the input values for the interpolation table as a vector. The values of the elements in the vector should increase from left to right. The minimum number of elements in the vector depends on the chosen interpolation method Interpolation method. For Linear interpolation, specify at least two elements. For Smooth For interpolation, specify at least three elements. The parameters of the output vector are the parameters of the Front suspension stiffness force vector.

Dependencies

To use this parameter, tick the checkbox. Pitch dynamics*and for the parameters *Suspension model set the value By table lookup.

Units

m | cm | ft | in | km | mi | mm | um | yd

Default value

[-0.4, -0.2, 0.0, 0.2, 0.4] m

Program usage name

delta_p_front_axle_vector

Evaluatable

Yes

# Front suspension damping force vector — front suspension damping force
N | kN | lb | mN | dyn | lbf

Details

Damping force of the front suspension. Set the output values for the interpolation table as a vector. The number of elements in the output vector must be the same as the number of elements in the input vector. The parameters of the input vector are the parameter Front suspension velocity vector.

Dependencies

To use this parameter, tick the checkbox. Pitch dynamics*and for the parameters *Suspension model set the value By table lookup.

Units

N | kN | lb | mN | dyn | lbf

Default value

[-200.0, -100.0, 0.0, 100.0, 200] N

Program usage name

C_front_axle_vector

Evaluatable

Yes

# Front suspension velocity vector — front suspension speed
fpm | fps | kph | mph | m/s | cm/s | ft/s | in/s | km/s | mi/s | mm/s

Details

Front suspension speed. Set the input values for the interpolation table as a vector. The values of the elements in the vector should increase from left to right. The minimum number of elements in the vector depends on the selected interpolation method Interpolation method. For Linear interpolation, specify at least two elements. For Smooth For interpolation, specify at least three elements. The parameters of the output vector are the parameters of the Front suspension damping force vector.

Dependencies

To use this parameter, tick the checkbox. Pitch dynamics*and for the parameters *Suspension model set the value By table lookup.

Units

fpm | fps | kph | mph | m/s | cm/s | ft/s | in/s | km/s | mi/s | mm/s

Default value

[-4.0, -2.0, 0.0, 2.0, 4.0] m/s

Program usage name

v_front_axle_vector

Evaluatable

Yes

# Rear suspension stiffness force vector — rear suspension elastic force
N | kN | lb | mN | dyn | lbf

Details

The elastic force of the rear suspension. Set the output values for the interpolation table as a vector. The number of elements in the output vector must be the same as the number of elements in the input vector. The parameters of the input vector are the parameter Rear suspension deformation vector.

Dependencies

To use this parameter, tick the checkbox. Pitch dynamics*and for the parameters *Suspension model set the value By table lookup.

Units

N | kN | lb | mN | dyn | lbf

Default value

[-2000.0, -1000.0, 0.0, 1000.0, 2000.0] N

Program usage name

k_rear_axle_vector

Evaluatable

Yes

# Rear suspension deformation vector — rear suspension deformation
m | cm | ft | in | km | mi | mm | um | yd

Details

Rear suspension deformation given in terms of displacement. Set the input values for the interpolation table as a vector. The values of the elements in the vector should increase from left to right. The minimum number of elements in the vector depends on the chosen interpolation method Interpolation method. For Linear interpolation, specify at least two elements. For Smooth For interpolation, specify at least three elements. The parameters of the output vector is the parameter Rear suspension stiffness force vector.

Dependencies

To use this parameter, select the check box. Pitch dynamics*and for the parameters *Suspension model set the value By table lookup.

Units

m | cm | ft | in | km | mi | mm | um | yd

Default value

[-0.4, -0.2, 0.0, 0.2, 0.4] m

Program usage name

delta_p_rear_axle_vector

Evaluatable

Yes

# Rear suspension damping force vector — rear suspension damping force
N | kN | lb | mN | dyn | lbf

Details

Damping force of the rear suspension. Set the output values for the interpolation table as a vector. The number of elements in the output vector must be the same as the number of elements in the input vector. The parameters of the input vector are the parameter Rear suspension velocity vector.

Dependencies

To use this parameter, tick the checkbox. Pitch dynamics*and for the parameters *Suspension model set the value By table lookup.

Units

N | kN | lb | mN | dyn | lbf

Default value

[-200.0, -100.0, 0.0, 100.0, 200] N

Program usage name

C_rear_axle_vector

Evaluatable

Yes

# Rear suspension velocity vector — rear suspension speed
fpm | fps | kph | mph | m/s | cm/s | ft/s | in/s | km/s | mi/s | mm/s

Details

Rear suspension speed. Set the input values for the interpolation table as a vector. The values of the elements in the vector should increase from left to right. The minimum number of elements in the vector depends on the selected interpolation method Interpolation method. For Linear interpolation, specify at least two elements. For Smooth For interpolation, specify at least three elements. The parameters of the output vector are the parameters of the Rear suspension damping force vector.

Dependencies

To use this parameter, tick the checkbox. Pitch dynamics*and for the parameters *Suspension model set the value By table lookup.

Units

fpm | fps | kph | mph | m/s | cm/s | ft/s | in/s | km/s | mi/s | mm/s

Default value

[-4.0, -2.0, 0.0, 2.0, 4.0] m/s

Program usage name

v_rear_axle_vector

Evaluatable

Yes

# Interpolation method — interpolation method
Linear | Smooth

Details

Interpolation methods for approximating the output value when the input value is between two consecutive grid points are as follows:

  • Linear - select this option by default to get the best performance. Provide at least two values for each measurement.

  • Smooth - select this option to obtain a continuous curve with continuous first order derivatives. Provide at least three values per measurement.

Dependencies

To use this parameter, select the check box. Pitch dynamics*and for the parameters *Suspension model set the value By table lookup.

Values

Linear | Smooth

Default value

Linear

Program usage name

suspension_parameters_interpolation_method

Evaluatable

No

# Extrapolation method — extrapolation method
Linear | Nearest

Details

Extrapolation method to determine the output value when the input value is outside the range specified in the argument list:

  • Linear - obtains a curve with continuous first-order derivatives in the extrapolation region and at the boundary with the interpolation region.

  • Nearest - produces an extrapolation that does not rise above the highest point in the data or below the lowest point in the data.

Dependencies

To use this parameter, tick the checkbox. Pitch dynamics*and for the parameters *Suspension model set the value By table lookup.

Values

Linear | Nearest

Default value

Linear

Program usage name

suspension_parameters_extrapolation_method

Evaluatable

No

# Hard stop — hard stop modelling option

Details

Hard stop modelling option for front and rear suspension.

Dependencies

To use this parameters, tick the checkbox Pitch dynamics.

Default value

false (switched off)

Program usage name

enable_hardstop

Evaluatable

No

# Front upper bound — upper limit of the rigid front suspension limiter
m | cm | ft | in | km | mi | mm | um | yd

Details

Upper limit of the rigid limiter for the front suspension.

Dependencies

To use this parameter, select the checkbox Pitch dynamics и Hard stop.

Units

m | cm | ft | in | km | mi | mm | um | yd

Default value

0.25 m

Program usage name

front_upper_bound

Evaluatable

Yes

# Front lower bound — lower limit of the rigid front suspension limiter
m | cm | ft | in | km | mi | mm | um | yd

Details

Lower limit of the rigid limiter for the front suspension.

Dependencies

To use this parameter, select the checkbox Pitch dynamics и Hard stop.

Units

m | cm | ft | in | km | mi | mm | um | yd

Default value

-0.25 m

Program usage name

front_lower_bound

Evaluatable

Yes

# Front contact stiffness — elasticity coefficient of the rigid front suspension limiter
N/m | lbf/ft | lbf/in

Details

Elasticity coefficient of the rigid limiter for the front suspension.

Dependencies

To use this parameter, tick the checkbox. Pitch dynamics и Hard stop.

Units

N/m | lbf/ft | lbf/in

Default value

1e6 N/m

Program usage name

k_hardstop_front

Evaluatable

Yes

# Front contact damping — damping coefficient of the rigid front suspension limiter
kg/s | N*s/m | N/(m/s) | lbf/(ft/s) | lbf/(in/s)

Details

Damping coefficient of the rigid limiter for the front suspension.

Dependencies

To use this parameters, tick the checkbox. Pitch dynamics и Hard stop.

Units

kg/s | N*s/m | N/(m/s) | lbf/(ft/s) | lbf/(in/s)

Default value

150.0 N/(m/s)

Program usage name

C_hardstop_front

Evaluatable

Yes

# Rear upper bound — upper limit of the rigid rear suspension limiter
m | cm | ft | in | km | mi | mm | um | yd

Details

Upper limit of the rigid limiter for the rear suspension.

Dependencies

To use this parameter, select the checkbox Pitch dynamics и Hard stop.

Units

m | cm | ft | in | km | mi | mm | um | yd

Default value

0.25 m

Program usage name

rear_upper_bound

Evaluatable

Yes

# Rear lower bound — lower limit of the rigid rear suspension limiter.
m | cm | ft | in | km | mi | mm | um | yd

Details

Lower limit of the rigid limiter for the rear suspension.

Dependencies

To use this parameters, tick the checkbox Pitch dynamics и Hard stop.

Units

m | cm | ft | in | km | mi | mm | um | yd

Default value

-0.25 m

Program usage name

rear_lower_bound

Evaluatable

Yes

# Rear contact stiffness — elasticity coefficient of the rigid rear suspension limiter
N/m | lbf/ft | lbf/in

Details

Elasticity coefficient of the rigid limiter for the rear suspension.

Dependencies

To use this parameter, tick the checkbox. Pitch dynamics и Hard stop.

Units

N/m | lbf/ft | lbf/in

Default value

1e6 N/m

Program usage name

k_hardstop_rear

Evaluatable

Yes

# Rear contact damping — damping coefficient of the rigid rear suspension limiter
kg/s | N*s/m | N/(m/s) | lbf/(ft/s) | lbf/(in/s)

Details

Damping coefficient of the rigid limiter for the rear suspension.

Dependencies

To use this parameters, tick the checkbox. Pitch dynamics и Hard stop.

Units

kg/s | N*s/m | N/(m/s) | lbf/(ft/s) | lbf/(in/s)

Default value

150.0 N/(m/s)

Program usage name

C_hardstop_rear

Evaluatable

Yes

# Initial pitch — slope at the beginning of the simulation
deg | rad | rev | mrad

Details

The value of the slope in the longitudinal plane at the beginning of the simulation.

Dependencies

To use this parameters, tick the checkbox Pitch dynamics.

Units

deg | rad | rev | mrad

Default value

0.0 rad

Program usage name

pitch_angle_start

Evaluatable

Yes

# Initial pitch rate — angular velocity of rotation at the beginning of simulation
rpm | deg/s | rad/s

Details

Value of the tilt velocity in the longitudinal plane at the beginning of the simulation.

Dependencies

To use this parameters, select the checkbox Pitch dynamics.

Units

rpm | deg/s | rad/s

Default value

0.0 rad/s

Program usage name

w_pitch_start

Evaluatable

Yes