Adams Car Package > Adams Car > Customizing Your Product > Example Four-Post Analysis

Example Four-Post Analysis

Although this is an Adams Car example, you can use the general concepts presented here to customize any template-based product.

■Building and Running an Analysis: Teaches the expert user how to build and run a full-vehicle analysis with the four-post test rig.

■Creating and Running a Macro: Introduces the concepts of creating and running a macro for the scenario given above.

Setting Up and Running an Analysis

Learn about building and running an analysis:

■Extracting the Files

■Test Description

■Test Rig Description

■Loading an Assembly with the Test Rig

■Running a Test

Extracting the Files

To get started with the example four-post test rig, extract the files located in the directory install_dir/acar/examples/fourpost (for example, C:\Program Files\MSC.Software\Adams\2024_1\acar\examples\fourpost). Then, use the file acar_build.cmd to create a site binary that contains the test rig and corresponding macros. To create a site binary file that contains the appropriate test rig and analysis macro files, you must perform the following steps:

1. Set the following environment variable to the location where your files are stored: MDI_ACAR_SITE.

■On Windows, it might look like: C:\Program Files\MSC.Software\Adams\2024_1\acar\examples\fourpost.

■On Linux, it might look like: /usr/MSC.Software/2024_1/acar/examples/fourpost.

Make sure you have write permissions within this directory.

2. Build the Adams Car site binary file as follows:

■On Windows: From the Start menu, point to Programs, point to Adams 2024.1, and then select Command Prompt. In the command window, type acar; cr-sitebin

■On Linux: Type adams2024_1; type acar, and then type cr-sitebin

Adams Car automatically executes acar_build.cmd and builds all the appropriate entities and libraries into a site version of the Adams binary file.

3. To run the site binary file, follow the steps outlined above, but replace the cr-sitebin command with ru-site.

Test Description

You can use the four-post test rig to investigate the vertical dynamics of the full vehicle and its suspension systems. You can then plot the time-based results and study them in the frequency domain to understand the various ride modes and their respective damping levels. The investigation will also help you learn more about the influences of the vehicle's vertical dynamics effects on handling behavior by studying the system's dynamic responses, which includes:

■Front-to-rear modal balance

■Suspension-to-body transfer function gain and phase

■Suspension-to-tire transfer function gain and phase

■Tire contact patch vertical load variation

The test involves assembling a standard full-vehicle model to a four-post test rig. The test rig is defined by four parts representing the tire pads that support the vehicle. The tire pads are constrained to move only in the vertical direction and a displacement actuator, or motion controller, controls their vertical motion.

The only constraint between the pads and the vehicle's tires is the friction of the tires.

Not all tire models have adequate zero speed modeling for being used with the four-post rig test: a rolling tire acts as a damper because the force response depends on tire slip speeds; a non-rolling tire should act as a spring and forces must depend on tire deflection.

All Adams Tire tire models support the four-post rig test when used in transient mode. For most tire models this means that the USE_MODE in the tire property file must be larger then 10. The exceptions are:

■UA-Tire, USE_MODE must be set to 2

■The Basic and Enhanced tire model property files must specify a RELAXATION_LENGTH larger then zero.

■FTire is in transient mode by default.

An analytical function controls the vertical actuators. Analytical functions also describe the displacement profile of the actuator in the time domain and they are limited to constant amplitude sinusoidal input that sweeps over a predetermined frequency range in a set amount of time. When using the analytical function control, users can use four excitation modes:

■Heave - All tire pads move vertically in phase.

■Pitch - The front tire pads move 180o out of phase with the rear tire pads.

■Roll - The left tire pads move 180o out of phase with the right tire pads.

■Warp - The left-front and right-rear tire pads move 180o out of phase with the right-front and left-rear pads.

Test Rig Description

We created the test rig __acme_4PostRig in Adams Car Template Builder. Its major role is analysis and it contains four general parts for each of the pads, and four actuators for each of the vertical translation joints on each pad. The location of all of the pads and their respective constraints, such as actuators, are parameterized in the ground plane (x and y) to a wheel-center location communicator that comes from the suspension systems. The vertical location is parameterized to the z location of the marker std_tire_ref. The marker std_tire_ref has its z height set automatically during the assembly process so that it represents the average tire contact patch height of the vehicle.

