Interface to SDF Functions in msautotils

A description of MotionSolve .xml statements needed to generate SDFs.

Front end and rear end vehicle analyses, like kinematics and compliance, static load, and ride analyses employ a set of user functions in msautoutils.so or msautoutils.dll to compute Suspension Design Factors (SDFs) such as scrub radius, wheel stiffness, swing arm length.
The data to compute the SDFs depend mostly on runtime measurements, based on markers in the suspension. But some SDFs, for example, anti-lift or anti-dive, require information about the full vehicle, like the height of the vehicle center of gravity. To simplify usage the SDF output requests employ the same user function and inputs, even though only a subset of the inputs are needed for a specific SDF. The form of all output requests for SDFs is:
<Post_Request
     id                  = "80000000"
     comment             = "Wheel Vert. Displacement and Vert. Force"
     type                = "USERSUB"
     usrsub_param_string = "USER(0,0,1,31000200,0,31000100)"
     usrsub_dll_name     = "msautoutils"
     usrsub_fnc_name     = "sdfrequest"
  />
The ‘user_param_string’ attribute of the Post_Request element defines the data, that is passed into the subroutine. The members of the USER-array are defined according to the following table:
Index Name Assumed Type Example Purpose
0 Axle ID unsigned int 0 Provides a unique identifier to the axle. The axle index (counted from front to rear, where 0 is the index of the first axle) is usually a good unique identifier.
This value is used to assign any registered steering or travel lock, which has the same id to the suspension.
Note: The current implementation will assume the suffixes “front” and “read” from this value to distinguish output values.
1 Branch ID unsigned int 350 Identify the request to compute according to the table on SDF Output.
2 Testrig-Param-Array Version unsigned int 1 Specifies, which version of the following array to assume. Version 0 refers to a version before v2020. The most recent is version 1.
3 Testrig-Param-Array int/array-id 31000200 Solver ID of the array, that contains information about the testrig and how it applies measurement to the suspension.
4 Vehicle-Param-Array Version unsigned int 0 Specifies which version of the following array to assume. The most recent is version 0.
5 Vehicle-Param-Array int/array-id 31000100 Solver ID of the array, that contains information about the vehicle and how the suspension relates to it.

Testrig Parameters Array

The ID in USER-array element #2 refers to a solver-array of the following layout:
Index Name Assumed Type Example Purpose
0 Left Wheel Center Marker int/marker-id mrk_wc.l.id The marker should be located on the wheel center, but should be defined on the knuckle. The marker must have no freedom to spin with the wheel.
1 Right Wheel Center Marker int/marker-id mrk_wc.r.id
2 Left Lower Marker on Steer-Axis int/marker-id mrk_kp.l.id If the upper and lower steer axis markers are connected to the same body, the marker should be defined on this body at the location of the steer axis. This is usually the lower kingpin. In this case, the z-axis of the marker should point to the direction of the steer axis (upper kingpin).

If the two markers are not connected to the same body (McPherson strut), then direction and body of this marker has no effect, but a second marker must be defined in #13 and #14.

3 Right Lower Marker on Steer-Axis int/marker-id mrk_kp.r.id
4 Left Ground Reference Marker int/marker-id mrk_gnd.l.id This marker should be located on the wheel center, but defined on ground. It serves as a reference for the measurement of wheel travel and steer.
5 Vehicle-Param-Array int/marker-id mrk_gnd.r.id
6 Left Marker on Jack int/marker-id sfo_jack_actuator.l.i.id This marker should be defined on the jack. It serves to measure the jack motion.
7 Right Marker on Jack int/marker-id sfo_jack_actuator.l.r.id
8 Left Jack reference Marker on Ground int/marker-id sfo_jack_actuator.l.j.id This marker should be defined on the ground at the same location as the Marker on Jack. It serves as a reference to measure the jack motion.
9 Right Jack reference Marker on Ground int/marker-id sfo_jack_actuator.r.j.id
10 Steering Actuation Input Marker int/marker-id j_st_wheel_i_id The marker serves to apply virtual steering input for the computation of steering relevant values, such as scrub radius and caster trail.

In the simplest case, it is a marker on the steering wheel or pinion and its z-axis points along the rotation axis.

11 Steering Actuation Orientation Marker int/marker-id -1 This marker can be skipped (-1), if the marker in the previous field is oriented to the steering axis or rack. If this marker is specified, the direction will be assumed as the line between the markers.
12 Steering Actuation Mode int 6 This value defines the mode (1 = TX, 2 = TY, 4 = RX, 6 = RZ) of the steering input orientation. This is only used, if the second marker is not defined (=-1).

In case of two markers, a negative value indicates, that the two markers are swapped and the marker in #11 defines the application of the steering input.

13 Left Upper Marker on Steer-Axis int/marker-id mrk_upr_mnt.l.id If this marker is defined (!=-1), then it is used together with marker #2/#3 to compute the steer axis. Steer axis is assumed to be the line, that passes the two markers #2-#13 for the left and #3-#14 for the right side.

If this marker is not defined, the markers #2/#3s z-axis is used to assume the steer axis.

14 Right Upper Marker on Steer-Axis int/marker-id mrk_upr_mnt.r.id
15 Left Ground Level and Orientation Marker int/marker-id mrk_jack_cp.l.id This marker is used to measure the ground plane for each wheel. It supports ground plane inclination for scrub radius and caster trail computation.
16 Right Ground Level and Orientation Marker int/marker-id mrk_jack_cp.r.id

Vehicle Parameters Array

Index Name Assumed type/dimension Example Purpose
0 Vehicle End/role unsigned int ds_vehpar.veh_end.ival Provides information, if the axle is at the front end or read end of the vehicle.
1 Type of suspension unsigned int ds_vehpar.dif_mnt.ival Provides information, if the suspension is independent (0) (left/right don’t influence each other) or not (1).
2 Tire Static Loaded Radius (mm) Float [L] ds_vehpar.tire_slr.value Provides location and body to lock, if #4 is positive.

Provides direction to from z-axis, if #3 is not given (-1) and #4 is positive.

Provides reference point for direction, if #3 is defined (second marker).

3 Tire Vertical Spring Rate (N/mm) Float [F/L] ds_vehpar.tire_rate.value Provides location and body to lock, if #4 is negative.

Provides second point for direction, if defined (second marker).

4 Vehicle CG Height (mm) Float [L] ds_vehpar.cg_height.value Height of the center of gravity over ground.
5 Wheel Base (mm) Float [L] ds_vehpar.wheel_base.value Distance between front and rear wheel centers.
6 Front Braking Ratio (-) Float [-] ds_vehpar.front_brake.value The brake force distribution at the front wheels. A value of 1 indicates 100% braking on the front.
7 Front Drive Ratio (-) Float [-] ds_vehpar.front_drive.value The percentage engine power distributed to the front axle. A value of 1 indicates all power is sent to the front.
8 Axle Ratio (-) Float [-] ds_vehpar.axle_ratio.value The ratio between the angular velocity of the input gear to the angular velocity of the output gear. It is also commonly known as gear or speed ratio.
9 Vehicle Weight (N) Float [F] ds_vehpar.veh_weight.value Total mass of the vehicle.