Skip to content
Snippets Groups Projects
Commit b280c58c authored by Enno Maschke's avatar Enno Maschke
Browse files

Modular vehicle dynamics model: add Sphinx documentation

parent ee657683
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
doc/source/user_guide/sim_user_guide/components/_static/images/VehicleDynamicsOverview.svg 0 → 100644
+ 1
− 0
View file @ b280c58c
<svg width="4430" height="1496" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" overflow="hidden"><defs><clipPath id="clip0"><rect x="-15" y="439" width="4430" height="1496"/></clipPath></defs><g clip-path="url(#clip0)" transform="translate(15 -439)"><rect x="390.5" y="441.5" width="714" height="226" stroke="#000000" stroke-width="4.58333" stroke-miterlimit="8" fill="#FFFFFF"/><text font-family="Times New Roman,Times New Roman_MSFontService,sans-serif" font-weight="400" font-size="64" transform="matrix(1 0 0 1 518.931 578)">ActionPowertrain</text><rect x="390.5" y="1074.5" width="714" height="226" stroke="#000000" stroke-width="4.58333" stroke-miterlimit="8" fill="#FFFFFF"/><text font-family="Times New Roman,Times New Roman_MSFontService,sans-serif" font-weight="400" font-size="64" transform="matrix(1 0 0 1 488.28 1210)">ActionBrakeSystem</text><rect x="390.5" y="1707.5" width="714" height="225" stroke="#000000" stroke-width="4.58333" stroke-miterlimit="8" fill="#FFFFFF"/><text font-family="Times New Roman,Times New Roman_MSFontService,sans-serif" font-weight="400" font-size="64" transform="matrix(1 0 0 1 458.202 1843)">ActionSteeringSystem</text><rect x="1647.5" y="1064.5" width="715" height="226" stroke="#000000" stroke-width="4.58333" stroke-miterlimit="8" fill="#FFFFFF"/><text font-family="Times New Roman,Times New Roman_MSFontService,sans-serif" font-weight="400" font-size="64" transform="matrix(1 0 0 1 1737.93 1200)">DynamicsTireModel</text><rect x="2647.5" y="1067.5" width="715" height="226" stroke="#000000" stroke-width="4.58333" stroke-miterlimit="8" fill="#FFFFFF"/><text font-family="Times New Roman,Times New Roman_MSFontService,sans-serif" font-weight="400" font-size="64" transform="matrix(1 0 0 1 2695.94 1204)">DynamicsMotionModel</text><rect x="3604.5" y="1064.5" width="715" height="226" stroke="#000000" stroke-width="4.58333" stroke-miterlimit="8" fill="#FFFFFF"/><text font-family="Times New Roman,Times New Roman_MSFontService,sans-serif" font-weight="400" font-size="64" transform="matrix(1 0 0 1 3732.82 1200)">DynamicsChassis</text><path d="M1104.5 556C1104.5 538.051 1119.05 523.5 1137 523.5 1154.95 523.5 1169.5 538.051 1169.5 556 1169.5 573.949 1154.95 588.5 1137 588.5 1119.05 588.5 1104.5 573.949 1104.5 556Z" stroke="#000000" stroke-width="4.58333" stroke-miterlimit="8" fill="#FFFFFF" fill-rule="evenodd"/><path d="M325.5 555C325.5 537.051 340.051 522.5 358 522.5 375.949 522.5 390.5 537.051 390.5 555 390.5 572.949 375.949 587.5 358 587.5 340.051 587.5 325.5 572.949 325.5 555Z" stroke="#000000" stroke-width="4.58333" stroke-miterlimit="8" fill="#FFFFFF" fill-rule="evenodd"/><path d="M1102.5 1186C1102.5 1168.05 1117.05 1153.5 1135 1153.5 1152.95 1153.5 1167.5 1168.05 1167.5 1186 1167.5 1203.95 1152.95 1218.5 1135 1218.5 1117.05 1218.5 1102.5 1203.95 1102.5 1186Z" stroke="#000000" stroke-width="4.58333" stroke-miterlimit="8" fill="#FFFFFF" fill-rule="evenodd"/><path d="M325.5 1187C325.5 1169.05 340.051 1154.5 358 1154.5 375.949 1154.5 390.5 1169.05 390.5 1187 390.5 1204.95 375.949 1219.5 358 1219.5 340.051 1219.5 325.5 1204.95 325.5 1187Z" stroke="#000000" stroke-width="4.58333" stroke-miterlimit="8" fill="#FFFFFF" fill-rule="evenodd"/><path d="M325.5 1820C325.5 1802.05 340.051 1787.5 358 1787.5 375.949 1787.5 390.5 1802.05 390.5 1820 390.5 1837.95 375.949 1852.5 358 1852.5 340.051 1852.5 325.5 1837.95 325.5 1820Z" stroke="#000000" stroke-width="4.58333" stroke-miterlimit="8" fill="#FFFFFF" fill-rule="evenodd"/><path d="M1102.5 1820C1102.5 1802.05 1117.05 1787.5 1135 1787.5 1152.95 1787.5 1167.5 1802.05 1167.5 1820 1167.5 1837.95 1152.95 1852.5 1135 1852.5 1117.05 1852.5 1102.5 1837.95 1102.5 1820Z" stroke="#000000" stroke-width="4.58333" stroke-miterlimit="8" fill="#FFFFFF" fill-rule="evenodd"/><path d="M25.0001 552.854 302.041 552.855 302.041 555.146 25.0001 555.146ZM297.458 540.25 324.958 554 297.458 567.75Z"/><path d="M27.9998 1185.85 301.332 1185.85 301.332 1188.15 27.9998 1188.15ZM296.749 1173.25 324.248 1187 296.748 1200.75Z"/><path d="M25.0001 1818.85 302.041 1818.85 302.041 1821.15 25.0001 1821.15ZM297.458 1806.25 324.958 1820 297.458 1833.75Z"/><path d="M1582.5 1186C1582.5 1168.05 1597.05 1153.5 1615 1153.5 1632.95 1153.5 1647.5 1168.05 1647.5 1186 1647.5 1203.95 1632.95 1218.5 1615 1218.5 1597.05 1218.5 1582.5 1203.95 1582.5 1186Z" stroke="#000000" stroke-width="4.58333" stroke-miterlimit="8" fill="#FFFFFF" fill-rule="evenodd"/><path d="M1169 553.854 1422.84 553.854 1422.84 1185.25 1421.69 1184.1 1558.84 1184.1 1558.84 1186.39 1420.55 1186.39 1420.55 555 1421.69 556.146 1169 556.146ZM1554.26 1171.5 1581.76 1185.25 1554.26 1199Z"/><path d="M0-1.14583 448.776-1.14583 448.776 578.488 446.485 578.488 446.485 0 447.63 1.14583 0 1.14583ZM461.38 573.905 447.63 601.405 433.88 573.905Z" transform="matrix(1 0 0 -1 1167 1819.41)"/><path d="M9.9608e-07-1.14583 392.233-1.14549 392.233 1.14617-9.9608e-07 1.14583ZM387.65-13.7497 415.15 0.000360892 387.65 13.7503Z" transform="matrix(1 0 0 -1 1167 1186)"/><path d="M2.82573e-06-1.14583 123.425-1.14553 123.425 1.14614-2.82573e-06 1.14583ZM118.842-13.7497 146.342 0.000360892 118.842 13.7503Z" transform="matrix(1 0 0 -1 1436 1186)"/><path d="M2362.5 1186C2362.5 1168.05 2377.05 1153.5 2395 1153.5 2412.95 1153.5 2427.5 1168.05 2427.5 1186 2427.5 1203.95 2412.95 1218.5 2395 1218.5 2377.05 1218.5 2362.5 1203.95 2362.5 1186Z" stroke="#000000" stroke-width="4.58333" stroke-miterlimit="8" fill="#FFFFFF" fill-rule="evenodd"/><path d="M2583.5 1187C2583.5 1169.05 2598.05 1154.5 2616 1154.5 2633.95 1154.5 2648.5 1169.05 2648.5 1187 2648.5 1204.95 2633.95 1219.5 2616 1219.5 2598.05 1219.5 2583.5 1204.95 2583.5 1187Z" stroke="#000000" stroke-width="4.58333" stroke-miterlimit="8" fill="#FFFFFF" fill-rule="evenodd"/><path d="M3362.5 1184C3362.5 1166.05 3377.05 1151.5 3395 1151.5 3412.95 1151.5 3427.5 1166.05 3427.5 1184 3427.5 1201.95 3412.95 1216.5 3395 1216.5 3377.05 1216.5 3362.5 1201.95 3362.5 1184Z" stroke="#000000" stroke-width="4.58333" stroke-miterlimit="8" fill="#FFFFFF" fill-rule="evenodd"/><path d="M3539.5 1181C3539.5 1163.05 3554.05 1148.5 3572 1148.5 3589.95 1148.5 3604.5 1163.05 3604.5 1181 3604.5 1198.95 3589.95 1213.5 3572 1213.5 3554.05 1213.5 3539.5 1198.95 3539.5 1181Z" stroke="#000000" stroke-width="4.58333" stroke-miterlimit="8" fill="#FFFFFF" fill-rule="evenodd"/><path d="M2427 1184.85 2560.35 1185.22 2560.34 1187.51 2427 1187.15ZM2555.8 1172.6 2583.26 1186.43 2555.73 1200.1Z"/><path d="M0.0334134-1.14535 89.6008 1.46762 89.5339 3.75831-0.0334134 1.14535ZM85.3869-11.2648 112.474 3.28123 84.585 16.2235Z" transform="matrix(1 0 0 -1 3427 1183.28)"/><path d="M0-1.14583 1449.69-1.14583 1449.69 578.064 1447.4 578.064 1447.4 0 1448.54 1.14583 0 1.14583ZM1462.29 573.48 1448.54 600.98 1434.79 573.48Z" transform="matrix(1 0 0 -1 1167 1819.98)"/><path d="M4319.5 1177.5C4319.5 1159.83 4334.05 1145.5 4352 1145.5 4369.95 1145.5 4384.5 1159.83 4384.5 1177.5 4384.5 1195.17 4369.95 1209.5 4352 1209.5 4334.05 1209.5 4319.5 1195.17 4319.5 1177.5Z" stroke="#000000" stroke-width="4.58333" stroke-miterlimit="8" fill="#FFFFFF" fill-rule="evenodd"/><path d="M4349.89 1145 4349.89 749.868 4351.03 751.014 1614 751.014 1615.15 749.868 1615.15 1130.81 1612.85 1130.81 1612.85 748.722 4352.18 748.722 4352.18 1145ZM1627.75 1126.23 1614 1153.73 1600.25 1126.23Z"/><text font-family="Times New Roman,Times New Roman_MSFontService,sans-serif" font-weight="400" font-size="37" transform="matrix(1 0 0 1 33 1793)">SteeringSignal</text><text font-family="Times New Roman,Times New Roman_MSFontService,sans-serif" font-weight="400" font-size="37" transform="matrix(1 0 0 1 28.1666 1162)">LongitudinalSignal</text><text font-family="Times New Roman,Times New Roman_MSFontService,sans-serif" font-weight="400" font-size="37" transform="matrix(1 0 0 1 17.7238 526)">LongitudinalSignal</text><text font-family="Times New Roman,Times New Roman_MSFontService,sans-serif" font-weight="400" font-size="37" transform="matrix(1 0 0 1 1169.96 1158)">BrakeTorque</text><text font-family="Times New Roman,Times New Roman_MSFontService,sans-serif" font-weight="400" font-size="37" transform="matrix(1 0 0 1 1176.53 531)">DriveTorque</text><text font-family="Times New Roman,Times New Roman_MSFontService,sans-serif" font-weight="400" font-size="37" transform="matrix(1 0 0 1 1202.2 1797)">WheelAngle</text><text font-family="Times New Roman,Times New Roman_MSFontService,sans-serif" font-weight="400" font-size="37" transform="matrix(1 0 0 1 4075.68 722)">VerticalTireForce</text><text font-family="Times New Roman,Times New Roman_MSFontService,sans-serif" font-weight="400" font-size="37" transform="matrix(1 0 0 1 2426.75 1150)">TireForce</text><text font-family="Times New Roman,Times New Roman_MSFontService,sans-serif" font-weight="400" font-size="37" transform="matrix(1 0 0 1 3394.91 1133)">InertiaForce</text></g></svg>
\ No newline at end of file
doc/source/user_guide/sim_user_guide/components/vehicle.rst
+ 207
− 0
View file @ b280c58c
......@@ -2,6 +2,7 @@
*******************************************************************************
Copyright (c) 2021 in-tech GmbH
2022-2023 Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
2023 Volkswagen AG
This program and the accompanying materials are made available under the
terms of the Eclipse Public License 2.0 which is available at
......@@ -549,3 +550,209 @@ Symbol Description
.. |br| raw:: html
<br>
VehicleDynamics
~~~~~~~~~~~~~~~
Components of this group can be used to model the vehicle dynamics. The vehicle dynamics model has a modular design. If necessary, the individual components can be replaced by the user with their own models. The vehicle dynamics model consists of six components listed below:
.. table::
:class: tight-table
================================ ==================================================================================================================================================================
Component Short Description
================================ ==================================================================================================================================================================
:ref:`components_steeringsystem` The steering model transfers the driver's input into the vehicle's wheel angle
:ref:`components_powertrain` The powertrain model converts the accelerator pedal position into wheel drive torques, under consideration of the selected gear
:ref:`components_brakesystem` The brake model converts the brake pedal position into wheel brake torques
:ref:`components_tiremodel` The tire model converts the predetermined drive and braking torques of the tires into tire longitudinal and lateral forces, under consideration of the wheel angles
:ref:`components_motionmodel` The motion model calculates the translational and rotational vehicle movement with the calculated tire forces
:ref:`components_chassismodel` The chassis model determines the dynamic wheel loads via the vehicle's longitudinal and lateral acceleration
================================ ===================================================================================================================================================================
The following figure gives an overview of the driving dynamics components and their signals:
.. image:: _static/images/VehicleDynamicsOverview.svg
:alt: |op| Vehicle dynamics overview
.. _components_steeringsystem:
ActionSteeringSystem
^^^^^^^^^^^^^^^^^^^^
The steering model obtains the "SteeringRatio" property from the :ref:`scenario_vehiclemodels` and uses it to calculate the steering angle of the front wheels.
Both wheels are turned at the same angle. Steering elasticities are currently not taken into account. The following parameter can be used to set a static toe:
.. table::
:class: tight-table
========= ============ ==== =========================================================================================================================
Attribute Type Unit Description
========= ============ ==== =========================================================================================================================
StaticToe VectorDouble rad Static toe of the wheels (A positive value corresponds to a toe-in; wheels are indexed from the front left in the vector)
========= ============ ==== =========================================================================================================================
.. _components_powertrain:
ActionPowertrain
^^^^^^^^^^^^^^^^
The powertrain model contains an engine model and a gear model. The type of the powertrain can be set using the following parameters:
.. table::
:class: tight-table
============== ====== ==== =============================================================================================================================
Attribute Type Unit Description
============== ====== ==== =============================================================================================================================
TypeDrivetrain String - Type of drivetrain; A selection can be made between front-wheel drive (FWD), rear-wheel drive (RWD) and all-wheel drive (AWD)
FrontRatioAWD Double - Distribution of the drive torque to the front axle in the case of all-wheel drive (AWD); Range 0-1
============== ====== ==== =============================================================================================================================
The wheel speed is converted into an engine speed [Hz] according to the axle ratio and the transmission ratio of the selected gear.
The axle ratio and gear ratios are obtained from the :ref:`scenario_vehiclemodels` ("AxleRatio" & "GearRatio"). The average value of the powered wheels is used for the determination of the engine speed.
.. math::
\omega_{engine} = \omega_{wheels,avg} \cdot i_{axle} \cdot i_{gear,selected}
The maximum possible engine torque [Nm] is limited by the engine power [W] or the maximum engine torque [Nm].
The engine power and the maximum engine torque are obtained from the :ref:`scenario_vehiclemodels` ("MaximumEnginePower" & "MaximumEngineTorque").
.. math::
M_{engine,max,current} = \begin{cases}
\frac{P_{engine,max}}{\omega_{engine}} & \text{ if } \frac{P_{engine,max}}{\omega_{engine}} < M_{engine,max} \\
M_{engine,max} & \text{ if } \frac{P_{engine,max}}{\omega_{engine}} >= M_{engine,max}
\end{cases}
When 98% of the maximum speed of the motor is reached ("MaximumEngineSpeed" in the :ref:`scenario_vehiclemodels`), the engine torque is linearly reduced to 0.
The maximum engine torque is scaled via the accelerator pedal position (input). This value is calculated back to the total wheel drive torque via the gear ratio.
.. math::
M_{wheels,current} = M_{engine,max,current} \cdot position_{accelerator pedal} \cdot i_{axle} \cdot i_{gear,selected}
The wheel total drive torque is evenly distributed to the wheels of an axle according to the definition of the drive type.
With all-wheel drive, the entire wheel drive torque is distributed statically over the defined ratio.
.. _components_brakesystem:
ActionBrakeSystem
^^^^^^^^^^^^^^^^^
The brake model is a linearized model. The brake pedal position is used as input. As output, the model returns the braking torques of the wheels as a vector.
The model considers a response time [ms] and linear factors [m/s³] for the increase and decrease of the braking force.The distribution of braking force between the front and rear axles can be defined statically.
.. table::
:class: tight-table
============================ ====== ==== ==============================================================================================================
Attribute Type Unit Description
============================ ====== ==== ==============================================================================================================
FrontAxlePercentage Double - Distribution of the brake torque to the front axle in the case of all-wheel drive (AWD); Range 0-1
BrakeDecelerationInclineRate Double m/s³ Linear Rate of braking force increase
BrakeDecelerationDeclineRate Double m/s³ Linear Rate of braking force decrease
BrakeResponseTimeMs Double ms Brake response time
============================ ====== ==== ==============================================================================================================
The maximum braking force of the system is determined from the maximum possible deceleration and the mass of the vehicle and is scaled by the brake pedal position (Input).
The maximum possible deceleration and the vehicle mass are obtained from the :ref:`scenario_vehiclemodels` ("maxDeceleration" & "mass").
.. math::
F_{brake,max} = a_{deceleration,max} \cdot m_{vehicle} \cdot position_{brake pedal}
When the brake is applied, a deceleration is calculated after the response time has elapsed. Then the braking force is built up linearly until the maximum or requested braking force has been reached.
.. math::
F_{brake,current} = rate_{incline} \cdot (t_{brake} - t_{response})
When the brake is released, the braking force is dissipated with the decline rate until it has dropped to zero. After that, the response time builds up again.
The braking force is divided among the axles according to the parameter "FrontAxlePercentage". Another input allows you to request a prefill that reduces the response time without braking
.. _components_chassismodel:
DynamicsChassis
^^^^^^^^^^^^^^^
The chassis model determines the vertical forces of the four wheels from the longitudinal and lateral acceleration of the vehicle. Constant spring and damper rates are taken into account, which can be defined by the following parameters per axis:
.. table::
:class: tight-table
============================ ============ ==== ==============================================================================================================
Attribute Type Unit Description
============================ ============ ==== ==============================================================================================================
SpringCoefficient VectorDouble N/m Constant spring coefficient for each axis
DamperCoefficient VectorDouble Ns/m Constant damper coefficient for each axis
============================ ============ ==== ==============================================================================================================
.. _components_tiremodel:
DynamicsTireModel
^^^^^^^^^^^^^^^^^
The tire model is freely configurable and includes a degressive behaviour. The tire forces are modeled according to Rill using the TMEasy model. The following parameters can be set for the tire model per axis :
.. table::
:class: tight-table
==================== ============ ==== ==============================================================================================================
Attribute Type Unit Description
==================== ============ ==== ==============================================================================================================
MuTireMaxXFRef VectorDouble - Normalized scaling factor for maximum longitudinal force at reference vertical force
MuTireMaxX2FRef VectorDouble - Normalized scaling factor for maximum longitudinal force at double reference vertical force
MuTireSlideXFRef VectorDouble - Normalized scaling factor for sliding longitudinal force at reference vertical force
MuTireSlideX2FRef VectorDouble - Normalized scaling factor for sliding longitudinal force at double reference vertical force
SlipTireMaxXFRef VectorDouble - Longitudinal slip at maximum longitudinal force at reference vertical force
SlipTireMaxX2FRef VectorDouble - Longitudinal slip at maximum longitudinal force at double reference vertical force
SlipTireSlideXFRef VectorDouble - Longitudinal slip at sliding longitudinal force at reference vertical force
SlipTireSlideX2FRef VectorDouble - Longitudinal slip at sliding longitudinal force at double reference vertical force
F0pXFRef VectorDouble N Initial slope of longitudinal force at reference force
F0pX2FRef VectorDouble N Initial slope of longitudinal force at double reference force
MuTireMaxYFRef VectorDouble - Normalized scaling factor for maximum lateral force at reference vertical force
MuTireMaxY2FRef VectorDouble - Normalized scaling factor for maximum lateral force at double reference vertical force
MuTireSlideYFRef VectorDouble - Normalized scaling factor for sliding lateral force at reference vertical force
MuTireSlideY2FRef VectorDouble - Normalized scaling factor for sliding lateral force at double reference vertical force
SlipTireMaxYFRef VectorDouble - Lateral slip at maximum lateral force at reference vertical force
SlipTireMaxY2FRef VectorDouble - Lateral slip at maximum lateral force at double reference vertical force
SlipTireSlideYFRef VectorDouble - Lateral slip at sliding lateral force at reference vertical force
SlipTireSlideY2FRef VectorDouble - Lateral slip at sliding lateral force at double reference vertical force
F0pYFRef VectorDouble N Initial slope of lateral force at reference force
F0pY2FRef VectorDouble N Initial slope of lateral force at double reference force
FRef VectorDouble N Vertical reference force for the tire parameters
FRefNormalized VectorBool - Should the reference force be scaled with the static vertical tire force?
Inertia VectorDouble kgm² Inertia of tire
PneumaticTrail VectorDouble m Pneumatic trail of tire
==================== ============ ==== =============================================================================================================
The normalized factors refer to the reference vertical force or to the double reference vertical force
The input variables used by the model are tire drive and braking torques as well as the wheel angles and vertical wheel forces. All data is provided as vectors.
The model determines tire forces in the longitudinal and lateral directions as well as the wheel self aligning torques. The wheel self aligning torque is formed from the product of the tire side force and the pneumatic trail.
A linear interpolation is performed between the values for the reference force and the double reference force. If no degressive tire behavior is desired, the parameters for the double reference force must be set identically to the values for the reference force.
All forces are scaled with the coefficient of friction from the :ref:`scenario_vehiclemodels` ("FrictionCoefficient").
All further information about the model can be found in the following sources:
https://www.tmeasy.de/
Rill, Georg. (2013). TMeasy -- A Handling Tire Model based on a three-dimensional slip approach.
.. _components_motionmodel:
DynamicsMotionModel
^^^^^^^^^^^^^^^^^^^
The motion model converts the tire forces (input) into a translational and rotational movement of the vehicle. The air resistance of the vehicle is taken into account. For the dynamic calculation, the center of gravity position is taken from the :ref:`scenario_vehiclemodels` ("XPositionCOG","YPositionCOG"),
which indicates the distance of the center of gravity to the center of the rear axle. If this data is not given, the center of gravity is positioned on half wheelbase. For air resistance, the properties "AirDragCoefficient" & "FrontSurface" from the :ref:`scenario_vehiclemodels` are used.
For the equations of motion, see relevant vehicle dynamics books such as:
Kücükay, Ferit (2022), "Grundlagen der Fahrzeugtechnik", page 1067 ff
\ No newline at end of file
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment

Copyright © Eclipse Foundation, Inc. All Rights Reserved.     Privacy Policy | Terms of Use | Copyright Agent