Vehicle Setup using VeSyMA Motorsports

A key feature of the VeSyMA Motorsports library is the adjustments in the suspensions models which allows vehicle setup. These replicate the physical adjustments available on a race car, such as shims, preload adjusters and variable mounting positions. With 20+ adjustments available in a suspension model, a setup experiment is required to determine the combination of adjustments required to achieve a desired vehicle setup. In this blog post I’m going to talk about the adjustments available, how the setup tests are used to tune the adjustments and how the setup data is used in the VeSyMA Motorsports library.

Vehicle Adjustments

A good place for me to start is probably with what adjustments are available. This will of course depend on the type of suspension model you use but the complete list is:

  • Adjustment 1 is applied between the upper wishbone, track rod and upright to adjust camber angle.
  • Adjustment 2 changes the upper wishbone outer joint position to adjust caster angle.
  • Adjustment 3 alters the pushrod length to adjust ride height.
  • Adjustment 4 offsets the pushrod mount at the rocker.
  • Adjustment 5 changes the track rod length to adjust toe angle.
  • Adjustment 6 is applied between the track rod and upright to adjust toe angle, it also affects camber angle to a lesser extent.
  • Adjustment 7 changes the wheel offset in the upright to adjust the track.
  • Adjustment 8 is the torsion bar preload  to adjust the rocker angle.
  • Adjustment 9 is the spring preload used to adjust rocker angle, ride height or cross weight.
  • Adjustment 10 is the heave spring preload.
  • Adjustment 11 is applied between the upper wishbone and the chassis mount  to adjust caster, camber and toe.
  • Adjustment 12 changes the anti-roll bar drop link length to adjust anti-roll bar torque.
  • Adjustment 13 is applied between the lower wishbone and the chassis mount to adjust caster, camber and toe.
  • Adjustment 14 is a second adjustment between upper wishbone and upright, inboard of Adjustment 1, to adjust bump steer.
  • Adjustment 15 is a second adjustment between track rod and upright used to adjust bump steer.
  • Adjustment 16 is applied between the lower wishbone and upright to adjust mechanical (caster) trail.
  • Adjustment 17 is a rotational adjustment between the lower wishbone and the chassis mount, outboard of Adjustment 13.
  • Adjustment 18 alters the lower wishbone outer joint position  to adjust caster angle.
  • Adjustment 19 is applied between the track rod and chassis mount.
  • Adjustment 20 is a rotational adjustment between the upper wishbone and the chassis mount, outboard of Adjustment 11.
  • Adjustment 21 changes the panhard rod chassis mount.

Adjustments available in the quarter car suspension models for vehicle setup

Figure 1: Adjustments available in the quarter car suspension models

Setup Tests

The VeSyMA Motorsports library has two setup test options, either all of the adjustments can be made simultaneously or they can be performed in a specific sequence to follow a real setup routine. We refer to the first option as a dynamic setup test and the second as a sequential setup test. These different setup test options were created using different setup controller approaches.

For both types of setup test, the controllers use individual adjustment tuners, containing a PI controller, to vary the adjustment to achieve the target within a given tolerance. The setup controller also contains front and rear adjustment control records, which are linked to matching records in the vehicle’s suspension models. The adjustment control records in the controller are used to enable the desired dynamic adjustments for the setup test. When enabled, the control bus is used to pass the signals controlling the adjustment size . When an adjustment is not enabled, the fixed value for the adjustment is taken from the setup records in the suspension models. The setup controllers contain setup records which are linked to those in the vehicle, and use the values from here as the starting point for the adjustments being varied.

Dynamic Setup Test

In a dynamic setup test, the controller contains a tuner for each adjustment being made, as shown in figure 2  from the VeSyMA Motorsports library example Motorsports.Experiments.SetupTests.FormulaStudent.

Dynamic setup test and controller

Figure 2: Dynamic setup test performed on a Formula Student type vehicle and the setup controller used