Four-Post Test Rig

Loading an Assembly with the Test Rig

Once you have successfully built the site binary file and started the site version of Adams Car, you must open the assembly that we have also provided in the examples directory (cdb.cdb) mentioned in Extracting the Files.

If you have not already added the database to your .acar.cfg file, you should do the following:

■From the Tools menu, point to Database Management, and then select Add to Session.

Open the assembly contained in the cdb database as follows:

1. From the File menu, point to Open, and then select Assembly.

2. Open the MDI_Vehicle_4PostRig.asy.

You can also create a new assembly by doing the following:

1. From the File menu, point to New, and then select Full-Vehicle Assembly.

2. Select the appropriate subsystem files.

3. Change the vehicle test rig from __MDI_SDI_TESTRIG to __acme_4PostRig.

4. Select OK.

Running a Test

You should have a full-vehicle assembly mounted to the four-post test rig as shown next.

Use the Command Navigator to submit an analysis using the auto-generated dialog box:

1. To open the Command Navigator, from the Tools menu, select Command Navigator.

2. To run a full-vehicle analysis with the four-post test rig, you must select acme -> analysis -> full_vehicle -> four_post -> submit (double-click).

Adams Car displays the following dialog box (without the values, which we added for your convenience):

3. After the analysis is completed, review the results using the animation and post-processing tools.

Creating and Running a Macro

This topic introduces the concepts of creating and running a macro. While many of the code excerpts are contained in this topic, we also included the appropriate files in the examples directory (install_dir\acar\examples\fourpost\analysis\macros).

You can modify the macro in this directory and then rebuild it in to your Adams Car site binary file. This allows you to make changes and experiment with macro changes.

■User-Input Parameters

■About the Simulation Process

■Creating the Macro

■Adding the Four-Post Analysis Macro to a Binary

■Testing the New Analysis Macro

■Customizing the Four-Post Analysis Dialog Box

User-Input Parameters

Analysis input parameters are the values that you enter to control a simulation or some other event in the template-based products. Analysis input parameters can be grouped into two categories:

■Parameters common to all analyses:

■Output prefix

■End time

■Number of steps

■Type of analysis (interactive, background)

■Analysis log file (yes, no)

■Parameters specific to this four-post test rig. You use the four-post simulation input parameters to define the boundary conditions of the desired vertical excitation test. The parameters are:

■Peak displacement

■Displacement units (such as m, mm, inch)

■Frequency range (units hardcoded to Hz)

■Excitation mode (heave, pitch, roll, or warp)

About the Simulation Process

The following steps outline the simulation process. The simulation process for the vehicle and test rig is similar to any other suspension or full-vehicle simulation.

The simulation process steps are:

1. Perform a check to ensure that the assembly has the correct test rig.

2. Check if an analysis of the same name already exists.

3. Read in the property files.

4. Assign the z location of the marker std_tire_ref based on the average contact patch location of all of the tires to the four wheel pads.

5. Modify the analytical functions of the actuator (jms_left_front_actuator, jms_right_front_actuator, and so on), according to the user-input data:

Based on the analytical drive signal, you must assign the following functions to each actuator:

Left Front - LF_phase*Peak_Amplitude*sin(1/2*360D*Freq_Range/End_Time*Time**2)

Right Front - RF_phase*Peak_Amplitude*sin(1/2*360D*Freq_Range/End_Time*Time**2)

Left Rear - LR_phase*Peak_Amplitude*sin(1/2*360D*Freq_Range/End_Time*Time**2)

Right Rear - RR_phase*Peak_Amplitude*sin(1/2*360D*Freq_Range/End_Time*Time**2)

where the following values are assigned to the phase variables in the function:

Heave Mode - LF_Phase, RF_Phase, LR_Phase, RR_Phase = 1.0

Pitch Mode - LF_Phase, RF_Phase = 1.0 & LR_Phase, RR_Phase = -1.0

Roll Mode - LF_Phase, LR_Phase = 1.0 & RF_Phase, RR_Phase = -1.0

Warp Mode - LF_Phase, RR_Phase = 1.0 & RF_Phase, LR_Phase = -1.0

The simulation process involves submitting the simulation to Adams Solver using a process similar to the full-vehicle simulation process. The simulation needs:

■One static equilibrium

■An initial velocity of 0.0

■A dynamic simulation equal to the end time (specified by user)

To avoid aliasing of the input during the simulation, users should set the maximum time step that the integrator is allowed to take (HMAX argument on the integrator) to at least 1/10 of the maximum frequency range. For example, if the frequency range you set is 20 Hz, then the HMAX should be 1/10*1/20 = 1/200 (0.005).

Creating the Macro

This four-post vertical excitation example provides instructions to help you create your own macro based on a given user scenario. The objective of the analysis is described in Test Description.

Creating the macro involves the following:

■Defining Parameters

■Handling Errors

■Reading Property Files

■Setting Up the Assembly and Test Rig

■Submitting the Analysis

■Logging the Analysis Results

■Finishing up the Macro

Defining Parameters

We determined the parameters for the four-post analysis macro from User-Input Parameters (for a description of the parameters whose values are important for the success of the four-post simulation, see the table Parameter Descriptions):

! $assembly:t=model

! $output_prefix:t=string

! $comment:t=string:d=""

! $end_time:t=real:gt=0

! $number_of_steps:t=integer:gt=0

! $analysis_mode:t=list(interactive,graphical,background):d=interactive

! $peak_displacement:t=real:gt=0

! $units:t=list(mm):d=mm

! $frequency_range:t=real:gt=0

! $excitation_mode:t=list(heave,pitch,roll,warp):d=heave

! $load_results:t=list(yes,no):u=yes

! $log_file:t=list(yes,no):u=yes

! $error_variable:t=variable:d=.ACAR.variables.errorFlag

Parameter Descriptions

Parameter name:	Description:
assembly	String value that specifies an existing model. t=model; t specifies type; examples could include real, integer, and so on.
output_prefix	String value that specifies the name of the analysis. This name is used to write the analysis files (.adm, .acf, and so on) to the file system and also when the solver files are read back into Adams Car.
comment	Stores comments in the Adams dataset, d=" "; d specifies default, which is an empty string.
end_time	Real value that tells Adams Solver the end time of the four-post analysis. gt=0; gt specifies greater than.
number_of_steps	Integer value that tells Adams Solver the number of output steps.
analysis_mode	String value that specifies the mode of the analysis. The three valid modes are interactive, background, or graphical; the list specifies the valid options.
peak_displacement	Indicates the maximum amplitude of the shaker pad vertical displacement.
units	Hardcoded to millimeters for tutorial, but you can expand it to include other units.
frequency_range	Real value indicating the frequency range of the actuator motion functions.
excitation_mode	List value that indicates the direction of the shaker pad motions.
load_results	Specifies whether to load the results once Adams Solver has finished the analysis. The default is yes.
log_file	Indicates if Adams Car should generate an analysis log file.

Handling Errors

With this macro, users must perform the four-post analysis with the .__acme_4PostRig test rig described in Test Rig Description. The assembly and test rig perform actions based on the elements that exist in the .__acme_4PostRig test rig. Therefore, as part of error checking, the macro checks for the correct test rig. For a description of the setup of the assembly and test rig, see About the Simulation Process.

In addition to verifying that the user is using the correct test rig, the macro also checks if the analysis name is unique for this assembly. Notice that we use indenting and comments to make the macro easier to read; as with all programming languages, this is a good practice to get into.

variable set variable_name=$error_variable integer=0

!---- Check to ensure the assembly has the proper test rig ----
if condition=($assembly.original_testrig_name != "__acme_4PostRig")

acar toolkit warning &

warning="Analysis cannot be submitted!", &

"The assembly does not have the proper testrig. This analysis only", &

"works with assemblies using the '__acme_4PostRig' testrig."

variable set variable_name=$error_variable integer=1

return

end

!---- Check if analysis name already exists ----

if condition=(db_exists("$assembly.$'output_prefix'_fourpost"))