For every adjustment enabled, you  need to provide a target. You may also need to change the tuners parameters for:

  • k_u_L/k_u_R the scale factors to change the direction of the adjustment.
  • K the proportional gain of the PI controller.
  • Ti  the integrator time constant of the PI controller .
  • y_max/y_min to set the realistic limits of the adjustment.
  • error_tolerance to define the acceptable error from the target.

At the end of a dynamic setup experiment the simulation log will report the final shim and preload values, as well as whether the adjustments have been successfully tuned to within the tolerance of the target by the end of the simulation.

Sequential Setup Test

Figure 3 shows the sequential setup test, Motorsports.Experiments.SetupTests.IndyCar. And as you can see the sequential setup test controller is a little more complex. It contains a sequence controller which controls the activation of the tuners based on a setup sequence. It  contains two records, a list of all the available tuners and an adjustment sequence.

Sequential setup test and controller

Figure 3: Sequential setup test performed on an IndyCar type vehicle and the setup controller used

In the sequence record there are 3 columns with a row for each setup step. The first column is the adjustment activated for tuning, the second is whether the controller should wait until the adjustment is tuned (i.e reached the target) before moving to the next step, and the third is whether the controller should deactivate the previous adjustment(s).

Before the sequence controller moves on to the next step the vehicle needs to be settled. The vehicleSettled component monitors the vertical wheel load, the change in these loads need to be below the specified tolerance for the vehicle to be considered settled.

The sequential setup controller contains sequential setup tuners, like that shown in Figure 4. These contain groups of the same individual adjustment tuners used in the dynamic setup controller. The Boolean activate inputs are supplied from sequence controller and become true when the tuner is active. The tuned outputs tell the sequence controller when the tuner has reached the target within the permitted tolerance.

Sequential setup test damper length tuner

Figure 4: Sequential setup test tuner changing adjustment 9 to achieve a damper length  and/or cross weight target, Motorsports.Experiments.SetupTests.Controllers.Tuners.DamperLengthCrossWeightTuner

When the sequence controller successfully reaches the end of the sequence, it will end the simulation and report to the simulation log as shown in Figure 5.

Sequential setup test report to simulation log

Figure 5: Sequential setup test report to simulation log


When your setup test has finished simulating it is important to verify that all the adjustments have been successfully tuned by checking the simulation log. There are a number of common reasons why a setup test isn’t successful:

  • If a measured metric diverges from the target, then the adjustment is probably being made in the wrong direction. This will probably be obvious if you look at the animation but it can be checked by plotting error.u1 and error.u2 from the individual adjustment tuner. So the corresponding scale factor k_u_ will need to be swapped from positive to negative or vice versa.
  • If there is significant oscillation in a measured metric (error.u1), the corresponding time constant Ti may need to be changed.
  • If the measured value (error.u1) changes too much, too little, very slowly or very fast, then corresponding gain K_ may need to be changed.
  • The setup test may need to be simulated for longer to tune all the adjustments.

There is further troubleshooting advice in the Motorsports Users Guide section Sequential Setup  Experiments > Troubleshooting.

Using the Setup Data

Once you have a successful setup experiment you’ll want to use the new setup adjustments determined in a vehicle model. As mentioned earlier the suspension models contain setup records where the fixed adjustment values are stored. There is a function for extracting the adjustments and initial conditions from the setup test results, Motorsports.Functions.extractFullSetup. This function extends the setup records used in suspension models, adding the adjustment, initial condition and solution selection values from the end of the setup experiment results. It also produces an extension of the vehicle’s free motion component, adding the vehicle height and attitude initial conditions. The setup records and motion component can simply be redeclared in the vehicle model to make use of the setup.

Written by: Hannah Hammond-Scott  – Senior Engineer

Please get in touch if you have any questions or have got a topic in mind that you would like us to write about. You can submit your questions / topics via: Tech Blog Questions / Topic Suggestion


Got a question? Just fill in this form and send it to us and we'll get back to you shortly.


© Copyright 2010-2024 Claytex Services Ltd All Rights Reserved

Log in with your credentials

Forgot your details?