if condition=(alert("question","An analysis called \'$'output_prefix'_fourpost\' &

already exists. Overwrite it?","Yes","No","",2) == 2)

variable set variable_name=$error_variable integer=1

return

end

Reading Property Files

After the macro validates the assembly, it reads in and assigns the property file information, using the following code fragment:

!---- Clear out message window ----

acar toolkit message &

message=" " append=no display=no closeable=yes echo_to_logfile=no

!---- Read property files ----

acar toolkit read property_files &

assembly=$assembly &

verbose=yes &

error_variable=$error_variable

if condition=($error_variable != 0)

return

end

Setting Up the Assembly and Test Rig

In this section of the macro, you modify elements of the test rig and assembly to match the values and information entered by the user.

The code fragments for the four-post setup are shown next, with a description for each section, as needed.

!---- Set up the assembly for the maneuver ----

acar toolkit message &

message="Setting up vehicle assembly for four-post shaker..."

You must assign the tire reference markers to the appropriate test pad on the shaker table. The naming conventions for the communicator variables for the reference markers are considered fixed, in that the macro looks for the communicators known to exist in the four-post test rig. Note that the setup of the tire reference markers only occurs once for a particular assembly. If you use the same assembly for multiple four-post analyses, the initial setup will be valid for each analysis.

For each wheel, the tire reference marker is assigned to a shaker pad. The first step is to find each tire in the full-vehicle assembly. The reassignment occurs through an output communicator in the test rig. The communicator holds the name of the part on the shaker pad where you should attach the tire reference marker.

if condition=(!db_exists("$assembly.fourpostSetup"))

!--- Parameterize the 4post pad height to the global road height marker just previously adjusted ---

marker modify &

marker_name=$assembly.testrig.ground.std_tire_ref &

location=($assembly.ground.std_tire_ref.location) &

relative_to=$assembly.testrig.ground

variable set variable=$_self.frontWheel &

object_value=(eval(subsystem_lookup($assembly,"wheel","front")))

variable set variable=$_self.leftFrontWheel &

object_value=(eval(db_filter_name(db_children($_self.frontWheel[1],"ac_tire"),"til_*")))

variable set variable=$_self.rightFrontWheel &

object_value=(eval(db_filter_name(db_children($_self.frontWheel[1],"ac_tire"),"tir_*")))

variable set variable=$_self.rearWheel &

object_value=(eval(subsystem_lookup($assembly,"wheel","rear")))

variable set variable=$_self.leftRearWheel &

object_value=(eval(db_filter_name(db_children($_self.rearWheel[1],"ac_tire"),"til_*")))

variable set variable=$_self.rightRearWheel &

object_value=(eval(db_filter_name(db_children($_self.rearWheel[1],"ac_tire"),"tir_*")))

marker modify &

marker_name=(eval($_self.leftFrontWheel.object_value.ref_marker.object_value)) &

new_marker_name=

(eval($assembly.testrig.col_front_pad_mount[1]//"."//$_self.leftFrontWheel.object_value.ref_marker.object_value.name))

marker modify &

marker_name=(eval($_self.rightFrontWheel.object_value.ref_marker.object_value)) &

new_marker_name=(eval($assembly.testrig.cor_front_pad_mount[1]//

"."//$_self.rightFrontWheel.object_value.ref_marker.object_value.name))

marker modify &

marker_name=(eval($_self.leftRearWheel.object_value.ref_marker.object_value)) &

new_marker_name=(eval($assembly.testrig.col_rear_pad_mount[1]//"."//$_self.leftRearWheel.object_value.ref_marker.object_value.name))

marker modify &

marker_name=(eval($_self.rightRearWheel.object_value.ref_marker.object_value)) &

new_marker_name=(eval($assembly.testrig.cor_rear_pad_mount[1]//"."//$_self.rightRearWheel.object_value.ref_marker.object_value.name))

variable set variable=$assembly.fourpostSetup &

integer_value=1

end

You must reset the motion actuators driving the displacement of the shaker pads for each individual four-post analysis. This is in contrast to the tire reference marker setup, described in the previous paragraphs, which needs to occur only once for a particular assembly, and remains valid for all successive four-post analyses.

Each of the four shaker pads will have the same magnitude of motion, but a specific excitation mode will determine the direction of the motion:

■Heave mode - All four shaker pads move in the same direction.

■Pitch mode - The front and rear tires move in opposite directions.

■Roll mode - The left and right tires move in opposite directions.

■Warp mode - The left front and right rear tires move opposite to the direction traveled by the right front and left rear tires.

You set the different excitation modes by specifying a 1 or -1 multiplier at the beginning of the actuator function definition, as shown next:

!---- Assign actuator functions based on excitation mode ----

!-Heave Excitation

if condition=("$excitation_mode" == "heave")