Adams Driveline Mdr3 Help

Welcome to Adams/Driveline
2 Adams/Driveline
About Adams/Driveline
You can use Adams/Driveline, part of the MD Adam R3 suite of software, stand alone or as a plugin
for Adams/Car. You use Adams/Driveline to model drivelines: to create virtual prototypes of driveline
subsystems and analyze the virtual prototypes much like you would analyze the physical prototypes.
Using Adams/Driveline, you can quickly create assemblies of suspensions and full vehicles, including
driveline components, and then analyze them to understand their performance and behavior.
You create assemblies by defining vehicle subsystems, such as front and rearsuspensions, steering gears,
anti-roll bars, and bodies. You base these subsystems on their corresponding Adams/Driveline templates.
For example, Adams/Driveline includes templates for engine, gearbox, prop shafts, and differentials.
If you have expert-user access, you can also base your subsystems on custom templates that you create
using the Adams/Driveline Template Builder.
When you analyze an assembly, Adams/Driveline applies the analysis inputs that you specify. For
example, for a full-vehicle analysis you can specify inputs to:
Apply a specific torque to your driveline model (impulse, step, ramp, loadcase, and so on).
Define a different friction coefficient for different wheels in your model.
Define a slope of your road to study the performance of your driveline model.
Based on the analysis results, you can quickly alter the driveline geometry andanalyze the driveline again
to evaluate the effects of the alterations.
Once you complete the analysis of your model, you can share your work with others. You can also print
plots of the vehicle dynamic responses. In addition, you can access other users models without
overwriting their data.
Benefits of Adams/Driveline
Adams/Driveline enables you to work faster and smarter, letting you have more time to study and
understand how design changes affect vehicle performance.
Using Adams/Driveline you can:
Explore the performance of your design and refine your design before building and testing a
physical prototype.
Analyze design changes much faster and at a lower cost than physical prototype testing would
require. For example, you can change springs with a few mouse clicks instead of waiting for a
mechanic to install new ones in your physical prototype before re-evaluating your design.
Vary the kinds of analyses faster and more easily than if you had to modify instrumentation, test
fixtures, and test procedures.
Work in a more secure environment without the fear of losing data from instrument failure or
losing testing time because of poor weather conditions.
Run analyses and what-if scenarios without the dangers associated with physical testing.
Learning the Basics
6 Adams/Driveline
Starting Adams/Driveline
In the Windows environment, you start Adams/Driveline from the Start button. In the UNIX environment, you
start Adams/Driveline from the Adams Toolbar.
This topic describes how you start the two Adams/Driveline interface modes, standard interface or template
builder.
Adams/Driveline Standard Interface

Adams/Driveline has two interface modes: Standard Interface and Template Builder. This topic explains how
to start Adams/Driveline Standard Interface.
To start in the Windows environment:
1. From the Stat menu, point to Programs, point to MSC.Software, point to MD Adams R3, point
to ACar, and then select Adams - Driveline.
The Welcome dialog box appears on top of the Adams/Driveline main window.
2. Do one of the following:
If the Welcome dialog box contains the options Standard Interface and Template Builder,
select Standard Interface, and then select OK.
If the Welcome dialog box does not contain any options, then Adams/Driveline is already
configured to run in standard-interface mode. Select OK.
The Adams/Driveline Standard Interface appears.

To start in the UNIX environment:
1. At the command prompt, enter the command to start the Adams Toolbar, and then press Enter.
The standard command that MSC.Software provides is adamsmdx, where x is the version
number, for example adamsmdr3.
The Adams Toolbar appears.
2. Select the Adams/Driveline tool .
If the Welcome dialog box contains the options Standard Interface and Template Builder,
select Standard Interface, and then select OK.
If the Welcome dialog box does not contain any options, then Adams/Driveline is already
configured to run in standard mode. Select OK.
The Adams/Driveline Standard Interface appears.
Learning the Basics
Adams/Driveline Template Builder

Adams/Driveline has two interface modes: Standard Interface and Template Builder. This topic explains how
to start Adams/Driveline Template Builder.
Before you start Adams/Driveline Template Builder, make sure that your private configuration file, .acar.cfg,
shows that you have expert-user access. Your private configuration file is located in your home directory.
To check user access:
1. In a text editor, such as jot or notepad, open .acar.cfg.
2. Verify that the following line appears as shown:
ENVIRONMENT MDI_ACAR_USERMODE EXPERT
This line sets the user mode for the Adams/Driveline session.
To start in the Windows environment:
1. From the Start menu, point to Programs, point to MSC.Software, point to MD Adams R3,
point to ACar, and then select Adams - Car.
2. Select Template Builder.
3. Select OK.
The Adams/Driveline Template Builder window appears.
To start in the UNIX environment:
1. At the command prompt, enter the command to start the Adams Toolbar, and then press Enter.
The standard command that MSC.Software provides is adamsmdx, where x is the version
number, for example adamsmdr3.
The Adams Toolbar appears.
2. Select the Adams/Driveline tool .
3. Select Template Builder.
4. Select OK.
The Adams/Driveline Template Builder window appears.
8 Adams/Car
Interfaces and Access

You can use Adams/Car through two different interfaces depending on your user access.
Interface Modes
Adams/Car has two interface modes:
Standard Interface - You use it when working with existing templates to create and analyze
assemblies of suspensions and full vehicles. Users with standard and expert access can use the
Standard Interface.
Template Builder - If you have expert-user access, you use the Template Builder to create new
templates for use in the Standard Interface.
When you create a new component in the Template Builder, your product automatically adds a
prefix based on the entity type and the symmetry. Your product uses a naming convention to let
you easily determine an entitys type from the entitys name. Learn about the naming convention
and see a table that lists the prefixes of various entities. If you have expert-user access, you use
the Template Builder to create new templates for use in the Standard Interface.
Using the Template Builder, you can assemble standard components, such as springs, parts, and
bushings, to define the topology of your system, such as a suspension or a single valvetrain in an
engine.
To switch between modes:
Do one of the following:
From the Tools menu, select [Product Name] Standard Interface or select [Product Name]
Template Builder.
Press F9.
About User Access

Your access to the standard-interface or template-builder mode depends on your assigned user access:
Standard user - Standard users do not have access to the Template Builder, only to the Standard
Interface. Therefore, the standard user cannot make topological modifications to templates, but
can operate on subsystems, varying design parametrics and analysis inputs.
Expert user - Expert users have access to modeling capabilities available in theTemplate
Builder. Therefore, expert users can open templates and modify their topological information, as
well as create new templates.
If you are an expert user, when you launch your Adams product, it prompts you to select either
Standard Interface or Template Builder.
Learning the Basics
Setting User Access

You use the MDI_ACAR_USERMODE keyword in your private configuration file to set your user
access, which determine you access to the Template Builder and other development tools. Your private
configuration file is found at $HOME/.acar.cfg, where $HOME is the location of your home directory.
Note:
The private configuration file is not located in the installation directory. Never change the
acar.cfg file located in the installation
You can set USERMODE to:

STANDARD - User can only access the Standard Interface.
EXPERT - User can access the Template Builder and create and modify templates. User can
access the Template Builder and other development tools that are located under the Tools menu.
Expert users can use the MDI_ACAR_PLUS_AVIEW keyword in the private configuration file
to access Adams/View. Learn about accessing Adams/View.
To change the value of this keyword, you must edit the private configuration file (.acar.cfg) using a text
editor and modify the corresponding string. The following gives you expert access:
! Desired user mode (standard/expert)
When you start a new session, your template-based product reflects the changes to the private
configuration file.
10 Adams/Car
Navigating Through a Modeling Database

The Database Navigator helps you view, select, and modify objects in your modeling database.
Learn more:
About the Database Navigator
Viewing Objects
Showing, Hiding, and Selecting Objects in the Database Navigator
Managing the Select List
Filtering Objects in the Database Navigator
Sorting Objects in the Database Navigator
Setting Highlighting in the Database Navigator
Changing Objects
Setting Appearance of Objects Through the Database Navigator
Renaming Objects Through the Database Navigator
Adding Comments Through the Database Navigator
Viewing Information About Your Model

Viewing Model Topology Through the Database Navigator
Viewing the Associativity of Objects
Viewing Object Information Through the Database Navigator
Viewing Model Topology Map Through Information Window
About the Database Navigator

The Database Navigator has several modes in which you can display object information. It can be set to
just let you browse for objects or you can set it to rename objects, view information about the objects,
such as view how the object relates to other objects, and view dependencies.
The Database Navigator only displays the types of objects that are appropriate for the command you are
executing. For example, if you are renaming a model, it only displays models in your database. On the
other hand, if you are searching for any modeling object in the database, it displays all types of modeling
objects. You can also set a filter for the types of objects that the Database Navigator displays.
The Database Navigator shows objects in their database hierarchy. The following figure shows the
Database Navigator with the top-level modeling objects in a small database that contains one model,
Learning the Basics
model_1 . These objects do not have parents. Double-click the name of a model, in this case model_1,
to find all the objects belonging to that model.
To display the Database Navigator, do any of the following:

From the Tools menu, select Database Navigator.
Execute an editing command, such as Modify, from the Edit menu when no object is currently
selected.
Request to view information about an object using the Info command on the Edit pop-up menu.
Browse for the name of an object to enter in a dialog box using the Browse command.
Your template-based product displays the Database Navigator.
Showing, Hiding, and Selecting Objects in the Database

Navigator
In the Database Navigator treelist,a plus (+) in front of an object indicates that the object has children
below it but they are hidden. A minus (-) indicates that all objects immediately below the object are
displayed.
11
12 Adams/Car
To show or hide objects below a single object:

Double-click an object with a plus or minus by it.
To expand or collapse all objects by one level:
In the lower right corner of the navigator window, select the + or - button.
To hide all objects:
In the lower right corner of the navigator window, select the - button.
You can use the Database Navigator to select any object in the database. You can also select more than
one object to complete a command. You can create a list of selected objects on which to perform options
by choosing Select List from the pull down menu at the top of the Database Navigator.
To select a single object:
In the tree list, click the object and select OK. If the Database Navigator is not in multi-select
mode, you can also double-click the object to select it.
To use the mouse to select a continuous set of objects:
1. In the tree list, drag the mouse over the objects you want to select or click on one object, hold
down the Shift key, and click the last object in the set. All objects between the two selected
objects are highlighted.
2. Select OK.
To use the Up and Down arrow keys to select a continuous set of objects:
1. In the tree list, click on the first object, hold down the Shift key, and then use the Up or Down
arrows to select a block of objects.
2. Select OK.
To select a noncontinuous set of objects:
1. In the tree list, click on an object, hold down the Ctrl key, and click on the individual objects you
want to select.
2. Select OK.
To clear any selection in the tree list:
Hold down the Ctrl key and click the selected object to clear its highlighting.
Managing the Select List

You can use the Database Navigator to view objects you've selected using the procedures explained in
Showing, Hiding, and Selecting Objects in the Database Navigator. The list of objects is called the Select
list. You can also add and remove objects from the Select list.
Learning the Basics
To view the select list:

From the pull-down menu, select Select List.
The selected objects appear in the text box to the right.
To add objects to a select list:
1. From the pull-down menu, select Select List.
2. From the tree list or main window, select the objects to be on the select list as explained in the
previous section.
3. Select Add.
4. Select Apply.
To remove objects from the select list:
2. From the list that appears on the right, select the objects to be removed.
3. Select Remove.
4. Select Apply.
To clear all objects from the select list:
2. Select Clear.
3. Select Apply.
Filtering Objects in the Database Navigator

You can filter the types and names of objects that you want displayed in the Database Navigator to
narrow the display to exactly what you want or to broaden the display using wildcards. For example, you
can narrow the display to only parts or broaden the display to include all objects that begin with a
particular character, such as an h.
To set the filter of the Database Navigator:
1. In the Filter text box, enter the name of the objects that you want to display. Type any wildcards
that you want to include.
2. From the pull-down menu, select the type of object or objects that you want to display in the
Database Navigator. To select from all the different object types in the modeling database, select
Browse.
3. Select OK.
13
14 Adams/Car
Sorting Objects in the Database Navigator

You can sort objects in the Database Navigator by their name or type, such as parts or geometry. You can
also select to not sort the object so the objects appear in the Database Navigator in the order they are
stored in the modeling database.
Note that sorting by name can be slow for objects with very long names. Setting no sorting is the fastest
way to see objects.
To sort objects in the Database Navigator:
At the bottom of the Database Navigator, from the Sort by pull-down menu, select how you'd
like the objects sorted.
Setting Highlighting in the Database Navigator

You can set up the Database Navigator so that whenever you select an object in the tree list, it also appears
selected in the main window and the reverse. Highlighting is off by default.
To toggle highlighting:
Select Highlighting.
Setting Appearance of Objects Through the Database

Navigator
Through the Database Navigator, you can set how individual, types of objects, and children of objects
appear in your template-based product.
You can set:
Visibility of the object and of its name on the screen.
Color, line style, line width and transparency of the object. For example, you can set the color of
the objects outline or its name.
Size of the screen icons that represent the object in your model. Note that these changes take
precedence over the size you specify globally for the modeling database.
State of the object during a simulation: active or inactive.
To set the appearance of objects:

1. Select an object from the Database Navigator tree list.
2. Use the options in the dialog box to set the appearance of the object. To inherit an attribute from
a parent of the object, select None from any of the pull-down menus.
Learning the Basics
Tip:
For transparency, the higher the value, the more transparent the object is, allowing
other objects to show through. The lower the value, the more opaque the object is,
covering other objects. However, setting the transparency of objects can have a
negative impact on graphical performance if you are using a graphics card without
hardware acceleration for OpenGL. Instead of setting an objects transparency,
consider setting the objects render mode to wireframe.
3. To set the scope of the appearance changes, you can select either:
Object - Only apply to the selected object.
Siblings - Apply changes to all objects of the same type that are children of the parent of the
selected object.
All - Apply changes to objects matching the filter you set in the Filter text box.
4. Select Apply.
Renaming Objects Through the Database Navigator

You can use the Database Navigator to rename any object.
To rename an object:
1. From the Database Navigator pull-down menu, select Rename.
2. From the tree list, select the object to rename.
3. In the text box that appears to the right, type a new name for the object.
4. Select Apply.
Adding Comments Through the Database Navigator

You can use the Database Navigator to associate comments with any object in the modeling database.
To associate comments with an object:
1. From the Database Navigator pull-down menu, select Comments.
2. From the tree list or main window, select an object.
3. In the text box that appears to the right, type or modify the comments associated with the object.
4. Select Apply.
To save the comments in a file:
Select Save to File.
15
16 Adams/Car
Viewing Model Topology Through the Database Navigator

The model topology map displays information about the parts in your model and determines what
constraints are owned by the model and what parts the constraints connect. The information appears in
the window on the right of the Database Navigator.
You can view the part connection information in the following ways:
By part - Lists each part in the model, along with the parts it is connected to and what
constraints or forces are affecting it.
By connections - Displays each constraint and force with the parts they connect and act on. Also
displays any unconnected parts.
Graphically - Displays a representation of the selected part and shows its connections to other
parts.
To display model topology of parts and connections:

From the Database Navigator pull-down menu, select Topology by Parts or Topology by
Constraints.
To graphically view the topology of parts:
1. From the Database Navigator pull-down menu, select Graphical Topology.
Viewing the Associativity of Objects

You can use the Database Navigator to display the objects that a selected object uses. For example, you
can select a joint in the tree list to show the Iand J markers that the joint uses. You can also select to view
the objects that use the selected object.
To view the associativity of objects:
1. From the Database Navigator pull-down menu, select Associativity.
2. Set the associativity:
To show the objects that the selected object uses, select Uses
To show the objects that use the selected object, select Is Used By.

The objects associated with the selected object appear in the text box to the right.
To set up automatic navigation of the objects:
Select Auto Navigate.
Learning the Basics
To save the current associativity information to a file:

Viewing Object Information Through Database Navigator

You can use the Database Navigator just as you would use the Information window to display information
about an object.
To display object information:
1. From the Database Navigator pull-down menu, select Information.
The information about the object appears in the window to the right.
To save the information to a file:
To return to the information about a previous object:
Select .
Viewing Model Topology Map Through Information Window

The model topology map displays information about the parts in your model and determines what
constraints are owned by the model and what parts the constraints connect. The information appears in
the Information window.
You can view the part connection information in two ways:
By part - Lists each part in the model, along with the parts it is connected to and what
constraints or forces are affecting it.
By connections - Displays each constraint and force with the parts they connect and act on. Also
displays any unconnected parts.
To display model topology by parts, do one of the following:

From the Tools menu, select Model Topology Map.
In your template-based product, on the status toolbar, from the Information tool stack, select
the Model Topology by Parts tool
17
18 Adams/Car
To display model topology by connections:

On the status toolbar, from the Information tool stack, select the Model Topology by
Constraints tool
Learning the Basics
Working with the Information Window

Your template-based product uses the Information window to display many different types of
information about your model, simulation, and so on. In addition to just viewing information about your
model, you can perform a variety of operations in the Information window. For example, you can display
additional information about the current object's parent or child, print the information, display
information about a different object in the database, and more.
Displaying Information
Displaying Object Information and Accessing the Information Window
Displaying Parent and Children Information
Displaying an Object's Modify Dialog Box
Managing Information
Clearing the Information Window
Saving Information in the Information Window
Displaying a Text File in the Information Window
Copying Text in the Information Window
Setting the Information Mode
Displaying Object Information and Accessing Information

Window
You can display information about each object in your modelling database, including parts, geometry,
motion, and markers. Learn about markers.
You can view the information about an object currently on the screen or any object in the database,
including the main window or dialog boxes.
When you display information about the objects in your modeling database, your template-based product
displays information specific to that type of object. For example, when you display information about a
rigid body in your model, your template-based product displays information about its material content,
inertial properties, initial conditions, orientation, velocity, and more. When you display information
about a motion, your template-based product displays information about the type of motion it is, its
function, and time derivative.
To display information about a modeling object displayed on the screen:
Right-click the object on the screen, and then select Info.
19
20 Adams/Car
Tip:
You may want to zoom in on theobject on the screen to more easily place thecursor
over just that object.
Information about the object appears in the Information window.

To use the Database Navigator to display information about objects in the Information
window:
1. On the status toolbar, select the Info tool
from the Information tool stack.
The Database Navigator appears.
2. Select the object about which you want to display information. Learn about selecting objects.
3. Select OK.
The information window appears.
To display object information once you've displayed the Information window, do one of
the following:
In the text box at the top of the Information window, enter the name of the object, and then select
Apply.
If the object name already appears in the Information window, place the text cursor in the name
of the object, and then select Apply.
Displaying Parent and Children Information

Each object in the database has an object that owns it, called its parent, and many objects own other
objects, called their children. The top-level objects in the database are models, plots, and interface
objects, called gui objects. These objects do not have parents. You can display information about the
parent or children of the object currently displayed in the Information window.
If an object has a parent, the type of parent it has appears in the Information window under the heading
Parent Type and the name of the parent is placed in front of the name of the object in the Object Name
heading. For example, for the part LINK_2, its parent type and name appear in the Information window,
as shown next:
To display an object's children:

In the Information window, select Children.
Learning the Basics
To display an object's parent, do one of the following:

In the Information window, select Parent.
In the Information window, place the text cursor in the name of the parent and select Apply.
Displaying an Object's Modify Dialog Box from the

Information Window
When information about an object is displayed in the Information window, you can access that object's
modify dialog box so you can modify the object.
To access an object's modify dialog box from the Information window:
In the Information window, place the text cursor in the name of the object and select Modify.
Clearing the Information Window

Each time you request information in the Information window, your template-based product adds the
information to the bottom of the Information window without removing the current information. You can
remove all current information.
To clear the Information window:
In the Information window, select Clear.
Saving Information in the Information Window

You can save the contents of the Information window to a text file.
To save the contents of the information to a text file:
1. In the Information window, select Save to File.
The Select File dialog box appears.
2. Select the directory in which you want to place the file.
3. In the File Name text box, enter the file name.
4. Select Open.
Displaying a Text File in the Information Window

You can display any text file in the Information window. You will find this helpful if you want to display
an information file that you saved or you are creating a demonstration of your model using a command
file and you want to display information about a particular object or aspect of the demonstration.
21
22 Adams/Car
To display a text file when the Information window is already displayed:

1. In the Information window, select Read from File. dialog box appears.
2. Select the directory in which you want to place the file.
3. Highlight the file that you want to open in the list, or type the file name in the File Name text box.
4. Select Open.
To display a text file when the Information window is not displayed:
1. On the Tools menu, select Show File.
The Info Window Read dialog box appears.
2. In the File Name text box, you can either:
Enter the name of the file.
Browse for a file: right-click the File Name text box, and then select Browse to display the
File Selection dialog box.
3. Select OK.
The Information window appears with the text of the file as its content.
Copying Text in the Information Window

You can copy any text in the Information window for use in another window, dialog box, or application.
You cannot paste or delete any text in the window.
To copy text in the Information window:
1. Highlight the text that you want to copy.
2. Right-click the Information window and select Copy.
Setting the Information Mode

By default, the Information window displays only a part's parent and type. To display more information
about the part, you can turn on verbose mode. When you turn on verbose mode, the Information window
displays the children of the object, its geometry, whether or not comments are associated with it, and its
attributes, such as its color and visibility.
To turn on verbose mode:
Select the Verbose check box.
Using Wildcards
You can use wildcards to narrow any search, set the type of information displayed in a window, such as
the Database Navigator or the log file, or specify a name of an object in a dialog box.
Learning the Basics
This Character:
* (asterisk)
Zero or more characters
Any single character
[ab]
Any one of the characters in the brackets
[^AB]
Any character other thanthe characters following the caret symbol (^) in the
brackets
[a-c]
Any one character in a range enclosed in brackets
{AB, bc}
Any of the character strings in the braces
23
24 Adams/Car
Setting Preferences
Setting Screen and Printer Fonts
You can change the font your template-based product uses to display text in a view, such as the name of
a part or a note on the screen, or to print text to a printer. The fonts available for displaying text in a view
are those available with your operating system. The fonts available for printing text are a fixed set of 12
fonts. Note that your printer may not support all of these printer fonts.
To select a screen or printer font:
1. On the Settings menu, select Fonts.
The Fonts dialog box appears.
2. In the Screen Font text box, enter the name of the font you want your template-based product to
use to display text in a view. To browse for a font, right-click the text box, select Browse, and
then select a font.
3. Set Postscript Font to the font you want to use to print text.
4. Select OK.
Specifying Working Directory

By default, your template-based product searches for and saves all files in the directory from which you
ran your template-based product. You can change the working directory.
To change the working directory for the current session:
1. On the File menu, select Select Directory.
Select the directory in which your template-based product should save files.
2. Select OK.
You can also set the working directory when you start your template-based product.
To change the working directory for all sessions:
On UNIX:
1. From the Adams Toolbar, right-click your template-based product's tool, and then select Change
Settings.
2. In the Registry Editor, select WorkingDirectory, and then change the working directory.
On Windows:
1. On the Desktop, right-click your template-based product's shortcut, and select Properties.
2. In the Start In text box, enter the working directory.
For more information, see your Windows online help.
Learning the Basics
Setting Units of Measurement

You can set the units that your template-based product uses in modeling, importing, and exporting files.
You can select individual units or select a set group of units.
To set the unit of measurement:
1. On the Settings menu, select Units.
The Units Settings dialog box appears.
2. Select the unit of measurement for each of the dimensions using the table below for assistance.
3. Select OK.
To Select:
Do the following:
Unit for a specific Select the individual unit from the pull-down menu associated with the dimension.
dimensions
Predefined unit
system
Select one of the following buttons. In all the unit systems, time is in seconds and
angle is in degrees. When you select a predefined unit system, the units selected
appear in the upper portion of the dialog box.
MMKS - Sets length to millimeters, mass to kilograms, and force to
Newtons.
MKS - Sets length to meters, mass to kilograms, and force to Newtons.

CGS - Sets length to centimeters, mass to grams, and force to Dyne.
IPS - Sets length to inches, mass to pound mass, and force to PoundForce.
25
26 Adams/Car
Setting Screen Icon Display

When you first start your template-based product, it displays screen icons. As you add objects to your
model, however, these icons can clutter your view of the model. To clear the display of a window, you
can turn off the icons. You can select to turn off:
All icons
Only icons of certain types of objects, for example, all joints
Only icons for individual objects, such as FORCE_1
In addition, you can set the size of the icons either in current units or as a factor of their current size.
Learn more about how to set the display of screen icons by database and object type.
Setting Screen Icon Display by Database
Setting Screen Icon Display by Object Type
For information on quickly toggling the display of all screen icons, see Displaying View Accessories. For
information on setting the display of icons for individual objects, see Setting Object Appearance through
Edit -> Appearance Command.
Setting Screen Icon Display by Database

You can set up how you want screen icons to be displayed for an entire modeling database. By default,
all models and objects in the modeling database inherit the screen icon settings that you specify for the
database. You can, however, override the inheritance for different types of objects as explained in Setting
Screen Icon Display by Object Type, or for individual objects as explained in Setting Object Appearance.
To set up the screen icon display for the entire database:
1. On the Settings menu, select Icons.
The Icon Settings dialog box appears.
2. Set New Value to one of the following to select whether or not you want to turn on screen icons:
No Change - Select No Change to not change the current settings.
On - Turns on all icons regardless of how you set the icon display for individual objects or
types of objects.
Off - Turns off all icons regardless of how you set the icon display for individual objects or
types of objects.
3. In the New Size text box, enter the size you want for the screen icons. Note that any changes you
make to the size of icons for individual objects or types of objects take precedence over this size
setting.
4. To save the settings for each new database in your template-based product settings file
(*BS.cmd), select Save new size as default.
5. Select OK.
Learning the Basics
To reset the screen icon display to the previous values:

On the Icon Settings dialog box, select Reset.
Setting Screen Icon Display by Object Type

You can set up how you want creen icons displayed for a particular type of object, such as all parts or
joints. By default, all objects inherit the screen icon display options that you specify for the modeling
database. You can set screen icon options for the following types of objects:
Parts
Joints
Forces
Motion
Markers (Note that markers belong to parts and, therefore, by default, inherit screen icon display
options for parts.)
Points
Data elements
Equations (system elements)
To set screen icon display options for objects of a particular type:

1. On the Settings menu, select Icons.
The Icon Settings dialog box appears.
2. Set Specify Attributes for to the type of object for which you want to set the screen icon options.
3. From the Visibility area of the Icon Settings dialog box, select whether or not you want to turn
on screen icons for the selected object type. You can select:
On - Turns on the display of screen icons for the selected type of object.
Off - Turns off the display of screen icons for the selected type of object. Remember,
however, that turning on the display of screen icons for the entire database overrides this
setting.
Inherit - Lets the object type simply inherit the display settings from its parent. For example,
a coordinate system marker inherits settings from its parent part.
No Change - Does not change the current settings. Lets you make changes to other display
options without affecting the visibility of the icons.
4. Enter the size you want for the icons or select the amount by which you want to scale the icons.
The scale factor is relative to thecurrent size set. A scale factor of 1 keeps the icons the same size.
A scale factor less than 1.0 reduces the size of the icons and a scale factor greater than 1.0
increases the size of the icons. Note that these changes take precedence over the size you specify
globally for the modeling database.
5. Enter the color you want to use for the icons.
27
28 Adams/Car
6. To browse for or create a color, right-click the Color text box, and then select Browse or Create.
7. Set Name Visibility Option to whether or not you want the names of objects of the selected type
displayed in the view. Refer to Step 3 for an explanation of the choices.
8. Select OK.
Learning the Basics
Setting Display Options

Learn about:
Setting Part Display
Displaying View Accessories
Setting Rendering Mode
Displaying the Status Toolbar
Setting Part Display

You can set the main window so it displays a particular part in the current model. You will find this
helpful when you want to compare or work with different parts at the same time.
To display a single part in the main window:
1. Click the main window.
2. From the View menu, select Part Only.
The Database Navigator appears listing the parts in the current model.
3. Select the part you want to display.
4. Select OK.
The selected part appears in the currently active view.
Displaying View Accessories

When you first start your template-based product, it displays several accessories to help you manage the
view of your model:
Working grid
Screen icons
View triad
View title
To use a dialog box to toggle on and off the display of view accessories:
1. Click the main window.
2. On the View menu, select View Accessories, and then select the accessories that you want toturn
on or off from the View Accessories dialog box that appears.
3. Enter the title you want displayed in the main window, and then press Enter.
4. On the Window menu in the View Accessories dialog box, select Exit.
29
30 Adams/Car
Tip:
Type a lowercase g while the cursor is in the main window to toggle on and
off the display of the working grid.
Type a lowercase v to toggle on and off the display of screen icons.
Setting Rendering Mode

Your template-based product provides six rendering modes in which you can display a model in the main
window.
To select a rendering mode:
Click the main window.
On the View menu, point to Render Mode, and then select a rendering mode.
To toggle the display between wireframe and smooth shaded mode:

Type an uppercase S in the main window.
Displaying the Status Toolbar

You can turn on and off the display of the status toolbar. You can also set where the status toolbar
appearseither at the top of the main window under the menu bar or at the bottom of the window. By
default, the status toolbar appears at the bottom of the window.
To turn the status toolbar on and off:
1. On the View menu, select Toolbox and Toolbars.
2. Select Status Toolbar and its placement in the main window. Your changes take place
immediately.
3. Close the dialog box.
Refreshing the Model Display

You can redraw the main window to return the model to its initial configuration and display all geometry
in the model . This is particularly useful if you selected to view only certain parts and now want to view
the entire model.
To refresh the model display:
On the View menu, select Refresh.
Learning the Basics
Setting View Background Colors

By default, your template-based product uses a blue background to display the main window. It also
provides a set of colors in which you can display the background. You can set the view to any color by
setting the red, green, and blue colors directly.
Selecting a Preset Background Color

You access the palette of background colors using View Background Color command on the Settings
menu.
To select from the entire palette of background colors:
1. From the Settings menu, select View Background Colors.
2. Press F1 and then follow the instructions in the dialog box help for Edit Background Color.
3. Select OK.
Creating a Background Color

You can create a background color by setting its red, green, and blue light percentages and change the
background of the main window to this new color. You cannot add the color to the preset palette of colors
or change the colors in the preset palette.
To create a color:
1. From the Settings menu, select View Background Colors.
2. Press F1 and then follow the instructions in the dialog box help for Edit Background Color.
3. Select OK.
To reset a color to the original background color:
Select the R tool in the Edit Background Color dialog box.
31
32 Adams/Car
Using Template-Based Product Tools

Learn about using the following template-based product tools:
Coordinate Window
Command Navigator
Command Window
Message Window
Information Window
Database Navigator
Working with the Coordinate Window

You can use the coordiante window to help you identify the coordinates of any location in the main
window. You can also measure the distance between objects based on their coordinate locations.
The sections below explain how to work with the coordinate window:
Displaying the Coordinate Window

To toggle on and off the display of the coordinate window, do one of the following:
On the View menu, select Coordinate Window.
The coordinate window appears in the lower right corner of the screen. You can move and size it
as you do any window in your operating system.
Tip:
Press the F4 key to toggle the display of the coordinate window.
Measuring the Distance Between Points

In delta mode, you can use your mouse and the coordinate window to find the distance between two
points.
To measure the distance between two points:
1. Move the cursor to the point in the main window where you want to begin, and press and hold
down the mouse button.
2. Drag the cursor to the next point. As you drag the cursor, your template-based product displays
the distance the cursor moves in the coordinate window.
3. To end delta mode, release the mouse button.
Learning the Basics
Command Navigator
Enables you to enter Adams/View commands without having to know the entire syntax of the
commands.
The Command Navigator displays a list of all Adams/View command keyword. A plus (+) in front of a
keyword indicates that the command has more keywords below it but they are hidden. A minus (-)
indicates that all keywords below the keyword are displayed. No indicator in front of a keyword indicates
that there are no more keywords below the object. When you select an object with no indicator, a dialog
box appears in which you enter parameters for executing the command.
Using the Command Window

The command window provides a text-based way to enter commands. Itassumes that you understand the
command language underlying your template-based product's interface. The command window contains
both a command entry area for entering commands and a command information area for displaying
informational and error messages:
Message Window
Provides you with messages on the status of Adams/View and displays helpful information while you
are using Adams.
Adams/View displays messages about the execution of a command in the message window. By default,
the message window only displays messages about commands you execute from the user interface. You
can also set it to display messages about commands that you execute from the command window,
command Navigator, and command files.
33
34 Adams/Car
Information Window
Adams/View uses the Information window to display many different types of information about your
model, simulation, or motion data. In addition to just viewing information about your model, you can
perform a variety of operations in the Information window.
The information includes:
Topology on the different objects in your model
Object information, such as information about a part or a view
Model verification results
Measurements from one coordinate system marker to another
Result set component information
View attributes
Results from a system command you run using the Tools -> System Command
The Option:
Does the following
Apply
Executes the command but leaves the dialog box open so you can execute the
command again.
Parent
Displays an object's parent.
Children
Displays an object's children.
Modify
Select to display the modify dialog box for the object displayed in the text box
at the top of the Information window.
Verbose
Select if you want to display more information about the object such as
children of the object, its geometry, whether or not commands are associated
with it, and its attributes like color and visibility.
Clear
Removes all current information in the window.
Read from File
Allows you to read information from a saved file.
Save to File
Allows you to save the information.
Database Navigator
Displays the types of objects appropriate for the command you are executing and shows objects in their
database hierarchy. You can browse for objects or set it to rename objects, view information about the
objects and view dependencies. You can also set a filter for the types of objects displayed in the Database
Navigator.
Learning the Basics
For the option:

Pull-Down Menu
Do the following:
Use the pull-down menu to choose a mode option. Select one:
Browse (the default; the options on this page describe Browse)
Display Attribute
Rename
Comments
Information
Topology by Parts
Topology by Connections
Graphical Topology
Associativity
Select List
Filter
Select if you want to filter the types and names that you want displayed in the
Database Navigator. Then, enter the name of the objects you want to display in
the text box and use the pull-down menu to the right to select the type of
object(s) you want to display. You can also use the pull-down menu below the
Filter text box to only display those objects that are active or inactive.
Sort by
Use the pull-down menu to choose how you want the objects sorted. You can
also select to not sort the objects so they appear in the order they are stored in
the modeling database.
Highlight
Off by default. Select if you want an object to appear selected in the main
window and the reverse.
Use the plus sign (+) or the minus (-) (--) signs to display or hide all of the
children hidden/shown in the tree view.
35
36 Adams/Car
Files and Commands

Executing a System Command
You can execute an operating system command from within your template-based product so that you do
not have to leave your template-based product window.
You can select to display the results of the command in the Information window or the log file. If you select
to display the results of the command in the Information window, you can:
Clear the window and only view the results of the command.
Save the results of the command to a file.
If you select to display the results in the log file, you can keep the command results with the other
commands that you execute so that you can cut and paste the information together into a new file.
To execute a system command within your template-based product:
1. On the Tools menu, select System Command.
The Execute Systems Command dialog box appears.
2. In the Command Text text box, enter the operating system command that you want to execute.
See your operating system documentation for more information.
3. Select whether or not you want the output of the command to be displayed in the Information
window or the log file.
4. Select OK.
Using the Log File

Your template-based product generates a log file during each session, called *.log.
While you are running Adams, you can display the current contents of the log file. In addition, you can
display the log file in a text editor. The following sections explain how to display the log file in your
template-based product and set the type of messages displayed.
Viewing the Log File in Your Template-Based Product
Updating the Log File
Setting the Log File Information
Note:
You can change the name of the log file through the initialization file .mdi_init.
Learning the Basics
Viewing the Log File in Your Template-Based Product

You can use the Log File command on the Tools menu to display the log file. You can keep the dialog
box open as you execute commands so you can keep track of the commands and messages that you
receive.
To help you use the log file as a command file, your template-based product marks any messages as
comments so that it does not try to execute them when you import the command file. It indicates a
comment by placing an exclamation mark (!) in front of the message. Your template-based product also
displays as comments any commands that it executes when it starts up. To help you distinguish the
startup commands from messages, your template-based product follows the exclamation mark (!) with
the command prompt (>>).
To display the log file:
1. On the Tools menu, select Log File.
The Display Log File dialog box appears.
2. Select Info to display all messages written to the log file. The default is to display only warnings,
errors, and fatal messages.
Updating the Log File
Your template-based product does not update the Display Log File dialog box each time you execute a
command. Therefore, if you want to see the commands that you executed since you opened the dialog
box, you must update the log file.
To update the contents of the log file:
From the Display Log File dialog box, select Update.
Setting the Log File Information
When you display the log file, your template-based product displays only warnings, errors, and fatal
messages that you have received. You can change the type of messages that your template-based product
displays as well as display the commands that your template-based product has executed. You can also
display only lines that contain certain information, such as display only commands that create links, and
remove any duplicate lines that occur if you encounter the same error again.
To set the type of information displayed in the Display Log File dialog box:
1. Select the Show only lines of type check box and then select one of the following:
Info - Displays all commands that you have executed in your template-based product.
Warning - Displays non-fatal messages that warn you of possible problems with commands
you entered.
Error - Displays fatal messages that your template-based product did not understand and,
therefore, did not successfully process.
Fatal - Displays messages that indicated that your model would not simulate.
37
38 Adams/Car
2. If desired, select Show only lines containing and enter the text that the line must contain in the
text box. You can also enter wildcards.
3. Select Apply.
To remove duplicate lines:
From the Display Log File dialog box, select Suppress duplicate lines.
Loading and Unloading Plugins

MSC has many add-on modules or plugins to template-based products, which expand their functionality.
The plugins include Adams/Driveline, Adams/Car Ride, Adams/Vibration, Adams/Controls, and
Adams/Durability. You run these products from within your template-based product. You can set your
template-based product to load them automatically when you start up. You can also unload them while
in your template-based product's current session. To run a plugin, you must have a license to it.
To see if there is a license available to run a plugin:
1. From the Tools menu, select Plugin Manager.
The Plugin Manager appears.
2. At the top of the Plugin Manager, select a plugin.
3. At the bottom of the Plugin Manager, in the text box Licenses, view the number of licenses
available.
To load an available plugin:
2. In the Load column, next to the plugins you want to load, select Yes.
3. Select OK.
The commands or menus for the plugins are added to your template-based product.
To unload a plugin:
2. In the Load column, next to the plugin you want to unload, clear the selection of Yes.
3. Select OK.
Your template-based product removes any plugin menus or commands.
To set up a plugin so it loads automatically when you start your template-based
product:
2. In the Load at Startup column, next to the plugin you want to load automatically, select Yes.
3. Select OK.
Learning the Basics
Displaying Product Information

When using any Adams product, you can display the following information:
Software version number and the date it was built
Directory where Adams is installed
Copyright statement
To display information about your product:

1. From the Help menu, select About <product name>.
2. View the information, and then select OK.
Tip:
From the status toolbar, select
39
40 Adams/Car
Building Models
40 Adams/Car
Subsystems
You only use subsystems in the Standard Interface. You can either create new subsystems or read in
existing ones. When you create a new subsystem, you must reference an existing template. When you use
an existing subsystem, the template associated with it is automatically read in.
Subsystems are based on templates and allow standard users to change the parametric data of the template
as well as the definition of some of the components. For example, you can change the location of
hardpoints and modify parameter variables.
The template-based products organize the basic components that make up a full assembly or subassembly
into subsystems. For example, subsystems can include suspensions, wheels, drivelines, chassis, and so
on.
Subsystems contain descriptions of the component that they model. These descriptions consist of:
Design data, such as wheel radii, toe angles, and locations of various points in the subsystems,
named hardpoints, mass properties of parts, and so on.
References to property files that contain design data for bushings, bumpstops, dampers, engines,
springs, and tires. A bushing property file, for example, contains a description of the bushing's
stiffness and damping characteristics.
Reference to a template that defines the subsystem's construction, including the kinds of parts
and how the parts interact and attach to one another. For example, a template that defines a rack
and pinion steering system defines a rack part, a pinion part, and a housing part. It also defines
that the rack slides in the housing, that the pinion rotates in the housing, and that the rack and
pinion are geared together. Since the construction of all rack and pinion steering systems is
similar, all subsystems describing a rack and pinion steering system can reference the same
template.
Learn more about subsystems:

Opening Subsystems
Getting Subsystem Information
Creating Subsystems
Updating Subsystems
Synchronizing Subsystems
Adding Subsystems
Replacing Subsystems
Removing Subsystems
Setting Subsystem Activity
Saving Subsystems
Closing Subsystems
Subsystem Modes
Building Models
Minor Roles
Publishing Subsystems
Opening Subsystems
When you open a subsystem that specifies a flexible representation of a rigid part, your template-based
product replaces the equivalent rigid body from the template with the flexible body. Learn about flexible
bodies.
To open an existing subsystem:
1. In Standard Interface, from the File menu, point to Open and then select Subsystem.
2. Press F1 and then follow the instructions in the dialog box help for Open Subsystem.
3. Select OK.
Notice that once the subsystem is open, the Edit and Adjust menus become active. We
recommend that you familiarize yourself with each menu item.
Getting Subsystem Information

You can get detailed information about subsystems in the current session.
To get information about a subsystem:
1. In the Standard Interface, from the File menu, point to Info, and then select Subsystem.
2. Press F1 and then follow the instructions in the dialog box help for Subsystem Info.
3. Select OK.
Creating Subsystems
You create subsystems by selecting a template that defines the topology and default data for your
subsystem. Using the Standard Interface, you can modify the default data to match your design. We
supply several templates with each product. For example, for Adams/Carusers, we supply templates that
represent MacPherson strut and double-wishbone suspension subsystems. Using the Template Builder
you can create templates for your company-specific topologies.
When creating a new subsystem, you can reference the property files that the template references, or
reference other property files held either in a different database or with a different file name, as indicated
by the dashed lines in the example model architecture.A collection of subsystems merged together forms
an assembly.
To create a subsystem:
1. In the Standard Interface, from the File menu, point to New, and then select Subsystem.
41
42 Adams/Car
2. Press F1 and then follow the instructions in the dialog box help for New Subsystem.
3. Select OK.
Updating Subsystems
Resets the values of a subsystem to those stored in a subsystem file. You can update a subsystem using
any subsystem file that is based on the same template as the subsystem in session.
When you update a subsystem, your template-based product does not reload the template.
Note:
The subsystems is not renamed during the update.
To update a subsystem:
1. In the Standard Interface, from the File menu, point to Manage Subsystems, and then select
Update.
2. Press F1 and then follow the instructions in the dialog box help for Update Subsystem.
3. Select OK.
Synchronizing Subsystems
When you synchronize a subsystem, you apply the values of the selected master subsystem to one or
more subsystem instances using the automated subsystem update feature. You can synchronize the
subsystems in session that are based on the same subsystem file. The subsystem mode flags (kinematic
or compliant) of the target subsystems will be retained.
For example, you may have several instances of one subsystem open in your session under several
assemblies. If you modify one subsystem and want to propagate those changes to every instance of the
subsystem, you can use the synchronize subsystems functionality.
To synchronize subsystems:
1. In the Standard Interface, from the File menu, point to Manage Subsystems, and then select
Synchronize.
2. Press F1 and then follow the instructions in the dialog box help for Synchronize Subsystem.
3. Select OK.
Adding Subsystems
When you add a subsystem into an assembly, your template-based product disassembles the assembled
model, opens the subsystem, and then reassembles the model to include the new subsystem.
Building Models
To add a subsystem:
1. From the File menu, point to Manage Assemblies, and then select Add Subsystem.
2. Press F1 and then follow the instructions in the dialog box help for Add Subsystem.
3. Select OK.
Your template-based product does the following:
Disassembles the assembly, which includes 'unassigning' communicators.
Opens the new subsystem under the existing assembly.
Reassembles the assembly, which includes re-assigning the communicators.
Replacing Subsystems
When you replace a subsystem in an assembly with a new subsystem, your template-based product
disassembles the assembled model, deletes the subsystem, opens the new subsystem, and then
reassembles the model to include the new subsystem.
To replace a subsystem:
1. From the File menu, point to Manage Assemblies, and then select Replace Subsystem.
2. Press F1 and then follow the instructions in the dialog box help for Replace Subsystem.
Select OK.
Deletes the subsystem from the existing assembly.
Opens the new subsystem underneath the existing assembly.
Removing Subsystems
When you remove a subsystem from the assembly to which it belongs, your template-based product
disassembles the assembled model, deletes the subsystem, and then reassembles the model.
To remove a subsystem:
1. From the File menu, point to Manage Assemblies, and then select Remove Subsystem.
2. Press F1 and then follow the instructions in the dialog box help for Remove Subsystem.
3. Select OK.
Deletes the subsystem from the assembly.
43
44 Adams/Car
Toggling Subsystem Activity

Toggles the activity status of an existing subsystem. Your template-based product disassembles the
assembled model, sets the subsystem activity accordingly, and then reassembles the model to take into
account the subsystems activity status.
When you set the subsystem activity status to inactive, your template-based product ignores the
subsystem during model assembly, and will not write it to the Adams/Solver files.
Note that compared to the Remove Subsystem functionality, which deletes the subsystem, the Toggle
Subsystem Activity functionality only de-activates the subsystem and all objects in it.
To toggle subsystem activity:
1. From the File menu, point to Manage Assemblies, and then select Toggle Subsystem Activity.
2. Press F1 and then follow the instructions in the dialog box help for Toggle Subsystem Activity.
3. Select OK.
If activating the subsystem, your template-based product does the following:
Activates the subsystem, which means that it will now be considered a valid part of the
assembly.
Reassembles the assembly (with the activated subsystem now taking part), which includes re-
assigning the communicators.
If deactivating the subsystem, your template-based product does the following:

Deactivates the subsystem, which means thatit is not actually removed from the assembly, but
simply ignored.
Reassembles the assembly (with the deactivated subsystem not considered), which includes
re-assigning the communicators.
Saving Subsystems
You save subsystems in ASCII format, and you can publish subsystems to databases so other users can
share them. We support two formats: TeimOrbit and XML.
If your subsystem contains a flexible part, your template-based product saves information about the part,
as well as the marker-node association, in the PART_ASSEMBLY block of the subsystem file. Your
template-based product writes one block for a single flexible part or two for paired parts, of which one is
flexible.
Building Models
To save a subsystem:
While viewing a subsystem, from the File menu, do one of the following:
Select Save (or use the keyboard shortcut, Ctrl + s) - Your template-based product saves the
TeimOrbit version of the subsystem to the default writable database and prompts you if a
subsystem already exists. For save options, select Save As.
Point to Save As, and then select Subsystem - Press F1 and then follow the instructions in the
dialog box help for Save Subsystem. Select OK.
To save a subsystem that is part of an assembly:

1. View the subsystem you want to save:
From the View menu, select Subsystem.
Set Subsystem to the subsystem you want to save.
Select OK.

Select Save (or use the keyboard shortcut, Ctrl + s) - Your template-based product saves the
TeimOrbit version of the subsystem to the default writable database and prompts you if a
subsystem already exists. For save options, select Save As.
Point to Save As, and then select Subsystem - Press F1 and then follow the instructions in the
dialog box help for Save Subsystem. Select OK.
Closing Subsystems
You can close a subsystem without first saving it to a database.
To close a subsystem:
1. In the Standard Interface, from the File menu, point to Close, and then select Subsystem.
2. Press F1 and then follow the instructions in the dialog box help for Close Subsystem.
3. Select OK.
Subsystem Modes
A subsystem exists in one of two modes - kinematic or compliant. When you toggle a subsystem between
these two modes, certain elements such as joints and bushings may be enabled or disabled. When you
create a joint, you define it to be active always or only in kinematic mode. Conversely, when you create
a bushing, you define it to never be inactive or be inactive only in the kinematic mode. This allows you
to use the same subsystem for both dynamic and kinematic analyses.
45
46 Adams/Car
Minor Roles
You assign a minor role, or function, to every subsystem. The minor role of a subsystem is stored in a
variable as a string. This string will also be written to the subsystem file. You select a minor role to
identify how your product should use the subsystem when creating an assembly of subsystems for
analysis.
A minor role defines the subsystem's location.
Adams/Car - A minor role can be front or rear. The following are the minor roles for
Adams/Car: any, front, rear, and trailer.
If you create a new subsystem with the minor role front based on a steering template, during
assembly Adams/Car connects your front steering subsystem to a front suspension subsystem,
but not a rear suspension subsystem.
If you create a new subsystem with the minor role any, during assembly Adams/Car connects
your new subsystem to any other active subsystem having matching communicators.
When you publish a subsystem, you copy the subsystem file and all its associated property files to the
target database, which is the database where your template-based product saves all files. You can also
select to publish the subsystem's template file. As you publish the subsystem, you can choose to write
over existing files or create backups of the files.
You can also select to update the in-session subsystem data to point to the target database or to have the
subsystem retain the existing references.
The subsystem you are publishing must be currently opened in the standard interface, and the target
database must be writable. Learn about setting the writable database.
You can also publish an entire assembly. Learn about publishing an assembly.
To publish a subsystem:
1. From the Tools menu, point to Database Management, and then select Publish Subsystem.
2. Press F1 and then follow the instructions in the dialog box help for Publish an Open Subsystem.
3. Select OK.
Building Models
Assemblies
Assemblies represent a collection of subsystems, along with a test rig, which when assembled form a
system that you can analyze using Adams/Solver.
In Adams/Car for example, a steering subsystem and a front-suspension subsystem, plus a suspension
test rig, form the basis of a suspension assembly that you can analyze for kinematic behavior.
In the Standard Interface, you can create, open, save, and analyze assemblies. You can also publish
assemblies to databases so other users can share them. Learn about publishing assemblies.
Learn more about assemblies:
Opening Assemblies
Getting Assembly Information
Creating Generic Assemblies
Updating Assemblies
Saving Assemblies
Closing Assemblies
Publishing Assemblies
Opening Assemblies
To open an existing assembly:
1. In Standard Interface, from the File menu, point to Open and then select Assembly.
2. Press F1 and then follow the instructions in the dialog box help for Open Assembly.
3. Select OK.
Notice that once the subsystem is open, the Edit, Adjust, and Simulate menus become active. We
Getting Assembly Information

You can get detailed information about assemblies in the current session.
To get information about an assembly:
1. In the Standard Interface, from the File menu, point to Info, and then select Assembly.
2. Press F1 and then follow the instructions in the dialog box help for Assembly Info.
3. Select OK.
47
48 Adams/Car
Creating Generic Assemblies

You can create a generic assembly from specified subsystems.
To create a generic assembly:
1. From the Tools menu, point to Dialog Box, point to Display, and then select
dbox_fil_ass_new_gen.
2. Press F1 and then follow the instructions in the dialog box help for New Generic Assembly.
3. Select OK.
Updating Assemblies
You can re-read an assembly file, in case you modified the file by an alternative process. For example, if
you edit in a text editor an assembly file stored in the shared database, you can reflect this change in your
template-based product by using the update assembly functionality.
To update an assembly:
1. In the Standard Interface, from the File menu, point to Manage Assemblies, and then select
Update.
2. Press F1 and then follow the instructions in the dialog box help for Update Assembly.
3. Select OK.
Saving Assemblies
You save assemblies in ASCII or binary format:
ASCII Assemblies - An ASCII assembly file references subsystems, but does not contain
subsystem data. If you want your assembly to be updated with the current template/subsystem
files, you should save your assemblies in ASCII format. When you open an ASCII-format
assembly, your template-based product opens each individual subsystem, which in turn accesses
the current version of each corresponding template.
Binary Assemblies - A binary assembly is a static snapshot of what's currently in your session.
That is, when you reopen a binary assembly, you will return to the exact state at which you left.
Adams/Car ignores any subsequent modifications made to templates and/or subsystems, which
were originally used to create the assembly, when you open the binary assembly. Therefore, if
you want your assembly to be updated with the current template/subsystem files, you should
save your assemblies in ASCII format.
Binary assemblies can be very useful, however, if you are working on a project where the
templates will not change, and a static snapshot of the assembly is sufficient.
Note that saving an assembly as a binary will not save the plots, nor the setting for simulation
(hold_solver_license). It will, however, save the analyses associated with the assembly, and you
could re-create plots using a plot configuration file. Learn about plot configuration files.
Building Models
To save an assembly:
1. From the File menu, select Save or Save As.
2. If you selected:
Save - Your template-based product saves the ASCII version of the assembly to the default
writable database. Your template-based product prompts you if it detects subsystem changes.
It also prompts you if the assembly already exists in the database. For save options, select
Save As.
Save As - Press F1 and then follow the instructions in the dialog box help for Save Assembly.
Select OK.
Closing Assemblies
To close an assembly:
1. In the Standard Interface, from the File menu, point to Close, and then select Assembly.
2. Press F1 and then follow the instructions in the dialog box help for Close Assembly.
3. Select OK.
When you publish an assembly, you copy each subsystem file included in the assembly definition,
including the associated property files for each subsystem, to the target database, which is the database
where your template-based product saves all files. You can also select to publish each subsystem's
template file. As you publish the assembly, you can select to write over existing files or create backups
of the files.
You can also select to update the in-session assembly data to point to the target database or to have the
assembly retain the existing references.
The assembly you are publishing must be currently opened in the standard interface, and the target
You can choose to publish only a subsystem, not an entire assembly. Learn about publishing a subsystem.
To publish an assembly:
1. From the Tools menu, point to Database Management, and then select Publish Assembly.
2. Press F1 and then follow the instructions in the dialog box help for Publish an Open Assembly.
3. Select OK.
49
50 Adams/Car
Property Files
Property files are ASCII-based files that contain data for modeling components, such as valve spring,
cams, and bushings. Because property files are flat text files, you can use any text editor to create or
modify them.
You use property files to:
Apply the same characteristics or parameters to many components within a template or
subsystem. In Adams/Car for example, a suspension might contain many bushings with the same
properties. In this case, all the bushings could reference the same property file.
Share a component between different templates and subsystems.
You can reference property files in different subsystems and templates, as shown in the example model
architecture.
All property file types are specifiedin the configuration file (acar.cfg). When you edit property files, you
can save them either with the existingfile name or with a new file name. Learn about managing property
files through configuration files.
Property files are grouped in classes and stored in databases. Every class (such as bushings and dampers)
is filed in the corresponding database table (in this case, bushings.tbl and dampers.tbl).
A subset of property files define force-displacement or force-velocity characteristics for springs,
dampers, bumpstops, reboundstops, and bushings. For those components, you use the Curve Manager or
Property File Editor to create, edit, and view property files. You can access the Curve Manager from the
Tools menu. From within dialog boxes, you can edit property files using the Curve Manager/Property
File Editor tool
and view property files using the View File tool
Building Models
Templates
Templates are parametric models, built by expert users within the Template Builder. Templates define
the default geometric data and topology of models, such as a double-wishbone suspension, an engine
cranktrain, or an aircraft landing gear. The components within a template are parametrically defined such
that you can use a single template within numerous subsystems.
Templates are intended to be a generic representation of a mechanical system, such that a template that
is common to a number of different vehicles can be reused in each of those vehicles. For example,
assume that you have two cars, a small car and a large car and that each of the two cars have a doublewishbone front suspension. You could use a double-wishbone template in each of the two vehicles. The
only difference is that the large car requires stiffer springs, larger A arms, different dampers, and so on.
The basic topology is the same: it is the components/properties that are changed. It is the subsystem file
that references the topology of the template but changes the characteristics of the suspension by
referencing different springs, parts, dampers, and so on.
Templates provide a quick way to experiment with different subsystems and still retain the basic design
components that are required.
A template in its most fundamental form cannot be used in the Standard Interface without first being
referenced by a subsystem file.
You can modify the data of a template by changing the values of design parameters. Hardpoints,
parameter variables, and property files are the design parameters of templates, where:
Hardpoints define locations for geometry, attachments, and construction frames.
Parameter variables contain strings, integers, and real values that you can modify in the Standard
Interface and store in the subsystem file.
Property files are referenced by some components.
Templates contain communicators to enable the exchange of information with other templates.
Learn more about templates:
Opening Templates
Creating Templates
Saving Templates
Closing Templates
Major Roles
Location of Templates
Opening Templates
When using the Template Builder for the first time, we recommend that you first open some of the
example templates we provide and familiarize yourself with them.
51
52 Adams/Car
To open an existing template:

1. From the File menu, select Open.
2. Press F1 and then follow the instructions in the dialog box help for Open Template.
3. Select OK.
Note:
Notice that once the template is open, the Edit and Build menus become active. We
Creating Templates
To ensure that an analysis will work with your new template, when you create a template you must make
sure that the template is compatible with other templates and with the test rigs. The template must contain
the proper output communicators.
To create a template:
1. From the File menu, select New.
2. Press F1 and then follow the instructions in the dialog box help for New Template.
3. Select OK.
Note:
Notice that once the template is open, the Edit and Build menus become active. We
Saving Templates
Using the Template Builder, you can save your files in ASCII or binary format. Saving your files in
ASCII format provides the benefit of small file sizes and being human readable. On the other hand,
saving your files in binary format ensures faster processing, but does not have the benefits associated
with ASCII format.
When saving a template that includes a flexible part, your template-based product saves the part as rigid.
To save a template:
2. If you selected:
Save - Your template-based product saves the binary version of the template to the default
writable database and prompts you if the template already exists. For save options,select Save
As.
Save As - Press F1 and then follow the instructions in the dialog box help for Save Template.
Select OK.
Building Models
Closing Templates
You can close a template without first saving it to a database.
To close a template:
1. From the File menu, select Close.
2. Press F1 and then follow the instructions in the dialog box help for Close Template.
3. Select OK.
Major Roles
You assign a major role, or function, to every template. The choices in the Major Role option menu
correspond to the available major roles for a template.
A major role is a property of a template. A subsystem inherits the major role of the type on which it is
based.
In Adams/Car, examples of major roles are: suspension, steering, and body. Note that for each major role
(for example, suspension, steering, and so on) Adams/Car allows only one active subsystem with the
minor role any. The choices in the Minor Role option menu correspond to the available minor roles for
an Adams/Car subsystem.
Location of Templates
The templates are located in the templates.tbl table, or directory, of your template-based product's shared
database. The shared database is usually located in your product's installation directory. For location
details, see your system administrator.
53
54 Adams/Car
Test-Rig Templates
You can extend the functionality of your templates by converting them into test-rig templates, also
referred to as test rigs.
In the template-based products, test rigs are almost completely comparable to regular templates. The
basic topological difference between test rigs and regular templates is that besides containing parts that
are attached using attachments and forces, test rigs also contain actuator elements, such as motions and
forces, to excite the assembly. Just like regular templates, test rigs also contain communicators to enable
the exchange of information with other templates.
You use test rigs when creating assemblies. A collection of subsystems and a test rig form an assembly.
Note that the name of a test rig is always preceded by a period and two underscores, that is .__. For
example, .__MY_TESTRIG. This is a convention used by all template-based products to differentiate
between templates (period and one underscore, ._), subsystems (period, .), and test rigs (period and two
underscores, .__).
Learn about test rigs:
Process Overview
Creating Test-Rig Templates
Saving Test-Rig Templates
Converting Templates into Test Rigs
Adding Test Rigs to Binaries
Process Overview
The process of working with test-rig templates involves the following steps:
For Adams/Car:
1. Creating a template and saving it in ASCII format as explained in Creating Test-Rig Templates
and Saving Test-Rig Templates.
2. Modifying the ASCII template file to become an ASCII command file, which is now the test rig,
as explained in Converting Templates into Test Rigs.
3. Saving the ASCII command file into a binary file as described in Adding Test Rigs to Binaries.
Creating Test-Rig Templates

You create test-rig templates the same way you create regular templates.
To create a test-rig template:
1. From the File menu, select New.
2. Press F1 and then follow the instructions in the dialog box for New Template.
Building Models
3. Select OK.
Note:
You must specifically set the minor roles of communicators in test-rig templates to any. Do
not set them to inherit. You set the minor roles to any because generally a template test rig
should be capable of connecting with any subsystem.
Saving Test-Rig Templates

You can save test-rig templates to files, just as you would save regular templates. We recommend that
you save test rigs in ASCII format so you can hand edit them. Storing test-rigs in ASCII format also
ensures portability from one machine to another. It allows you, for example, to use the same file when
building a site binary on either a Windows or UNIX machine.
To save a test-rig template:
2. If you selected:
Save - Your template-based product saves the binary version of the template to the default
writable database and prompts you if thetemplate already exists. For save options, select Save
As.
Save As - Press F1 and then follow the instructions in the dialog box help for Save Template.
Select OK.
3. Depending on the template-based product you are using, continue as follows:

If working in Adams/Car go to Converting Templates into Test Rigs.
Converting Templates into Test Rigs

To convert templates into test rigs you must make the following modifications to your ASCII test-rig
template file generated from your template-based product:
Removing the Header Information
You must remove the header information that is added at the beginning of the ASCII template file
because the command file reader will not understand the information stored in this header and will output
errors.
The following example shows a typical header from an ASCII template file:
$-----------------------------------------------MDI_HEADER
[MDI_HEADER]
FILE_TYPE = 'tpl'
FILE_VERSION = 13.3
FILE_FORMAT = 'ASCII'
HEADER_SIZE = 9
55
56 Adams/Car
(COMMENTS)
{comment_string}
'Simple Double Wishbone Suspension'
$--------------------------------------------TEMPLATE_HEADER
[TEMPLATE_HEADER]
MAJOR_ROLE = 'suspension'
TIMESTAMP = '1999/07/15,17:21:32'
HEADER_SIZE = 5
You should remove all the lines from the beginning of the file up to, and including, the line containing
the HEADER_SIZE attribute.
Modifying Adams/View Variables
Templates and test rigs in template-based products have information that is stored in Adams/View
variables to determine how the template is used. All templates, including test rigs, have three required
variables: major role, minor role, and model class. Test rigs, however, have an additional required
Adams/View variable called test rig class.
When you create the test-rig template, your template-based product automatically creates the first three
variables. You must, however, manually create the last variable, the test rig class variable.
The following sections introduce the variables:
Major Role
Minor Role
Model Class
Test-Rig Class
Major Role
The major role of templates and test rigs is stored in an Adams/View variable called role. The major role
of a test rig is always analysis.
When creating a test rig, make sure that you set the major role as shown next:
variable create &
variable_name = .__acme_4PostRig.role &
string_value = "analysis" &
comments = "Memory for Adams/Car major role"
Minor Role
The minor role of templates and test rigs is stored in an Adams/View variable called minor_role. The
minor role of a test rig is typically any. Setting the minor role to any is veryimportant if you are designing
a test rig that is supposed to work with other subsystems that can have different minor roles.
In Adams/Car for example, a suspension test rig should work with either front, rear, or trailer-type
suspensions. If the minor role of the test rig were defined as front, the test rig would hook up only to front
suspensions.
Building Models
Set the minor role as shown next:

variable create &
variable_name = .__acme_4PostRig.minor_role &
string_value = "any" &
comments = "Memory for Adams/Car minor role"
Model Class
Every assembly in template-based products has a specific model class. The model class of an assembly
is stored in an Adams/View variable called model_class. Your template-based product automatically
creates this variable when you create the assembly.
Currently, in template-based products, there are four model classesdefined: template, subsystem, testrig,
and assembly.
Set your model class as shown next:
variable create &
variable_name = .__acme_4PostRig.model_class &
string_value = "testrig" &
comments = "Memory for Adams/Car model class"
Test-Rig Class
You can associate any test rig with a particular class of assembly. In Adams/Car for example, the test rig
.__MDI_SUSPENSION_TESTRIG is associated with suspension assemblies. The assembly class of a
test rig is stored in an Adams/View variable called testrig_class.
Set the test rig class as shown next:
variable create &
variable_name = .__acme_4PostRig.testrig_class &
string_value = "full_vehicle" &
comments = "Memory for Adams/Car testrig class"
You can reference the variable testrig_class directly from the graphical user interface. In Adams/Car for
example, this variable is used in the suspension assembly and the full-vehicle assembly dialog boxes.
Each of these two dialog boxes contains an option menu from which you can select the test rig to be
included in the new assembly. The option menu will only contain test rigs that are compatible with the
particular class of assembly you specified.
The following steps shows how you can reference testrig_class from the Adams/Car interface. You can
follow the same basic steps for the other template-based products.
To reference testrig_class from the Adams/Car interface:
1. From the File menu, point to New, and then select Suspension Assembly.
2. Press F1 and then follow the instructions in the dialog box help for New Suspension Assembly.
3. Select OK.
57
58 Adams/Car
Adding Test-Rigs to Binaries in Adams/Car

Adding a test rig to your private or site binary makes it available for use whenever you start a private or
site session.
You should move the test rig you modified from the template table (templates.tbl) in your template-based
product databases to a directory that contains the source for the custom private or site binary file.
Typically, you will need to create custom analysis macros that work with the new test rig. All these files
should be located in the same directory structure.
For example, you could enter this command in the acar_build.cmd file to read the test rig:
file command read &
file=(eval(getenv("MDI_ACAR_SITE")//"/analysis/models/acme_4PostRig.cmd"))
When you add this command to the acar_build.cmd file, Adams/Car reads in and stores the test rig in the
private or site binary, making the test rig available for use whenever you start an Adams/Car private or
site session.
As as additional option, you can rename your test rig file from the .tpl extension to a .cmd extension to
reflect the fact the test rig is now a command file.
Building Models
Communicators
Communicators are the key elements in template-based products that enable the exchange of information
between subsystems, templates, and the test rig in your assembly.
An assembly requires two directions of data transfer between its subsystems. To provide for these two
directions of data transfer, the template-based products have two types of communicators:
Input communicators - Request information from other subsystems or test rigs.
Output communicators - Provide information to other subsystems or test rigs.
In Adams/Car for example, a mount communicator in the rack and pinion steering templates outputs the
rack part name so that tie rods of suspension templates can attach to the rack. In addition, a mount
communicator in the steering template inputs a part name. The steering template uses the part name to
determine where to attach the steering column.
Learn more about communicators:
Creating/Modifying Input Communicators
Creating/Modifying Output Communicators
Communicator Entity Class
Communicator Roles
Communicator Naming
Matching Communicators During Assembly
Displaying Communicator Information
Testing Communicators
Creating/Modifying Input Communicators

You can create or modify input communicators as explained next. You must be in template-builder mode
to do this.
To create/modify input communicators:
1. From the Build menu, point to Communicator, point to Input, and then select New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Create/Modify Input
Communicator.
3. Select OK.
Creating/Modifying Output Communicators

You can create or modify output communicators as explained next. You must be in template-builder
mode to do this.
59
60 Adams/Car
To create/modify output communicators:

1. From the Build menu, point to Communicator, point to Output, and then select New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Create/Modify Output
Communicator.
3. Select OK.
Communicator Entity Class

The class of a communicator indicates the kind of information it exchanges. For example, communicators
of the class marker exchange a location and an orientation through a construction frame name and a part
name. The classes of communicators and the information that each class exchanges are listed in table
Communicator Entity Class. The classes apply to both input and output communicators.
In Adams/Car, and Adams/Driveline, communicators can be either single or be part of a symmetrical
pair, either left or right. The table below provides additional information about entity classes.
The class:
Exchanges:
The following entity classes do not have symmetry and, therefore, are always single, by default:
Array
Adams/Solver array name.
Differential equation Differential equation name.

Motion Mot
Parameter Variables
Spline Splin
Solver variable
ion name.
Parameter variable name.
e name.
Adams/Solver variable name. You must use an Adams/Solver variable, not an
Adams/View variable. Unlike an Adams/View variable, an Adams/Solver
variable's computation occurs during analysis. Your template-based product
generates Adams/Solver variables as state variables.
The following entity classes have symmetry:

Mount
Part name to provide connections between subassemblies. As a shortcut, the

template-based products also automatically create input mount
communicators when you create a mount part.
Marker
Creation of a marker output communicator results in the creation of a new

marker whose location is defined by a user-input construction frame and which
is located on a user-input part. The identity of this marker is passed through
this communicator to provide both location and part information. If the
construction frame is part of a symmetrical pair, the template-based products
create an input communicator for each construction frame in the pair.
Joint Join
t name.
Joint-for-motion Join
t name.
Building Models
The class:
Exchanges:
Bushing Bus
Location
Part Par
hing name.
The location of the named hardpoint or construction frame. If the hardpoint is
part of a symmetrical pair, the template-based products create two input
communicators, one for each hardpoint in the pair.
t name.
Orientation The
orientation of the named construction frame.
Real parameter
A parameter variable name of the type real.
Integer parameter
A parameter variable name of the type integer.
Communicator Minor Roles

Each communicator has a minor role. A minor role defines the communicator's position in the assembly.
The template-based products provide you with minor roles, as shown in the following table:
This template-based
product:
Adams/Car
Has these communicator minor roles:

any
inherit
front
rear
trailer
You can define a communicator's minor role when you create it. For example, if you want to provide
input to or output from subsystems of specific roles, then you set the minor role for communicators when
you create them. We recommend, however, that you do not set a communicator's minor role. Instead, let
the subsystem determine the minor role by setting it to inherit, in which case the communicator inherits
the minor role from the subsystem in which it is embedded. For example, in Adams/Car a suspension
template might be used to define either a front or rear suspension subsystem. By letting the subsystem
determine the minor role, the assembly process attaches a steering systemto the front suspension and not
to the rear.
Communicator Naming
After you create a communicator, your template-based product assigns a prefix to the name. For
example, it creates a prefix, cil_ where:
ci indicates it is an input communicator. If it were an output communicator, the template-based
product would use co.
61
62 Adams/Car
l indicates it is for the left side of a symmetrical pair. If it were for the right side, the template-
based product would use an r. If it were a single communicator, it would have an s (cis).
If you create a mount part, your template-based product automatically creates an input communicator of
the class mount. It uses the name of the mount part as the name of the communicator and appends the
prefix ci[lrs]_ to it, depending on whether or not it is a left, right, or single communicator. For example,
if you create a mount part of mtl_rack_mount, your template-based product creates an input
communicator with the name cil_rack_mount, where the l indicates it is for the left side.
As you name communicators, you should ensure that any input and output communicators that exchange
information have identical matching names. In Adams/Car for example, the name you give to
communicators that exchange a part name during assembly might be ci_strut_mount and
co_strut_mount, each of which has a matching name of strut_mount. In addition, if you are working with
MSC.Software templates, you must ensure that you use the same naming conventions as the
MSC.Software templates. Learn about matching communicators.
Matching Communicators During Assembly

For a pair of communicators to exchange information during assembly, the communicators must:
Have identical matching names.
Be of opposite types (one input, one output).
Be of the same symmetry type (left, right, or single).
Be of the same class (exchange the same type of information).
Have the same minor role or be assigned a role of any.
If all pieces of information match, your template-based product determines an input/output

communicator pair.
If an input communicator does not have a corresponding output communicator, your template-based
product returns a warning message, and, if the input communicator belongs to the class mount, the
template-based product assigns the mount part to ground. You can still analyze the model even if it does
not have matching communicators. In fact, you may find this helpful if you want to run an analysis of a
subsystem without attaching another subsystem to it.
In Adams/Car for example, the following pairs of input and output communicators match and exchange
a part name during assembly.
Sample of Matching Input and Output Communicators
The pair:
Belongs to the class:
cil_strut_mount m
ount
col_strut_mount m
ount
cil_strut_mount m
ount
From minor role:
To minor role:
front
front
any
Building Models
The pair:
Belongs to the class:
col_strut_mount m
ount
cil_strut_mount m
ount
col_strut_mount m
ount
From minor role:
To minor role:
front
front
any
You can match an input communicator with only one output communicator. You can, however, match an
output communicator with any number of input communicators.
You should always check the warning messages during the assembly, especially if the warning refers to
an input communicator of class mount that does not get assigned and is, therefore, attached to ground.
Displaying Communicator Information

You can display information about communicators in each template or test rig. The communicator
information includes the names of the communicators, their classes, and minor roles. You can choose to
display all types and classes of communicators in the templates and test rigs or display only a specified
set of types and classes.
To display information about communicators:
1. From the Build menu, point to Communicator, and then select Info.
2. Press F1 and then follow the instructions in the dialog box help for Communicators Info.
3. Select OK.
Information window appears. It displays the communicator information for each template or test
rig, grouped by each class of communicator that you selected.
Testing Communicators
You can perform a test to verify that you have correctly specified input and output communicators in your
template. You can use this test to determine whether or not you need to add or modify communicators to
correctly create an assembly.
When you perform the test, you specify the model names of one or more existing templates or test rigs.
Although you can specify a single template, you should specify all the templates containing
communicators that transfer information between the selected template. You must specify a minor role
for each template, subsystem, or test rig you chose to test.
After you perform the test, your template-based product lists the matching input and output
communicators, the unmatched input communicators, and the unmatched output communicators for the
templates, subsystems, and test rigs you selected. You can save the test information to a file.
To test communicators:
1. From the Build menu, point to Communicator, and then select Test.
63
64 Adams/Car
2. Press F1 and then follow the instructions in the dialog box help for Test Communicators.
3. Select OK.
The Information window appears. It contains a list of the communicators that match other
communicators and a list of those that do not. It shows the matched communicators followed by
the unmatched communicators. The lists include the names of the input and output
communicators and the names of the templates to which they belong. Often, you'll see many
communicators that are unmatched. Many of these communicators are related to subsystems or
test rigs that you do not currently have open.
If you want to fully test the communicators in your template, you should open the other templates
with which you want the template to communicate. In Adams/Car for example, if you are creating
a suspenion template, the template must be able to communicate with a steering template and the
suspension test rig.
Working with Components
66 Adams/Car
Introducing the Components

The template-based products offer a number of component definitions that allow you to quickly and
efficiently create components such as springs, dampers, and tires in the Template Builder. This allows the
expert user to generate complex components without being overly concerned with the underlying
elements, such as parts, markers, and geometry.
Components provide the building blocks required to define topological systems. Components are
designed to be intuitive, to allow you to create templates quickly and easily.
The expert user can create, modify, and delete components using the Template Builder. In the Standard
Interface, either the standard or the expert user can only modify components. Learn about user access.
The components within a template are parametrically defined such that you can use a single template to
represent numerous subsystems.
General Information About Components

Creating Components
Modifying Components
Deleting Components
About the Naming Convention
Information About a Particular Component

Hardpoints
Construction Frames
Parts
Markers
Geometry
Attachments
Forces
Wheels, Adjustable forces and Gears
Actuators
Condition Sensors
Feedback Channels
Data Elements, Requests and Variables
Creating Components
You can create components only in the Template Builder. The Template Builder design leads you through
a step-by-step process for creating components: the Build menu is organized such that you can start at
the top of the menu, building basic components, and work your way down, attaching these basic
components together and building increasingly complex components.
For information about a certain component, see the topic for that component.
The following example shows how you can create arm geometry. You follow the same basic steps to
create any other component listed under the Build menu.
To create arm geometry:
1. From the Build menu, point to Geometry, point to Arm, and then select New.
2. Press F1 and then follow the instructions in the dialog box help for Create/Modify Arm Geometry.
3. Select one of the following:
OK if you want to execute the command and close the dialog box.
Apply if you want to execute the command butkeep the dialog box open so you can continue
to work in it.
Cancel if you decide not to execute the command and close the dialog box.
Modifying Components
Depending on the component you want to modify, one or more of the following methods will be
available:
Modifying Component Parameters
Modifying Component Property File
Replacing Instance Definition
Modifying Component Parameters

You can modify component parameters in either interface, as follows:
In the Template Builder - After you create components in the Template Builder, you can
modify any of their parameters, as needed.
In the Standard Interface - The standard user can reference an existing template by either
opening or creating a subsystem file. The standard user can modify only selected parameters in
the Standard Interface.
The following examples show how you can modify component parameters in either interface. You use
the same basic steps to modify any components parameters.
In Standard Interface, to modify arm geometry:
1. Right-click an arm geometry, and then select Modify.
2. Press F1 and then follow the instructions in the dialog box help for Modify Arm.
3. Select OK.
67
68 Adams/Car
Note:
You can only change a limited number of parameters in the Standard Interface.
In Template Builder, to modify arm geometry:

1. From the Build menu, point to Geometry, point to Arm, and then select New/Modify.
3. Select OK.
Modifying Component Property File
You can modify property files using either of the following:
Any text editor - When working in any of the template-based products, you can open a text
editor, such as vi on UNIX and Notepad on NT, display the property file referenced by the
component you want to change, modify any of the parameters as needed, and then save your
changes.
The Curve Manager - You can modify some property files as explained in Modifying Property
Files Using the Curve Manager.
Modifying Property Files Using a Text Editor

If you want to modify a property file using a text editor, you can find the location of the particular
database that a property file uses by following the steps outlined next.
To find the location of a database:
From the Tools menu, point to Database Management, and then select Database Info. The
Information window appears, displaying the path of the database.
Modifying Property Files Using the Curve Manager
You can use the Curve Manager to modify a select set of property files.
To modify Adams/Car property files:
1. From the screen, right-click the component you want to modify, for example a spring, point to the
component name, and then select Modify.
The Modify Spring dialog box appears.
2. Select the Curve Manager tool
The Curve Manager appears.

3. Change any parameters as needed.
Replacing Instance Definition
Another way of modifying components is to change the definition of the component you are using with
another definition of the same component. For example, you can replace a coil spring with an air spring.
The following example shows how you can change a component's definition. You follow the same basic
steps to change the definition of other components.
Components currently supported include: air spring, bushing, damper, and spring, as well as applicationspecific components.
Note:
In Adams/Car you can change the component definition only in the Standard Interface.
To change component definition:

1. In Standard Interface, right-click a component, point to its name, and then select Replace
Instance.
2. Press F1 and then follow the instructions in the dialog box help for Replace Instance Definition.
3. Select OK.
Deleting Components
You can delete components only in the Template Builder. If you try to delete a component that is
dependent on other components, your template-based product informs you that the component is
dependent on others, and if you delete it, the dependents also are deleted.
Because not all the components you can create and delete in the Template Builder have a graphical
representation, you cannot delete some components by right-clicking on them. The following procedures
explain how you can delete both types of components: those that have a graphical representation as well
as those that dont.
To delete components that do not have graphical representation:
1. From the Build menu, point to the component you want to delete, and then select Delete.
The appropriate Delete dialog box appears.
2. Fill in the dialog box as appropriate, and then select either of the following:
OK if you want to execute the command and close the dialog box.
Apply if you want to execute the command butkeep the dialog box open so you can continue
to work in it.
Your template-based product does one of the following:

Deletes the component.
Checks if the component has dependencies, and if the component does have dependencies, it
informs you and gives you three options:
Proceed with the delete command

Highlight and list the dependents
Cancel the delete command
69
70 Adams/Car
To delete components that have graphical representation:

Do one of the following:
Right-click the component you want to delete from the screen, point to the component name,
and then select Delete.
Complete steps 1 and 2, above.
Your template-based product does one of the following:

Deletes the component.
Checks if the component has dependencies, and if the component does have dependencies, it
informs you and gives you three options:
Proceed with the delete command

Highlight and list the dependents
Cancel the delete command
About the Naming Convention

The template-based products use a naming convention to allow you to easily determine a components
type from it name. When you create a new component in the Template Builder, your template-based
product automatically adds a prefix based on the component type and symmetry. The first two letters of
the prefix indicate the component type. The third letter indicatesthe symmetric information of the entity.
This letter can be l, r, or s, indicating left, right, or single, respectively.
The exception to this rule is the prefix for geometry entities, where the first three letters are always gra.
The next three letters describe the type of geometry. These letters can be arm, cyl, ell, lin, and out,
corresponding to the following types of geometry: arm, cylinder, ellipse, link, and outline.
The following table lists the prefixes associated with the Template Builder entities. The list is sorted
alphabetically by prefix.
Prefix:
Entity type:
bg[lrs]_
Bushing (always active)
bk[lrs]_
Bushing (kinematically inactive)
bu[lrs]_
Bumpstop (Adams/Car only)
cf[lrs]_ Constr
ci[lrs]_ Input
co[lrs]_ Output
css_ Condition
da[lrs]_
fb[lrs]_ F
ff[lrs]_ User
uction frame
communicator
communicator
sensor
Damper (Adams/Car only)
lexible body
-function feedback channel
Prefix:
ge[lrs]_ G
gk[lrs]dif_ Gear
Entity type:
eneral part
differential (kinematically active)
gk[lrs]red_ G
ear reduction (kinematically active)
gp[lrs]_ G
eneral parameter
gr[lrs]dif_ Gear
differential (always active)
gr[lrs]red_ Gear
reduction (always active)
graarm Arm
geometry
gracyl_ C
graell_ Ellipse
ylinder geometry
geometry
gralin_ Li
nk geometry
graout_ O
utline geometry
gs[lrs]_ Gener
al spline
gv[lrs]_ G
eneral variable
hp[lrs]_ H
ardpoint
ip[lrs]_ Interface
jf[lrs]_
jk[lrs]_ Jo
part
Joint force actuator
int (kinematically active)
jm[lrs]_
Joint motion actuator
jo[lrs]_
Joint (always active)
mt[lrs]_ M
nr[lrs]_ Nonlinear
ount part
rod
ns[lrs]_ Spring
ph[lrs]_ H
idden parameter variable
pt[lrs]_ P
oint torque actuator
pv[lrs]_ P
arameter variable
re[lrs]_
sw[lrs]_ Switch
ti[lrs]_
ue[lrs]_ U
wh[lrs]_
Reboundstop (Adams/Car only)

part
Tire force (Adams/Car only)
ser-defined entity
Wheel part (Adams/Car only)
71
72 Adams/Car
Hardpoints
Hardpoints contain location information and are the basic building blocks for most other components.
Hardpoints have no orientation. If you need components that hold both location and orientation
information, use construction frames.
Hardpoints and construction frames are also referred to as coordinate references.
You use the Template Builders Build menu to create, modify, and delete hardpoints. When you create
hardpoints, you can define them symmetrically or as a single point in space. When defining hardpoints
symmetrically, you could, for example, define a left hardpoint and the right hardpoint is automatically
generated as a parametric point.
Creating a Hardpoint
To create a hardpoint:
1. From the Build menu, point to Hardpoint, and then select New.
2. Press F1 and then follow the instructions in the dialog box help for Create Hardpoint.
3. Select OK.
Modifying a Hardpoint
In Standard Interface, to modify a hardpoint:
1. From the Adjust menu, point to Hardpoint, and then select Modify.
2. Press F1 and then follow the instructions in the dialog box help for Modify Hardpoint Location.
3. Select OK.
In Template Builder, to modify a hardpoint:
1. From the Build menu, point to Hardpoint, and then select Modify.
2. Press F1 and then follow the instructions in the dialog box help for Modify Hardpoint Location.
3. Select OK.
Modifying Several Hardpoints at a Time
If you want to modify several existing hardpoints at a time, you can use a table editor to do so.
In Standard Interface, to modify several hardpoints at a time:
1. From the Adjust menu, point to Hardpoint, and then select Table.
2. Press F1 and then follow the instructions in the dialog box help for Hardpoint Modification Table.
3. Select Apply.
In Template Builder, to modify several hardpoints at a time:
1. From the Build menu, point to Hardpoint, and then select Table.
2. Press F1 and then follow the instructions in the dialog box help for Hardpoint Modification Table.
3. Select Apply.
73
74 Adams/Car
Construction Frames
Construction frames contain both location and orientation information, and are the basic building blocks
for many other components. When you need only location and no orientation information, hardpoints are
the correct components to use.
Hardpoints and construction frames are also referred to as coordinate references.
You can define construction frames symmetrically. To easily locate and orient construction frames
without having to worry about complex rotations and translations, you can use various options:
Summary of Location Dependency Options
Summary of Orientation Dependency Options
To create or modify a construction frame:

1. From the Build menu, point to Construction Frame, and then select New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Create/Modify Construction
Frame.
3. Select OK.
Parts
You can build the following types of parts in Template Builder:
General Parts
Interface Parts
Flexible Bodies
Nonlinear Beams
Mount Parts
Switch Parts
General Parts
A general part is arigid part that is defined by its location, orientation, mass, inertia, and center ofgravity.
Note that the computed mass properties are not parametric. Your template-based product does not update
the mass properties when the geometry changes, if hardpoints have changed position, for example. If you
want to have the part mass re-computed based upon a parts geometry, you must explicitly have your
template-based product compute the mass properties based on the changed geometry by calculating the
mass for the general part, using the Build or Adjust menus. Alternatively, you can change the mass
properties to user-defined values by modifying the general part using the Build or Adjust menus.
In the Standard Interface, general parts are enhanced to be either rigid or flexible. Learn about flexible
parts.
Creating or Modifying a General Part

In Standard Interface, to create or modify a general part:
1. From the Adjust menu, point to General Part, and then select Modify.
2. Press F1 and then follow the instructions in the dialog box help for Modify General Part.
3. Select OK.
In Template Builder, to create or modify a general part:
1. From the Build menu, point to Parts, point to General Part, and then select New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Create/Modify General Part.
3. Select OK.
Calculating the Mass of a General Part
You can calculate the mass based on material properties (steel, aluminum, and so on) or enter a material
density. The mass will be based on the volume of the associated geometry.
75
76 Adams/Car
To calculate the mass of a general part:

From the Build menu, point to Parts, point to General Part, and then select Modify.
From create/modify dialog boxes, select
.
Using the General Part Wizard

You can use the general part wizard to create simple geometry. Using the general part wizard allows the
Template Builder to automatically calculate mass and inertia properties. You can create either a link or
an arm and choose the material properties.
To use the general part wizard:
1. From the Build menu, point to Parts, point to General Part, and then select Wizard.
2. Press F1 and then follow the instructions in the dialog box help for General Part Wizard.
3. Select OK.
Interface Parts
Interface parts let you connect flexible bodies to the rest of your template. You cannot use joints or
bushings to connect general parts and flexible bodies: you must use interface parts.
To create or modify interface parts:
1. From the Build menu, point to Parts, point to Flexible Body, point to Interface Part, and then
select New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Create/Modify Interface Part.
3. Select OK.
Flexible Bodies
Template-based products use descriptions of flexible bodies, named modal neutral files (MNF), from a
finite element (FEM) program. The MNF is a binary, platform-independent file that combines compact
storage and efficiency of data access.
The information in an MNF includes:
Geometry (locations of nodes and node connectivity)
Nodal mass and inertia
Mode shapes
Generalized mass and stiffness for mode shapes
The Template Builder uses a method of modeling flexible bodies named modal flexibility. Modal
flexibility assigns a set of mode shapes (eigenvectors) to a flexible body. The principle of linear
superposition is then used to combine the mode shapes at each time step to reproduce the total
deformation of the flexible body. This method can be very useful in problems that are characterized by
high elasticity and moderate deflections.
In Standard Interface, to modify a flexible body:
1. If the displayed subsystem or assembly has a flexible part, from the Adjust menu, point to
Flexible Body, and then select Modify.
2. Press F1 and then follow the instructions in the dialog box help for Modify Flexible Body.
3. Select OK.
In Template Builder, to create or modify a flexible body:
1. From the Build menu, point to Parts, point to Flexible Body, and then select New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Create/Modify Flexible Body.
3. Select OK.
Nonlinear Beams
A nonlinear beam consists of one cylindrical/rectangular segment or several segments connected to each
other at coordinate references. The cylindrical/rectangular elements can have hollow cross sections to
represent pipes. The segments form a shaft with a stiffness appropriate to the cross-sectional area and
material stiffness.
Using a nonlinear beam offers you a quick and easy way to deliver flexibility during early design stages.
The mass and inertia properties of a nonlinear beam are determined according to the outer radius, inner
radius, and material type, with the cylinder wall thickness = (outer radius - inner radius).
Nonlinear beams can be:
Rigid - A rigid nonlinear beam is a sequence of cylinders that belongs to one part. You can use
rigid nonlinear beams to model links that do not have a simple straight-line shape.
Flexible - For a flexible nonlinear beam, your template-based product creates a separate part for
each hardpoint you specify. Your template-based product cuts into two pieces the cylinder
between two hardpoints, with each belonging to one of the two parts associated with the
hardpoints. The two halves are then connected elastically by a beam element. You can use
flexible nonlinear beam to model components such as anti-roll bars.
To create or modify a nonlinear beam:

1. From the Build menu, point to Parts, point to Nonlinear Beam, and then select New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Create/Modify Nonlinear
Beam.
3. Select OK.
77
78 Adams/Car
Mount Parts
A mount part is a massless part that acts as an alias for another part in a separate template. You can use
this alias part as you would use the real part when creating joints, springs, contacts, and so on. A mount
part is fixed to ground by default. If there are matching communicators of type mount found during the
assembly process, the template-based product fixes the mount part to the part specified as the value of
the corresponding output communicator.
To create or modify a mount part:
1. From the Build menu, point to Parts, point to Mount, and then select New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Create/Modify Mount Part.
3. Select OK.
Switch Parts
A switch part is a massless part that enables flexible topology. You can use this switch part as you would
use any real part when creating joints, springs, bushings, and so on. Your template-based product has a
list of real parts related to each switch part. At any time, the switch part is fixed to one and only one of
the parts on the part list.
A switch part lets you explore two different topological solutions. For example, a suspension may
connect either directly to a chassis or to a subframe, depending on the subsystems active during assembly.
The switch part makes these topological solutions possible. Following assembly, switch parts are
automatically deleted.
When you choose a new part in the Switch to Part pull-down menu, the switch part changes the part it is
fixed to, and all the joints and forces acting on the switch part will act on the new part. The switch part
concept allows you to model and investigate different topologies.
Creating or Modifying Switch Parts
In Standard Interface, to modify a switch part:
1. From the Adjust menu, select Switch Part.
2. Press F1 and then follow the instructions in the dialog box help for Modify Switch Part.
3. Select OK.
In Template Builder, to create or modify a switch part:
1. From the Build menu, point to Parts, point to Switch, and then select New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Create/Modify Switch Part.
3. Select OK.
Removing Switch Parts

To remove a switch part:
1. From the Tools menu, select Remove Switch Part.
2. Press F1 and then follow the instructions in the dialog box help for Switch and Remove Switch
Parts.
3. Select OK.
79
80 Adams/Car
Markers
A marker defines a local coordinate system on any part in your model or on ground. A marker has a
location (the origin of the coordinate system) and an orientation.
To create or modify a marker:
1. From the Build menu, point to Marker, and then select New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Create/Modify Marker.
3. Select OK.
Geometry
Geometry components in the template-based products allow you to easily build parametric
representations of standard parts. If mass and inertia information is unavailable, you can automatically
calculate the mass of the general part based on the size of the geometry.
You can build the following geometry components:
Arm Geometry
Link and Cylinder Geometry
Ellipsoid Geometry
Outline Geometry
Note that the computed mass properties, based on geometry, are not parametric. Your template-based
product does not update the mass properties when the geometry changes, if hardpoints have changed
position, for example. If you want to have the part mass re-computed, based upon a parts geometry, you
must explicitly have your template-based product compute the mass properties based on the changed
geometry, by Calculating Mass for the General Part, using the Build or Adjust menus. Alternatively, you
can change the mass properties to user-defined values by modifying the General Part, using the Build or
Adjust menus.
Arm Geometry
An arm part is a solid triangular plate defined by three coordinate references and a thickness. If
necessary, you can automatically update the mass and inertia properties of the general part.
In Adams/Car, you could use the arm geometry to view the control arm of a MacPherson suspension.
In Standard Interface, to modify arm geometry:
1. Right-click an arm geometry, and then select Modify.
2. Press F1 and then follow the instructions in the dialog box help for Modify Arm.
3. Select OK.
In Template Builder, to create or modify arm geometry:
1. From the Build menu, point to Geometry, point to Arm, and then select New/Modify.
3. Select OK.
Link and Cylinder Geometry

The link and cylinder geometry are very similar. The only differences exist in the method used to define
the geometry:
81
82 Adams/Car
The link geometry consists of a cylinder whose ends you define using two hardpoint locations
and a radius. You can use links to view the tie rods of certain suspensions.
You define the cylinder using a construction frame, rather than two hardpoints. The centerline of
the cylinder follows the z-axis of the construction frame. You can define the cylinder so that it
has length in both the positive and negative z-axis. You can use cylinders to view the strut rods
of certain suspensions.
If necessary, you can automatically update the mass and inertia properties of the general part.
Creating or Modifying Link Geometry
In Standard Interface, to modify link geometry:
1. Right-click a link, and then select Modify.
2. Press F1 and then follow the instructions in the dialog box help for Modify Link.
3. Select OK.
In Template Builder, to create or modify link geometry:
1. From the Build menu, point to Geometry, point to Link, and then select New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Create/Modify Link Geometry.
3. Select OK.
Creating or Modifying Cylinder Geometry
To create or modify link geometry:
1. From the Build menu, point to Geometry, point to Cylinder, and then select New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Create/Modify Cylinder
Geometry.
3. Select OK.
Ellipsoid Geometry
An ellipsoid geometry is defined by a coordinate reference and a user-specification of x, y, and z
dimensions. You can use ellipsoids to represent spherical elements of your template. A sphere is an
ellipsoid whose x, y, and z radii have the same values.
You can use two different methods of defining an ellipsoid:
Use a link to define the radius and then specify a scaling factor in each of the orthogonal axes
Define a measurement in each axis
If necessary, you can automatically update the mass and inertia properties of the general part.
To create or modify ellipsoid geometry:

1. From the Build menu, point to Geometry, point to Ellipsoid, and then select New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Create/Modify Ellipsoid
Geometry.
3. Select OK.
Outline Geometry
You can use the outline to draw a line between different hardpoint locations. You can choose to define
either an open or a closed outline. In general, you would use outlines to visualize the general form of
parts. For example, you would add outline geometry to represent the subframe of a vehicle.
Because the geometry entity has no thickness, you cannot update the mass and inertia properties of an
outline.
To create or modify outline geometry:
1. From the Build menu, point to Geometry, point to Outline, and then select New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Create/Modify Outline
Geometry.
3. Select OK.
83
84 Adams/Car
Attachments
When working with template-based products, you can use two types of attachments:
Joints
Bushings
Joints
Joints define a rigid connection between two parts and help define the motion of the parts. The following
table lists the joints the template-based products support, along with information about their degrees of
freedom (DOF):
Joint name:
Number of DOF:
Type of motion DOFs allow:
Translational
Translation of one part with respect to another while all

axes are co-directed.
Revolute
Rotation of one part with respect to another along a

common axis.
Cylindrical
Translation and rotation of one part with respect to

another.
Spherical
Three rotations of one part with respect to the other while

keeping two points, one on each part, coincident.
Planar
The x-y plane of one part slides with respect to another.
Fixed
No motion of any part with respect to another.
Inline
One translational and three rotational motions of one part

with respect to another.
Inplane
Two translational and three rotational motions of one part

Orientation
Constrains the orientation of one part with respect to the

orientation of another one, leaving the translational
degrees of freedom free.
Parallel_axes
Three translational and one rotational motions of one part

Perpendicular
Three translational and two rotational motions of one part

Convel
Two rotations of one part with respect to the other while

remaining coincident and maintaining a constant velocity
through the spin axes.
Hooke
Two rotations of one part with respect to the other while

remaining coincident.
You can use different parametric orientation options to define the location and direction of the joint.
To create or modify a joint:
1. From the Build menu, point to Attachments, point to Joint, and then select New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Create/Modify Joint
Attachment.
3. Select OK.
Working with Bushings

Bushings provide a six degree-of-freedom force relationship for connecting two components. The force
is applied between a marker on each component. The force depends on the relative displacement, and (in
the case of hysteretic bushings), the relative velocity of the two markers.
The forces generated due to translational and rotational motion are entirely uncoupled from each other.
In the description of the bushing formulation that follows, you can apply the force dependencies,
described next, to either translational or rotational behavior. Therefore, a statement such asfi = h (relative
displacements, relative velocities) implies the following:
Forces: fi = g (translational displacements, translational velocities)
Moments: fi = h (angular displacements, angular velocities)
Learn about bushings:

Creating and Modifying Bushings
Stiffness Forces Computation
Damping Forces Computation
Bushing Specifications in the Adams Dataset (.adm)
Creating and Modifying Bushings

When working in Template Builder, you can create bushings and then modify them. When working in
Standard Interface, you can only modify bushings. Learn about the Interface Modes.
Nonlinear Bushings
To create a nonlinear bushing:
1. From the Build menu, point to Attachments, point to Bushing, and then select New.
2. Press F1 and then follow the instructions in the dialog box help for Create/Modify Bushing
Attachment.
3. Select OK.
85
86 Adams/Car
To modify a nonlinear bushing in the Template Builder:

1. To display the modify dialog box, do one of the following:
From the Build menu, point to Attachments, point to Bushing, and then select Modify. To load
the parameters for a specific bushing, you must specify the bushing you want to modify.
Right-click a bushing, point to its name, and then select Modify. The dialog box has the bushing
parameters already loaded.
2. Press F1 and then follow the instructions in the dialog box help for Create/Modify Bushing
Attachment.
3. Select OK.
To modify a nonlinear bushing in the Standard Interface:
1. In Standard Interface, right-click a bushing, point to its name, and then select Modify. The dialog
box has the bushing parameters already loaded.
2. Press F1 and then follow the instructions in the dialog box help for Modify Bushing.
3. Select OK.
Linear Bushings
To modify a linear bushing in the Standard Interface:
1. Right-click a bushing, point to its name, and then select Modify. The dialog box has the bushing
2. Press F1 and then follow the instructions in the dialog box help for Modify Linear Bushing.
3. Select OK.
Stiffness Forces Computation
In the expressions that follow:
i, j k, l are indices whose integer values of 1 to 3 indicate application to the x, y, and z coordinate
directions, respectively
All uppercase letters represent constants
The Transformed Displacement, q

Adams/Solver computes the stiffness forces based on a bushing displacement vector, q, which is
determined by transformation to account for any inter-axial coupling. Therefore:
For uncoupled directions
qk = rk
( k > D ) , q is given by:
( k D ) , q is given by:
For coupled directions
q k = m sgn ( r k )
D
with
m =
rl
l=1
and
rk = Hk xk Qk
where the Adams internal variables are:
xk
- Displacement of the modeled bushing in the k direction
rk
- Displacement of the physical bushing in the k direction
qk
- Ordinate (lookup point) in the stiffness force characteristic
- Scalar magnitude of the bushing displacement vector
and the user-specified constants are:
Hk
Qk
- Horizontal (displacement) scaling for the kth direction (disp_scale); can be used to perform unit
conversions
- Displacement offset for the kth direction (disp_offset);can be used to specify an offset between
the modeled bushing and the physical bushing (perhaps caused by the rotational preload
introduced by the assembly process)
This formulation allows the elements of the displacement vector, x, to be scaled up by a user-specified
factor, H, and/or offset by a user-specified displacement offset, Qk, to determine the transformed
displacement vector, qk, which becomes the lookup point in the selected stiffness force characteristic (see
next).
The Stiffness Force, f
For uncoupled directions
( k > D ) , the resulting force, f, is given by:
87
88 Adams/Car
f k = G k V k y k ( q k' v k )
For coupled directions
(k D)
, f, is given by:
f k = G k V k w k y k ( q k' v k )
with .
rk
w k = ------m
Where the Adams internal variables are:
fk
- Stiffness component of the force in the kth direction, determined by accounting for preload,
scaling factors, and inter-axial coupling
yk
- Force returned internally by the user-defined (positive-positive) bushing stiffness

characteristic for the kthdirection
wk
- Weighting of the returned force for the kth direction (0 to 1, for coupled directions only)
Gk
Vk
- Force offset (preload) for the kth direction (force_offset)

- Vertical (force) scaling for the kth direction (stiffness_force_scale)
See the following sections for the precise mathematical descriptions of the two alternative coupling
formulations.
Note about the scaling factors, V and H:
Note:
Regardless of the bushing formulation, a doubling of the scale factor, V, results in a

doubling of the restoring force provided by the bushing for a given displacement in that
direction. In contrast, doubling of H:
Results in a doubling of the restoring force for bushings whose force-displacement
characteristics are linear.
Results in a nonlinear change of the restoring force for bushings whose force-
displacement characteristics are nonlinear.
Expressing the Stiffness Force Characteristic

You can use a number of formulations to express the stiffness force characteristic of the bushing, by
appropriately setting the integer value of stiffness_type (see above), and providing the necessary data in
the .adm file.
Linear
The linear characteristic is straightforward, and is defined using a stiffness, k:
y i ( q i', v i ) = y i ( q i ) = ( k i q i )
Piecewise Linear
The piecewise linear characteristic is defined as:
y ( q, v ) = y ( q ) = k 1 q +
m1
l=1
( k l + 1 k l ) ( q b l ), q > b l
where:
qi -
ki
l
bi
m
Note that
The i-direction component of the (transformed) bushing displacement

- The lth stiffness for the ith direction
- The breakpoint where the stiffness changes between k i
l1
and
- The number of straight-line slopes that describe the characteristic

l+1
bi
> bi
is a necessary condition for all n.
A typical characteristic from this formulation looks similar to the following:
ki
89
90 Adams/Car
Figure 1
Example Piecewise Linear Force-Displacement Characteristic
Smoothed Piecewise Linear

The smoothed piecewise linear definition is similar to the piecewise, but with smoothing across each
change in slope, such that the gradient of the force-displacement curve (for example, the stiffness)
becomes continuous:
dy spw
-------------- = k 1 +
dq
with:
2
( kl + 1 kl ) l ( 3 2l )
l=1
1
m1
l 0
0 < l < 1
l 1
e
q b l ---
2
l = ---------------------------e
where (noting that for clarity, the subscript i, indicating direction, has been dropped):
- The (transformed, scaled and offset) bushing displacement
kl
- The lth stiffness
bl
- The breakpoint (value of displacement) where the stiffness changes between
l1
ki
and
ki
e
- The displacement over whicheach change in stiffness is smoothed to prevent discontinuities

in stiffness
- The number of straight-line slopes that describe the underlying characteristic
This gradient is integrated analytically from zero displacement q, to find the force-displacement curve.
The constant of integration is set such that if there were no smoothing, the curve would pass through the
origin. As smoothing is introduced, this constant of integration (the vertical offset of the forcedisplacement curve) is adjusted such that the smoothed curve continues to overlay the unsmoothed curve
in regions where there is no smoothing (such as those for high values of displacement). Note that this
means that if the origin is contained within a smoothing interval, then the smoothed force-displacement
curve may not pass exactly through the origin, but that you can safely vary the smoothing interval,
knowing that as the displacement moves from a smoothed into an unsmoothed region, the behavior will
converge to that of the unsmoothed piecewise curve.
Note that as with the piecewise formulation,
l+1
bi
> bi
Setting e to zero collapses this formulation to the piecewise formulation.

A typical characteristic from this formulation will look similar to the following (where the plot shows
the effect of varying the smoothing interval from 0.3 mm to 10 mm):
91
92 Adams/Car
Figure 2
Example Force-Displacement Characteristic for a Smoothed Piecewise Linear

Bushing
AKIMA Spline
The nonlinear, AKIMA spline characteristic is defined using a single Adams AKIMA spline. The
restoring force is than determined directly from this spline:
y i ( q i', v i ) = y i ( q i ) = AKISPL ( q i, 0, ID i )
Hysteretic (Dual-Spline)
The hysteretic definition of the stiffness characteristic also incorporates some damping (velocitydependence) of the force, according to the following:
y i ( q i', v i ) = AKISPL ( q i, v i, ID i )
where:
v i = STEP ( p i, P, 1, P, 1 )
with:
p i = A i x i E i
where:
Ai
- Horizontal (velocity) scaling for the ith direction (vel_scale)
Ei
- Velocity offset for the ith direction (vel_offset)
Pi
- Velocity saturation point (m/s) for the i direction (for hysteretic bushings only)
pi
- Scaled and offset velocity in the i direction
vi
x i
- Velocity (rate of change of model bushing displacement) in the i direction

- Transformed, and saturated
x i
Such that, for v < -v, the force_neg_vel_values only are used, and for v > vel_threshold, only the
force_pos_vel_values are used. When v is between these values, the two force characteristics are
interpolated according to the STEP function described above.
Note that for very large values of P, the hysteresis disappears, and the characteristic approaches a simple
displacement-dependent AKIMA spline:
93
94 Adams/Car
y i ( q i', v i ) y i ( q i ) = AKISPL ( q i, 0, ID i )
The following is an example of the typical behavior of a hysteretic bushing, excited to increasing
amplitude:
Figure 3
Displacement
Figure 4
Force
Damping Forces Computation

Adams/Solver computes the damping forces based on a transformed (scaled, and offset) bushing velocity
vector, p, defined as:
where the Adams internal variables are:

- Rate of change of the true bushing displacement, x
Pi
- Scaled and offset bushing velocity (the point in the force lookup)
95
96 Adams/Car
Ai
- Horizontal (velocity) scaling for the ith direction (vel_scale)
Ei
- Velocity offset for the ith direction (vel_offset)
This formulation allows the elements of the true velocity vector,
, to be scaled up by a user-specified
factor H, and/or offset by a user-specified displacement d, to determine the transformed displacement

vector q, which is used as the lookup point in the definition of the stiffness force characteristic for the
bushing.
For each direction, the damping force, c is given by:
where the user-specified constant:

Bi - Is the vertical (force) scaling for the ith direction (damping_force_scale)
Expressing the Damping Force Characteristic
You can use several methods to specify the damping properties in each coordinate direction, as explained
next.
None
This option simply deactivates damping for the given coordinate direction:
Linear
The linear characteristic is straightforward, and is defined using a damping constant, c:
For a linear characteristic, the parameter damping_value should be set equal to the required stiffness, c.
AKIMA Spline
The nonlinear, AKIMA spline characteristic is defined using a single Adams AKIMA spline. The
damping-force characteristic is then determined directly from this spline:
Piecewise Linear
The piecewise linear characteristic is defined as:
where:
qi
- The i-direction component of the (transformed) bushing displacement

- The lth stiffness for the ith direction
- Breakpoint where the stiffness changes between
Note that
and
A typical characteristic from this formulation will look similar to the following:
97
98 Adams/Car
Figure 5
Example Piecewise Linear Force-Velocity Characteristic
Stiffness Fraction ("k-fraction")

The stiffness fraction damping method simply ensures that the damping coefficient increases in
proportion to the local stiffness of the bushing at the current operating point.
The damping force in each direction is determined by first identifying the local stiffness as being the
modulus of the rate of change of the stiffness force in that direction with respect to a displacement in the
same direction. This stiffness magnitude is then multiplied by the k-fraction, k, (damping_value) and
multiplied by the appropriate component of the transformed velocity, p:
For an uncoupled linear bushing (D = 0 or 1, stiffness_type = 1), this reduces to a constant damping
coefficient and a typical viscous damping characteristic.
Learn how the stiffness damping characteristics are expressed in the .adm file.
Bushing Specifications in the Adams Dataset (.adm)

Coupling Specification
Stiffness Force Characteristic
Damping Force Characteristic
Bushings are implemented using a FIE(ld)SUB. This FIESUB reads the bushing specifications directly
from the .adm deck, and returns the total (stiffness plus damping) force, fi + ci, for any six-element
bushing displacement and six-element bushing velocity vector.
Coupling Specification
The value of D for the bushing is specified directly as shape in the FIELD statement for the bushing:
FIELD/id, I=idi, J=idj, FUNCTION=USER(branch, shape, txa, tya, tza, rxa, rya, rza)
where the value of the integer shape may be:
- Rectangular (no coupling). The force in each direction is dependent only on the
displacement in that direction.
- Cylindrical (that is, x-y coupling). The forces in the x and y directions are each dependent
on the displacement of the bushing in both the x and y directions. The force in the z
direction is independent (that is, it depends only on the displacement in z).
- Spherical (that is, x-y-z coupling). The force in each direction depends on the
displacements in all translational directions, and the torque in each direction depends on
the angular displacements in all rotational directions.
Note that the selected shape factor (coupling) always applies to both the translational and rotational
behavior of the bushing.
The next six parameters in the FIELD statement, all of which are required, should contain the Adams
array IDs of the arrays containing the data, which expresses the stiffness and damping characteristic for
the direction:
FIELD/id, I=idi, J=idj, FUNCTION=USER(branch, shape, txa, tya, tza, rxa, rya, rza)
Each of the referenced arrays must be included in the .adm file, and should be in the following form:
ARRAY/id, NUM=
stiffness_type, stiffness_value, stiffness_force_scale,

damping_type, damping_value, damping_force_scale,
force_offset, disp_offset, disp_scale, vel_offset, vel_scale
All of those parameters are required, and are described in detail in the following sections.
Stiffness Force Characteristic
You can use a number of formulations to express the stiffness force characteristic of the bushing, by
appropriately setting the integer value of stiffness_type (see above), and providing the necessary data in
the .adm file.
99
100 Adams/Car
Linear (stiffness_type = 1)
For a linear characteristic, the parameter stiffness_value should be set equal to the required stiffness, k.
Piecewise Linear (stiffness_type = 4)
When you select this stiffness type, you must provide an additional array in the .adm file, and you must
set the value of stiffness_value (see above) equal to the integer Adams ID of that additional array. That
additional array must be of the form:
ARRAY/id, NUMBERS = n, k(0), b(1), k(1), ... , b(n), k(n)
where:
- The number of slopes that define the stiffness characteristic. This number must be
an integer and greater than 1 (note that for bushings with a single slope defining the
stiffness characteristic, the linear stiffness type, stiffness_type = 1, should be used)
b(1) ... b(n)
- The breakpoints. The values of displacement, or of angular displacement, at which

the slope changes. These values must be real and in ascending order, but may be
negative.
b(m)
- The breakpoint where the slope (stiffness) changes from k(m-1), for displacements
lower than b(m), and to k(m) for displacements greater than b(m).
k(0) ... k(n)
- The slopes, all of which must be real and positive for a physical, passive bushing.
Their units are stiffness (force/displacement) or angular stiffness (torque/angular
displacement). Note that k(0) extends to minus infinity and k(n) to plus infinity.
Note that the set k(0), b(1), k(1), ... , b(n), k(n) must contain precisely 2n-1 values, so that the total number
of elements in the array must be 2n.
Smoothed Piecewise Linear (stiffness_type = 5)
When you select this stiffness type, you must provide an additional array in the .adm file, and you must
set the value of stiffness_value (see above) equal to the integer Adams ID of this new array. For the
smoother piecewise characteristic, the new array must be of the form:
ARRAY/ID, NUMBERS = s, n, k(0), b(1), k(1), ... , b(n), k(n)
where:
- The interval over which changes of slope are smoothed. This number must be a real
value greater than zero, in units of displacement.
- The number of slopes that define the stiffness characteristic. This number must be
an integer and greater than 1 (note that for bushings with a single slope defining the
stiffness characteristic, the linear stiffness type, stiffness_type = 1, should be used).
b(1) ... b(n)
- The breakpoints. The values of displacement, or of angular displacement, at which

the slope changes. These values must be real and in ascending order, but may be
negative.
b(m)
- The breakpoint where the slope (stiffness) changes from k(m-1), for displacements
lower than b(m), and to k(m) for displacements greater than b(m).
k(0) ... k(n)
Their units are stiffness (force/displacement) or angular stiffness (torque/angular
displacement). Note that k(0) extends to minus infinity and k(n) to plus infinity.
Note that the set k(0), b(1), k(1), ... , b(n), k(n) must contain precisely 2n-1 values, so that the total
number of elements in the array must be 2n+1.
AKIMA Spline (stiffness_type = 2)
The nonlinear, AKIMA spline characteristic is defined using a single Adams AKIMA spline, specified
by setting stiffness_value equal to the Adams ID of the spline. That spline must be supplied in the dataset,
but can be shared among several directions and/or bushings.
Hysteretic Dual-Spline (stiffness_type = 3)
To specify this stiffness characteristic, the .adm file must include both a two-element array (whose
integer ID is placed in stiffness_value), of the form:
ARRAY/id, NUM = sid, P
where the terms are defined as:
sid
- The Adams ID of the 3D spline that specifies the hysteretic characteristic
- The (positive) velocity threshold above which the bushing characteristic becomes
independent of the velocity
and the associated Adams spline, of the form:

SPLINE/sid,
,X= [displacement_values]
,Y= -1.0, [force_neg_vel_values]
,Y= 1.0, [force_pos_vel_values]
101
102 Adams/Car
Damping Force Characteristic

For the stiffness characteristic, a number of methods exist for specifying the damping properties in each
coordinate direction:
None (damping_type = 0)
This setting of damping_type simply deactivates damping for the given coordinate direction:
Linear (damping_type = 1)
For a linear characteristic, the parameter damping_value should be set equal to the required stiffness, c.
AKIMA Spline (damping_type = 2)
The nonlinear, AKIMA spline characteristic is defined using a single Adams AKIMA spline, specified
by setting damping_value equal to the Adams ID of the spline. The damping force characteristic is then
determined directly from this spline:
Note the sign convention here. Within the spline definition, an increase inx (transformed velocity) should
generally yield an increase in the y value (damping force).
The same Adams AKIMA spline can be used for more than one direction of the same bushing (optionally,
with different scaling), and/or for more than one instance of a bushing within the same model.
Piecewise Linear (damping_type = 3)
When you select this damping type, exactly as with the equivalent stiffness type, you must provide an
additional array in the .adm file, and you must set the value of damping_value (see above) equal to the
integer Adams ID of that additional array. That array must be of the form:
ARRAY/id, NUMBERS = n, k(0), b(1), k(1), ... , b(n), k(n)
where:
- The number of slopes that define the damping characteristic. This number must be
an integer, and greater than 1 (note that for bushings with a single slope defining the
damping characteristic, the linear damping type, damping_type = 1, should be used).
b(1) ... b(n)
- The breakpoints. The values of velocity, or of angular velocity, at which the slope of
the damping characteristic changes. These values must be real and in ascending order,
but may be negative.
b(m)
- The breakpoint where the slope (damping coefficient) changes from c(m-1), for
velocities lower than b(m), to c(m) for velocities greater than b(m)
c(0) ... c(n)
Their units are those of damping (that is, force/velocity) or rotational daming (that is,
torque/angular velocity). Note that c(0) extends to minus infinity and c(n) to plus
infinity.
Note that the set c(0), b(1), c(1), ... , b(n), c(n) must contain precisely 2n-1 values, so that the total number
of elements in the array must be 2n.
Stiffness Fraction ("k-fraction") (damping_type = 4)
For the stiffness-fraction damping characteristic, the parameter damping_value should be set equal to the
required stiffness fraction, k.
103
104 Adams/Car
Forces
You can build the following types of forces in Template Builder:
Springs
Dampers
Bumpstops
Reboundstops
In Template Builder you can also modify air springs.
Working with Springs

A spring element defines a force-displacement relationship between two parts. The spring force acts on
the two parts at user-specified coordinates. The springs force-displacement properties, free length,
number of coils and other parameters are given in the designated property file.
Learn about springs:
Creating and Modifying Springs
About Linear Springs
About Nonlinear Springs
About Spring Property Files
Your template-based product models air springs as simple action-reaction forces between two parts. Each
air spring references an air-spring property file that tabulates spring force against trim load and deflection
from trim length. Trim load is the nominal load in the spring for a given trim length and internal pressure.
Before analysis, your template-based product reads the data from the referenced property file and stores
it in a three-dimensional SPLINE. During analysis, Adams/Solver computes the air-spring force by
interpolating the SPLINE data using the Akima method.
Air springs include an auto-trim feature, where you can specify a desired trim height of the suspension
and the air spring's trim load is automatically adjusted during static equilibrium analysis to achieve the
trim height.
To use an air spring in a subsystem, select a coil spring and use thereplace option from the shortcut menu
to replace the coil spring with an air spring.
Learn about air springs:
Modifying Air Springs
Auto Trim Load
Calculation of Air-Spring Force
Creating and Modifying Springs

When working in Template Builder, you can create springs and then modify them. When working in
Standard Interface, you can only modify springs. Learn about the interface modes.
Nonlinear Springs
To create a nonlinear spring:
1. From the Build menu, point to Forces, point to Spring, and then select New.
2. Press F1 and then follow the instructions in the dialog box help for Create/Modify Spring.
3. Select OK.
To modify a nonlinear spring in the Template Builder:
1. To display the modify dialog box, do one of the following:
From the Build menu, point to Forces, point to Spring, and then select Modify. To load the
parameters for a specific spring, you must specify the spring you want to modify.
Right-click a spring, point to its name, and then select Modify. The dialog box has the spring
2. Press F1 and then follow the instructions in the dialog box help for Create/Modify Spring.
3. Select OK.
To modify a nonlinear spring in the Standard Interface:
1. In Standard Interface, right-click a spring, point to its name, and then select Modify. The dialog
box has the spring parameters already loaded.
2. Press F1 and then follow the instructions in the dialog box help for Modify Spring.
3. Select OK.
Linear Springs
To modify a linear spring in the Standard Interface:
1. Right-click a spring, point to its name, and then select Modify. The dialog box has the spring
2. Press F1 and then follow the instructions in the dialog box help for Modify Linear Spring.
3. Select OK.
About Linear Springs
Your template-based product (using the Adams/Solver SPRINGDAMPER) calculates the spring force
as follows:
Spring Force = - K*(DM(I,J) - OffsetCalc)
where:
105
106 Adams/Car
K - The linear stiffness defined in the spring property file.

DM - The instantaneous distance between the I and J coordinate references.
OffsetCalc - Depends on the free length defined in the spring property file and in the spring
install methods.
Spring Install Methods

The three spring install methods are:
Preload - The desired spring load at the current position of the I and J coordinate references.
Installed Length - The installed length of the spring at the current position of the I and J
coordinate references.
Use Hardpoints - The installed length of the spring equals the distance between the I and J
When you submit the model to Adams/Solver, the spring-damper statement that your template-based
product creates, has the form:
SPRINGDAMPER/id, I=I_id, J=J_id
, K=K
, C=0
, LENGTH=OffsetCalc
, FORCE=0
, TRANSLATIONAL
About Nonlinear Springs
Your template-based product (using the Adams/Solver SFORCE) interpolates a force versus spring
length or spring deflection table using Akima's method.
If you are using a force versus length table, the force is calculated as follows:
Spring Force = AKISPL(OffsetCalc + DM(I, J), 0, Spline)
If you are using a force versus deflection table, the force is calculated as follows:
Spring Force = AKISPL(OffsetCalc - DM(I, J), 0, Spline)
where:
AKISPL - Adams/Solver function that interpolates data stored in a SPLINE.
OffsetCalc - Depends on the free length defined in the spring property file and in the spring install
methods.
DM - The instantaneous distance between the I and J coordinate references.

Spline - A reference to a SPLINE statement.
Spring Install Methods

The three spring install methods are:
Preload - The desired spring load at the current position of the I and J coordinate references.
Installed Length - The installed length of the spring at the current position of the I and J
Use Hardpoints - The installed length of the spring equals the distance between the I and J
When you submit the model to Adams/Solver, the SFORCE statement that your template-based product
creates, has the form:
SFORCE/id, I=I_id, J=J_id
, FUNCTION=AKISPL(OffsetCalc + DM(I_id, J_id), 0, Spline)\
, TRANSLATIONAL
About Spring Property Files
The spring component supports the following types of Property Files:
TeimOrbit linear-spring property files (extension .lsf).
TeimOrbit nonlinear-spring property files (extension .spr). Standard TeimOrbit nonlinear-spring
property files correspond to nonlinear, deflection-based spring formulation, as explained in

About Nonlinear Springs.
XML spring property file. The XML spring property file supports linear and nonlinear force
characteristics and allows you to choose between specifying force versus spring deflection or
spring length, as described in About Nonlinear Springs. You work with XML files in the Property
File Editor.
Modifying Air Springs

To modify an air spring in the Standard Interface:
1. In Standard Interface, right-click an air spring, point to its name, and then select Modify. The
dialog box has the air-spring parameters already loaded.
2. Press F1 and then follow the instructions in the dialog box help for Modify Spring.
3. Select OK.
Auto Trim Load
An Adams/Solver differential equation sets an air spring's trim load. The differential equation calculates
the trim load that corresponds to the desired trim length during static equilibrium analyses. Its value is
then locked to the last valuecalculated during static analyses for all the subsequent transient simulations.
F = USER (1117, trimLength, Imarker, Jmarker)
where:
1117 - Branch ID
trimLength - The desired displacement, as specified in the property file, which you can edit
using the Property File Editor.
107
108 Adams/Car
I/J marker - The air spring's I and J markers of the SFORCE.
Calculation of Air-Spring Force

An Adams/Solver SFORCE computes the air-spring force. The SFORCE function is:
force = AKSIPL((trimLength DM (marker I, marker j)),
(trimLoad), splineID)
where:
AKSIPL - Is the Adams/Solver function that interpolates data using Akimas method.
trimLength - Is the distance between the upper and lower spring seats when the suspension is at
trim height. trimLength is a positive real value read from the air-spring property file.
DM(marker I, marker J) - Is the distance between the upper and lower spring seats.
TrimLoad is the load in the spring when the suspension is at trim height. The load corresponds to
the trim load you specified, or, if you select auto trim load, it corresponds to a differential
equation.
Working with Dampers

A damper defines the force-velocity relationship between two parts. The damper is defined as acting
between user-specified coordinate reference points oneach part, and conformsto the force-velocity curve
described in the designated property file.
Learn about dampers:
Creating and Modifying Dampers
About Linear Dampers
About Nonlinear Dampers
Creating and Modifying Dampers

When working in Template Builder, you can create dampers and then modify them. When working in
Standard Interface, you can only modify dampers.
Nonlinear Dampers
To create a nonlinear damper:
1. From the Build menu, point to Forces, point to Damper, and then select New.
2. Press F1 and then follow the instructions in the dialog box help for Create/Modify Damper.
3. Select OK.
To modify a nonlinear damper in the Template Builder:
To display the modify dialog box, do one of the following:
From the Build menu, point to Forces, point to Damper, and then select Modify. To load the
parameters for a specific damper, you must specify the damper you want to modify.
Right-click a damper, point to its name, and then select Modify. The dialog box has the
damper parameters already loaded.
Press F1 and then follow the instructions in the dialog box help for Create/Modify Damper.
Select OK.
To modify a nonlinear damper in the Standard Interface:

1. Right-click a damper, point to its name, and then select Modify. The dialog box has the damper
2. Press F1 and then follow the instructions in the dialog box help for Modify Damper.
3. Select OK.
Linear Dampers
To modify a linear damper in the Standard Interface:
1. Right-click a damper, point to its name, and then select Modify. The dialog box has the damper
2. Press F1 and then follow the instructions in the dialog box help for Modify Linear Damper.
3. Select OK.
About Linear Dampers
In addition to the standard definition of a damper (based on an AKIMA spline interpolation of a force
velocity two-dimensional spline), Adams/Car offers a linear-damper model. The linear-damper model
allows you to define a single damping term. The force exerted by the damper between the I and J parts
at the desired locations follows the well-known formula:
Force = -c dx/dt
where dx/dt is the time derivative of the radial relative displacement between marker I and marker J.
About Nonlinear Dampers
The force-velocity formula is based on:
VR - Relative velocity of marker I with respect to marker J
Damper property file
Force = akispl(VR(marker i, marker j),0, Spline)

The damper property file defines the two-dimensional spline. The independent variable is the
translational velocity of the I and J markers, and the dependent variable is the force exerted between the
two parts at the I and J marker locations.
109
110 Adams/Car
Working with Bumpstops

A bumpstop defines a force-displacement relationship between two parts. The bumpstop acts between
user-specified coordinate reference points on each part, and conforms to the force-displacement
properties described in the designated property file.
The bumpstop force is activated when the displacement between the two coordinate references exceeds
the clearance defined for the bumpstop.
The force-displacement formula is based on:
Instantaneous distance between the user-specified coordinates defined on each part
Impact length or clearance
Bumpstop property file (polynomial or nonlinear stiffness with or without linear or nonlinear
damping).
Learn about bumpstops:

Creating and Modifying Bumpstops
Calculation of Force Characteristics
About Bumpstop Property Files
Creating and Modifying Bumpstops

When working in Template Builder, you can create bumpstops and then modify them. When working in
Standard Interface, you can only modify bumpstops
To create a bumpstop:
1. From the Build menu, point to Forces, point to Bumpstop, and then select New.
2. Press F1 and then follow the instructions in the dialog box help for Create/Modify Bumpstop.
3. Select OK.
To modify a bumpstop in the Template Builder:
From the Build menu, point to Forces, point to Bumpstop, and then select Modify. To load
the parameters for a specific bumpstop, you must specify the bumpstop you want to modify.
Right-click a bumpstop, point to its name, and then select Modify. The dialog box has the
bumpstop parameters already loaded.
Press F1 and then follow the instructions in the dialog box help for Create/Modify Bumpstop.
Select OK.
To modify a bumpstop in the Standard Interface:

In Standard Interface, right-click a bumpstop, point to its name, and then select Modify. The
dialog box has the bumpstop parameters already loaded.
Press F1 and then follow the instructions in the dialog box help for Modify Bumpstop.
Select OK.

The XML bumpstop property file supports various methods and options for calculating force
characteristics. It supports the following methods to determine the elastic-force component:
polynomial - The formulation of the force is based on a third-order polynomial whose equation
can be expressed as follows:
F elastic = POLY(MAX(0, impact_length DM ( marker i, marker j )), 0,

0, LinearRate, QuadraticRate, CubicRate)
nonlinear (spline based) - The formulation of the force is based on the Akima spline
interpolation of a nonlinear characteristic:
F elastic = akispl(MAX(0, impact_length - DM( marker i, marker j )), 0,

Spline)
The elastic force becomes active only when the instantaneous distance between the markers on the two
parts is less than the impact length. The impact length term depends on the distance type. If you select
Clearance, the impact length becomes:
dmCalc - Clearance
where:
Clearance - Value you specify
dmCalc - Initial displacement computed between the I and J markers
The following figure shows the clearance and impact length.
111
112 Adams/Car
In an XML bumpstop property file, you can also enable a damping characteristic. If you enable the
damping characteristic, the force is dependent on the deflection and velocity of the I and J markers.
Damping (viscous) forces can be:
linear - If you include in the property file a linear damping value other than zero, then the total
force exerted between the I and J parts is equal to the sum of the elastic force specified above and
the following damping force:
Fdamping = STEP MAX(0, impact_length - DM(i,j)), 0, 0, 0.1, dampingRate * VR ( marker i, marker j ))

nonlinear (spline based) - If you include in the property file a nonlinear damping value, then the
total force exerted between the I and J parts is equal to the sum of the elastic force specified
above and the following damping force:
F damping = STEP MAX(0, impact_length - DM(i,j)), 0, 0, 0.1, AKISPL ( VR ( marker i, marker j ), 0, dampingSpline ))
About Bumpstop Property Files

The bumpstop component supports the following types of property files:
TeimOrbit bumpstop property files (extension .bum). Standard TeimOrbit bumpstop property
files correspond to nonlinear elastic forces with linear damping equal to 0 formulation.
XML bumpstop property file. The XML bumpstop property file enables data sharing with other
MSC.Software applications, such as Adams/Chassis, and allows greater flexibility and a wider
range of bumpstop formulation choices. In particular, the new XML bumpstop property file
supports various methods and options for the calculation of force characteristics, as explained in
Calculation of Force Characteristics. You work with XML files in the Property File Editor.
Working with Reboundstops

A reboundstop defines a force-displacement relationship between two parts. The reboundstop acts
between user-specified coordinate reference points on each part, and conforms to the force-displacement
curve described in a designated property file. The reboundstop force is activated when the displacement
between the two coordinate references exceeds the defined clearance.
The force-displacement formula is based on:
Instantaneous distance between the user-specified coordinates defined on each part
Impact length or clearance
Reboundstop property file (polynomial or nonlinear stiffness with or without linear or nonlinear
damping.)
Learn about reboundstops:

Creating and Modifying Reboundstops
About Rebounstop Property Files
Creating and Modifying Reboundstops

When working in Template Builder, you can create reboundstops and then modify them. When working
in Standard Interface, you can only modify reboundstops. Learn about the interface modes.
To create a reboundstop:
From the Build menu, point to Forces, point to Reboundstop, and then select New.
Press F1 and then follow the instructions in the dialog box help for Create/Modify Reboundstop
Select OK.
To modify a reboundstop in the Template Builder:

113
114 Adams/Car
From the Build menu, point to Forces, point to Reboundstop, and then select Modify. To
load the parameters for a specific reboundstop, you must specify the reboundstop you want to
modify.
Right-click a reboundstop, point to its name, and then select Modify. The dialog box has the
reboundstop parameters already loaded.
Press F1 and then follow the instructions in the dialog box help for Create/Modify Reboundstop.
Select OK.
To modify a reboundstop in the Standard Interface:

In Standard Interface, right-click a reboundstop, point to its name, and then select Modify. The
dialog box has the reboundstop parameters already loaded.
Press F1 and then follow the instructions in the dialog box help for Modify Reboundstop.
Select OK.
Force Calculation
The force in a rebound stop always acts to keep two parts from moving farther apart. The force is active
only when the distance between the parts as computed by dm(i,j) exceeds the impact length. You specify
the impact length directly or indirectly as the initial clearance in the rebound stop. When you specify a
clearance, the impact length is calculated from the clearance as follows:
dmCalc + Clearance
where:
Clearance is the value you specify
dmCalc is the initial displacement computed between the i and j markers
Further, the force in a rebound stop is the sum of an elastic force and a damping force. The XML property
file supports various options for calculating either force. The options available for calculating elastic
force (F elastic) are:
polynomial - The for calculated using a third-order polynomial. The Adams/Solver function
expression is:
F elastic = POLY(MAX(0,DM(i, j) - impact_length),0,0,- linearRate,quadraticRate,-cubicRate)

nonlinear (spline based) - The force is interpolated using Akima's method based on force vs.
deflection data.
F elastic = -1.0*(AKISPL(MAX(0,DM( i , j ) - impact_length),0,Spline))
The following figure shows the clearance and impact length.
The damping force always acts in opposition to the velocity. In an XML reboundstop property file, the
options for calculating damping force are:
linear - You specify the dampingRate, and the damping force is the product of dampingRate,
velocity, and a STEP function. The STEP function depends on the displacement in the rebound
stop and ensures the damping force is continous with displacement.
Fdamping = STEP (MAX(0, DM(I,J) - impact_length), 0, 0, 0.1, -dampingRate

* VR ( marker i, marker j ))
nonlinear (spline based) - The damping force is interpolated using Akimas method from a
table of force vs. velocity. Again, a STEP function dependent on the displacement in the
rebound stop ensure that the damping force is continous with displacement.
F damping = STEP (MAX(0, DM(I,J) - impact_length), 0, 0, 0.1, -AKISPL

VR ( marker i, marker j ), 0, dampingSpline ))
About Reboundstop Property Files

The reboundstop component supports the following types of property files:
TeimOrbit reboundstop property files (extension .reb) - Standard TeimOrbit reboundstop
property files correspond to nonlinear elastic forces with linear damping equal to 0 formulation.
115
116 Adams/Car
XML reboundstop property file - The XML reboundstop property file enables data sharing with
other MSC.Software applications, such as Adams/Chassis, and allows greater flexibility and a
wider range of reboundstop formulation choices. In particular, the new XML reboundstop
property file supports various methods and options for the calculation of force characteristics, as
explained in Calculation of Force Characteristics. You work with XML files in the Property File
Editor.
Wheels, Adjustable forces and Gears

Wheels
A wheel is a specialized part you can use when creating tire models. In Adams/Car, creating a wheel
corresponds to creating the metal rigid body part (the rim) and the rubber (tire) around it. You model the
rim with a general rigid part and the tire with a general force (GFORCE). For information on GFORCE,
see the Adams/Solver online help.
In Standard Interface, to modify a wheel:
1. Right-click a wheel, and then select Modify.
2. Press F1 and then follow the instructions in the dialog box help for Modify Wheel.
3. Select OK.
In Template Builder, to create or modify a wheel:
1. From the Build menu, point to Wheel, and then select New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Create/Modify Wheel.
3. Select OK.
Adjustable Forces
An adjustable force is a special Template Builder user-defined element (UDE). You can use adjustable
forces for a variety of conditions, to satisfy static parameters in your model. For example, if you want to
set the length of a rod to be a specific length during static analysis, the adjustable force will vary until
the desired end condition is satisfied.
In Adams/Car for example, atypical application is to use an adjustable force to set toe and camber values
during a static suspension analysis. You might use two parts to define the tie rod and attach them by a
translational joint. You would then apply an adjustable force between the two parts to set toe and camber
values.
When the vehicle reaches static equilibrium without the use of adjustable forces, the toe and camber
alignments might not be the ones that you want. You use adjustable forces to define toe and camber
angles at static equilibrium position.
Adjustable forces act between two appropriate parts and perform a series of adjustments during static
equilibrium to minimize the error between the current computed toe/camber angle and the desired
toe/camber.
You might, for example, use two parts for the tie rod, constrain them using a translational joint, and then
apply an adjustable force between the two parts to set static toe angle. The current formulation creates a
single-component force that acts between the two parts. The force function uses stiffness and damping
values that you can set. The user-defined force uses a differential equation to minimize the error between
desired and computed angles.
117
118 Adams/Car
The _double_wishbone_torsion template distributed in the shared car database contains an example of
an adjustable force.
If more than one adjustable force is defined in a model, you must use the pattern statement within the
adjustable force definition. The pattern statement defines the order in which adjustable forces are active.
The following table defines four adjustable forces.
Adjustable force:
Pattern 1:
Pattern 2:
Pattern 3:
Front left toe
10
1010
10101010
Front right toe
10
1010
10101010
Front left camber
01
0101
01010101
Front right camber
01
0101
01010101
Rear left toe
10
1010
10101010
Rear right toe
10
1010
10101010
Rear left camber
01
0101
01010101
Rear right camber
01
0101
01010101
In Pattern 1, two separate static analyses would be run. In the first analysis, the toe adjustable forces
would be active. During the second analysis, the camber adjustable forces would be active. In Pattern 2,
four separate static analyses would be run and the same order as in Pattern 1 would be repeated. Because
the camber is directly affected by the toe change and the toe change is affected by the camber, it is often
desirable to build up patterns such that you can find a static solution by running a number of separate
static analysis. Pattern 3 is an example of eight separate static analyses.
Once the static analysis has been run, one of two things will happen depending on whether the lock with
motion was set for the adjustable force. For example, in Adams/Car an adjustable force might be created
between the tie rod inner and tie rod outer parts. If the adjustable force is locked with motion, then after
the statics is complete, Adams/Car will create a fixed joint between the two tie rod parts, fixing the
displacement between these parts for subsequent dynamic analyses. But if the adjustable force is not
locked, then the same force between the tie rod parts at the end of the static analysis will be maintained
during subsequent dynamic analyses.
In Standard Interface, to modify an adjustable force:
1. From the Adjust menu, select Adjustable Force.
2. Press F1 and then follow the instructions in the dialog box help for Modify Adjustable Force.
3. Select OK.
In Template Builder, to create or modify an adjustable force:
1. From the Build menu, point to Adjustable Force, and then select New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Create/Modify Adjustable
Force.
3. Select OK.
Gears
We provide two constraint-based gear options within the Template Builder:
Differential gear - The differential gear applies a reduction ratio between an input joint and the
symmetric output joint pair. The joint can be either revolute or cylindrical. The motion direction
can be inverted between the input and output joints and a toggle exists to switch between the two
different modes, allowing the reduction ratio to always be positive.
The reduction ratio is based on the following equation:
input motion = reduction ratio * (input shaft - output shaft)/2
You can define the differential gear to be kinematically active, allowing the element to be turned
on or off depending on the type of analysis you are running: compliant or kinematic.
Reduction gear - The reduction gear applies a reduction ratio between the input and output
joint. Either joint type can be translational, revolute, or cylindrical. Additionally, the motion
direction can be inverted between the input and output joints and a toggle exists to switch
between the two different modes, allowing the reduction ratio to always be positive.
When you enter a cylindrical joint in the input or output Joint text box, an additional text box
becomes active. Because either the rotational or translational degree of freedom of the cylindrical
joint can be used, you must specify if the rotational or translational motion will be the output for
the gear.
The reduction ratio is based on the following equation:
input motion = reduction_ratio * output motion
You can define the differential gear as being kinematically active, allowing the element to be turned on
or off depending on the type of analysis you are running: compliant or kinematic.
Note:
A gear in Adams/Car is a coupler in Adams/View.
119
120 Adams/Car
Actuators
We provide several actuator options with the Template Builder. An actuator lets you define an element
that can apply a force or motion function to a collection of modeling components. For example, you
might want to create a motion on a valvetrain system, or steer a vehicle around a corner. These
components include joints and parts but are not limited only to these.
Learn more about actuators:
About Actuators
Joint-Force Actuators
Joint-Motion Actuators
Point-Point Actuators
Point-Torque Actuators
Variable Actuators
Set Function
Set Activity
About Actuators
When used with appropriate feedback channels, actuators provide a very powerful method to control
your system.
Actuators differ from adjustable forces due to their behavior during dynamic analyses, with actuators
remaining active, whereas adjustable forces are either locked in place or replaced by a fixed joint.
If you create actuators as a symmetrical pair, then you can define separate left and right functions. You
can use the Function Builder to define functions.
Each actuator can have an application area and an identifier. The application area provides information
about the intended purpose of the actuator. The identifier should be used to describe the actuator instance
for this application area. A typical example would be:
Application area = steering
Identifier = steering_wheel_angle (e.g. for a motion type
actuator)
These two additional parameters support a more dynamic use of actuators. For example, to allow de/activation and function assignment on the assembly level by adding additional means for browsing and
filtering. Note that they are currently not required by your template-based product.
You can define limits for each actuator in the same way that you would define limits in a test laboratory
to prevent damage caused by excessive actuator force or travel. Although you can define limits for force,
displacement, velocity, and acceleration, it is not required that you do so.
You can define the activity of the actuator as either active or not active. You can define the activity either
from the dialog box or from the menu option Set Activity located under the Actuators menu. Learn about
defining the activity.
Joint-Force Actuators
A joint-force actuator defines either a translational or rotational single-component force acting between
two parts that a user-defined joint connects. You can select three types of joints:
Revolute joint - Selecting a revolute joint causes the Template Builder to automatically switch
to rotational and disable the Type of Freedom option. The single-component force will be a
rotational force acting between the two bodies that the revolute joint connects.
Translational joint - Selecting a translational joint causes the Template Builder to
automatically switch to translational and disable the Type of Freedom option. The singlecomponent force will be a translational force acting between the two bodies that the translation
joint connects.
Cylindrical joint - Selecting a cylindrical joint makes an additional text box active. Because
either the rotational or translational degree of freedom of the cylindrical joint can be used, you
must specify if the rotational or translational force will be used. This allows you to decide
between the creation of a torque or a force, based on the selection of either the rotational or
translational type of freedom.
Learn more about actuators, such as creating symmetrical pairs, using application area and identifier
attributes, and defining limits.
To create/modify a joint-force actuator:

1. From the Build menu, point to Actuators, point to Joint Force, and then select New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Create/Modify Joint Force
Actuator.
3. Select OK.
Point-Point Actuators
A point-point actuator defines an action-reaction translational single-component force acting between
the two parts that I Part and J Part parameters specify. You define the direction of the resulting force by
selecting the two points of force application, which can be either hardpoint or construction frame
locations.
To create/modify a point-point actuator:

1. From the Build menu, point to Actuators, point to Point Torque, and then select New/Modify.
121
122 Adams/Car
2. Press F1 and then follow the instructions in the dialog box help for Create/Modify Point Point
Actuator.
3. Select OK.
Joint-Motion Actuators
A joint-motion actuator defines either a translational or rotational motion acting between two parts that
a user-defined joint connects. You can select three types of joints:
Revolute joint - Selecting a revolute joint causes the Template Builder to automatically switch
to rotational and disable the Type of Freedom option. The motion will be a rotational motion
acting between the two bodies that the revolute joint connects.
Translational joint - Selecting a translational joint causes the Template Builder to automatically
switch to translational and disable the Type of Freedom option. The motion will be a
translational motion acting between the two bodies that the translational joint connects.
Cylindrical joint - Selecting a cylindrical joint makes an additional text box active. Because
either the rotational or translational degree of freedom of the cylindrical joint can be used, you
must specify if the rotational or translational motion will be used. This allows you to decide
between the creation of a rotational or a translational motion based on selection of either the
rotational or translational type of freedom.
To create/modify a joint-motion actuator:

1. From the Build menu, point to Actuators, point to Joint Motion, and then select New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Create/Modify Joint Motion
Actuator.
3. Select OK.
Point-Torque Actuators
A point-torque actuator defines an action-reaction or action-only rotational single-component torque
acting between the two parts that the I Part and J Part parameters specify. You define the direction of the
resulting torque within the dialog box. Many of the parametric functions discussed in Construction
Frames are available to define the position and orientation of the resulting actuator.
If you define the actuator as action only, then the J Part text box is disabled and no reaction is exerted.
To create/modify a point-torque actuator:

1. From the Build menu, point to Actuators, point to Point Torque, and then select New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Create/Modify Point Torque
Actuator.
3. Select OK.
Variable Actuators
A variable actuator is a user-defined element consisting of a data element variable and a series of
additional elements, such as strings and arrays. A variable actuator can be particularly useful where
either parts or joints cannot be referenced. An example of a variable actuator is the velocity of a vehicle:
the function could define a changing velocity which is then referenced by several other modeling
components.
To create/modify a variable actuator:

1. From the Build menu, point to Actuators, point to Variable, and then select New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Create/Modify Variable
Actuator.
3. Select OK.
Set Function
You can use the set function menu item to modify or replace the function that you defined.
You can use the Function Builder to define functions.
To set actuator function:
1. From the Build menu, point to Actuators, and then select Set Function.
2. Press F1 and then follow the instructions in the dialog box help for Actuator Set Function.
3. Select OK.
Set Activity
You can use the set activity menu option to set the actuator to be either active or not active. The not active
option is particularly useful when actuator elements are not required.
To set actuator activity:
1. From the Build menu, point to Actuators, and then select Set Activity.
2. Press F1 and then follow the instructions in the dialog box help for Actuator Set Activity.
3. Select OK.
123
124 Adams/Car
Condition Sensors
A condition sensor is a user-defined element that consists of a data element array and strings. It references
an existing variable class element (data element variable or measure solver computed), which is then tied
to the label and unit strings by the array. The array also encapsulates a request (for plotting convenience)
and a units conversion factor.
In essence, a condition sensor represents a relationship between a measurable solver quantity (the
variable class object) and a string label identifier that can be used in an event file (.xml) to define a
condition for Adams/Car full-vehicle analyses.
Use of Condition Sensors in Adams/Car
Adams/Car browses the assembly for condition sensor elements prior to each vehicle analysis and
updates the data element end_conditions_array with the derived list. At the beginning of the simulation,
the Standard Driver Interface (SDI) then uses the specified end condition measure string in the driver
control file to identify the associated variable class object in the dataset, that calculates the quantity the
end condition sensor should compare to the target value.
This architecture allows you to extend the provided set of standard end conditions. If, for example, a
ramp-steer like custom vehicle event should be ended when the turn radius falls short of a certain
threshold, you could:
add a variable class element to calculate the desired turn radius
variable name = .__MDI_SDI_TESTRIG.body_turn_radius
function = (vx2 + vy2)1.5 / (vx*ay - vy*ax)
add a condition sensor referencing the variable above
label = "radius"
variable = .__MDI_SDI_TESTRIG.body_turn_radius
units = length
Then, you could use this new condition sensor with the following line in your driver control file:
(END_CONDITIONS)
{measure test value allowed_error filter_time delay_time group}
'RADIUS' '|<' 20000.0 500.0 0.0 0.0
Creating or Modifying Condition Sensors
To create/modify condition sensors:
1. From the Build menu, point to Condition Sensors, and then select New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Create/Modify Condition
Sensor.
3. Select OK.
Feedback Channels
A feedback channel is a special user-defined element that contains a series of entities such as
Adams/Solver measures and Adams/View variables. Creating a feedback channel effectively
corresponds to creating a measure (Adams/Solver variable). It is then possible to display the measure.
For information on creating, displaying, and managing strip charts based on measures, see the
Adams/View online help.
Feedback channels are used in the __MDI_SUSPENSION_TESTRIG for the controller. Your templatebased product creates two channels:
Raw_channel - Controls an absolute value.
Offset_channel - Controls desired inputs for a deviation.
You can create feedback channels either as a symmetrical pair or individually.

Each feedback channel has an application area and a unique identifier. The application area provides
information about the intended purpose of the feedback channel. For example, you may want to specify
an application area forengine velocity with the identifier specifying that the velocity will beat the crank.
The following are possible naming schemes:
Application area = engine_velocity
Identifier = engine_velocity_crank
If you create feedback channels as a symmetrical pair, then you can define separate left and right
functions. You can use the Function Builder to define functions.
You can offset the raw signal of the feedback channel by a desired real value. Entering a real number in
this text box causes the Template Builder to create an additional measure whose function is the same as
the raw channel, but it is offset by the specified value.
Creating or Modifying User-Function Feedback Channel
To create or modify a user-function feedback channel:
1. From the Build menu, point to Feedback Channels, point to User Function, and then select
New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Create/Modify User-Function
Feedback Channel.
Setting Function
You can use the set function menu to modify or replace the function that you defined. Note that you have
the option to specify a routine instead of a function.
To set feedback channel function:
1. From the Build menu, point to Feedback Channels, and then select Set Function.
125
126 Adams/Car
2. Press F1 and then follow the instructions in the dialog box help for Set Feedback Channel
Function.
Setting Offset
You can use the set offset menu to modify the offset applied to the raw measuredchannel. You can toggle
the activity of the offset on or off.
To set feedback channel offset:
1. From the Build menu, point to Feedback Channels, and then select Set Offset.
2. Press F1 and then follow the instructions in the dialog box help for Set Feedback Channel Offset.
Data Elements, Requests and Variables

General Data Elements
General data elements are elements whose values are stored in property files.
The general data elements group includes:
General Parameter
General Spline
General Variable
General Parameters
The general parameter is an Adams/View variable whose real value is based on a value stored in a
property file data block. The property file must be in the neutral file format of your template-based
product. When your template-based product reads the property files, it updates the general parameter
variable entity with the appropriate real value stored in the property file. The data block and attribute
names in the Create General Parameter dialog box identify the data that is being accessed from the
property file.
Adams/Car uses a general parameter to model the piston area within a steering system. The steering
system includes a data block as follows:
$---------------------------------------------------GENERAL_PARAMETER
[GENERAL_PARAMETER]
USAGE = 'rack_piston_area'
SYMMETRY = 'single'
PROPERTY_FILE =
'mdids://acar_shared/steering_assists.tbl/mdi_steer_assist.ste'
DATA_BLOCK = 'STEERING_ASSIST'
ATTRIBUTE_NAME = 'piston_area'
The parameter DATA_BLOCK refers to the sub-block (steering_assist) in which the parameter can be
found. The USAGE keyword describes the name of the attribute whose value must be located. The
example below shows the data for the piston_area referenced above:
$----------------------------------------------------STEERING_ASSIST
[STEERING_ASSIST]
piston_area <area> = 490.87
In this case, the general parameter variable (rack_piston_area) is set to 490.87.
If your template-based product does not find the specified data blocks in the selected property file, then
it issues a warning and the general parameter retains its default value (0.0).
127
128 Adams/Car
To create or modify a general parameter:

1. From the Build menu, point to General Data Elements, point to Parameter, and then select
New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Create/Modify General
Parameter.
3. Select OK.
General Splines
The general spline is a spline whose values are stored in a property file. The property file must be in the
neutral file format of your template-based product. This method of creating splines allows great
flexibility: you can define the splines in your model depending on the numerical content of the selected
property files. When your template-based product reads the property files, it updates the spline entities
with the appropriate referenced values stored in the property files. The data that is being accessed from
the property file is identified by the data block and data sub-block names in the Create General Spline
dialog box. This allows for a very quick and efficient way to modify your data, without manually
modifying the data within an Adams spline.
For example, you could store the boost curve characteristics of many different steering systems in
separate property files and then test different steering systems by referencing those property files. If your
template-based product does not find the specified data blocks in the selected property file, then it issues
a warning and the spline retains its default values.
You can also create a spline using the Build -> Data Element -> Spline menus.This spline differs from
the general spline in a couple of subtle different ways:
A data element spline stores its data within the template and does not reference an external data
file defined by the neutral file format (TeimOrbit). Therefore, simple changes in data require that
you manually manipulate this spline in the Template Builder.
Because you cannot make variations to the spline data within the standard user environment, you
cannot carry out what-if scenarios, which you can easily do with the general spline.
Adams/Car uses a generalspline to model steering characteristics. The steering subsystem includes a data
block as follows:
$----------------------------------------------------GENERAL_SPLINE
[GENERAL_SPLINE]
USAGE = 'steering_assist'
SYMMETRY = 'single'
TYPE = 'two_dimensional'
PROPERTY_FILE =
'mdids://acar_shared/steering_assists.tbl/mdi_steer_assist.ste'
CURVE_NAME = 'steering_assist'
(COMMENTS)
{comment_line}
'Example of a steering assist spline'
The parameter steering_assist then refers to a sub-block of information within your property file. When
your product reads the property file, it populates the general spline with the data. The following shows
the data block for the steering_assist spline:
$----------------------------------------------------STEERING_ASSIST
[STEERING_ASSIST]
piston_area <area> = 490.87
(XY_DATA)
{tbar_deflection <angle> delta_pressure <MPa>}
-3.00 -4.00
-2.20 -4.00
-1.80 -3.60
-1.50 -3.00
-1.00 -2.00
-0.50 -1.00
0.00 0.00
0.50 1.00
1.00 2.00
1.50 3.00
1.80 3.60
2.20 4.00
3.00 4.00
This mechanism lets you generate and use both 2D and 3D splines with data stored within your database
structure by simply selecting the property file that stores the data and defining the data block.
To create or modify a general spline:
1. From the Build menu, point to General Data Elements, point to Spline, and then select
New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Create/Modify General Spline.
3. Select OK.
General Variables
The general variable is an Adams/Solver (data element) variable whose real value is stored in a property
file data block. The property file must be in the neutral file format of your template-based product. When
your template-based product reads the property files, it updates the general variable entity with the
appropriate real value stored in the property file. The data block and attribute names in the Create
General Variable dialog box identify the data that is being accessed from the property file.
The mechanism described for the general parameter is equally applicable to the general variable.
If your template-based product does not find the specified data blocks in the selected property file, then
it issues a warning and the general variable function retains its default value (0.0).
To create or modify a general variable:
1. From the Build menu, point to General Data Elements, point to Variable, and then select
New/Modify.
129
130 Adams/Car
2. Press F1 and then follow the instructions in the dialog box help for Create/Modify General
Variable.
3. Select OK.
Parameter Variables
You can use parameter variables to parameterize various elements and entities in your template-based
product. There are three types of parameter variables:
String - Does not contain units information, only a string value.
Integer - Does not contain units information, only an integer value.
Real - Can contain both a real value and a units specification.
Regardless of the parameter variable type, you can choose to hide the parameter variable from the
standard user. When you designate a parameter variable as hidden, the standard user will not be able to
access it using the Modify Parameter Variable dialog box in the Standard Interface.
Requests
You can use the Create Request dialog box to create a request statement and auxiliary variables used by
your template-based product. A request statement indicates a set of data you want Adams/Solver to
output in the request file (.req). You can explicitly do the following:
Output a set of displacements, velocities, accelerations, or forces with respect to existing
markers in your template. Learn about markers.
Define the generic request function
Use the user-written subroutine REQSUB to define nonstandard output. For information on user-
written subroutines, see Adams/Solver Subroutines.
For information on creating requests, see the Adams/View online help.
Data Elements
Data elements include arrays, curves, splines, matrices, and strings.
For information on data elements, see the Adams/View online help
System Elements
System elements let you create general differential and/or algebraic equations.
For information on system elements, see the Adams/View online help
Backlash Components
This component represents a backlash gap between two parts. In Adams/Driveline you can work with
two types of backlash components: rotational and translational backlash.
Learn about backlash:
Creating or Modifying Backlash
About Rotational Backlash
About Translational Backlash
Creating or Modifying Backlash

To create or modify backlash:
1. From the Driveline Components menu, point to Translational/Rotational Backlash, and then
select New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Backlash.
3. Select OK.
About Rotational Backlash

A rotational backlash describes a rotational connection between two parts that are connected using a
revolute joint and a rotational single-component force that describes the backlash. In addition,
Adams/Driveline creates a fixed joint to allow the possibility of deactivating the backlash.
Note:
Adams/Driveline automatically creates some kinematic joints in this component.
In the Standard Interface, you can use the Driveline Activity Wizard to manage the activity of each
backlash element.
The backlash law is defined with a combination of ATAN functions to guarantee smoothness and
derivative continuity
2 Adams/Driveline
where:
T = Resulting torque
sharp = Sharpness factor of the backlash
a = Relative angles of the two markers defining the backlash force
lash = Backlash (in radians)
stiff = Stiffness of the gear-to-gear contact
damp = Damping of the gear-to-gear contact
The sharpness factor lets you control how sharp the transition is between the lash region with zero forces
and the stiff region.
In this model, the expression of the sharpness factor is as follows:
This means that the backlash needs some time to be fully developed with the steady-state value of Nx.
This device makes integration easier. Nx is the value you define in the Rotational Backlash
Create/Modify dialog box.
Sharpness Factor Development Time
4 Adams/Driveline
Backlash Force as Function of Sharpness Factor (N=10, 500, 1000)
In the Standard Interface, you can vary values for the following:
Backlash
Stiffness
Damping
Sharpness factor
Request Definition
Result name: backlash_states
Component:
Component
name:
Component
units:
Definition:
F2
displacement
angle
The angle between the two parts connected

with the backlash element.
F3
angular_velocity
angular velocity The relative rotational velocity between the

two parts connected by the backlash element.
F4
force
force
Force exerted by the backlash element.
Subsystem Parameters
Backlash flag
Backlash
Stiffness
Damping
Sharpness factor
About Translational Backlash

A translational backlash describes a translational connection between two parts that are connected using
a translational joint and a translational single-component force that describes the backlash. In addition,
Adams/Driveline creates a fixed joint to allow the possibility of deactivating the backlash.
Note:
In the Standard Interface, you can manage the activity of each backlash element using the
Activity Wizard.
The backlash law is defined with a combination of ATAN functions to guarantee smoothness and
derivatives continuity.
6 Adams/Driveline
where:
F= Resulting force
Sharp = Sharpness factor of the backlash
a = Relative displacement angles of the two markers defining the backlash force
lash = Backlash in mm
stiff = Stiffness of gear-to-gear contact
damp = Damping of the gear-to-gear contact
The sharpness factor lets you control how sharp the transition is between the lash region with zero forces
and the stiff region.
In this model, the expression of the sharpness factor has been defined as follows:
This means that the backlash needs some time to be fully developed with the steady-state value of Nx.
This device makes integration easier. Nx is the value you select in the appropriate dialog box.
Sharpness Factor Development Time
Backlash Force as Function of Sharpness Factor (N=10, 500, 1000)
8 Adams/Driveline
Backlash
Stiffness
Damping
Sharpness factor
Request Definition
Result name: backlash_states
Component:
Componen Component
t name:
units:
F2
displacement length
The angle between the two parts connected with the

backlash element.
F3
velocity
velocity
The relative rotational velocity between the two parts

connected by the backlash element.
F4
force
force
Force exerted by the backlash element.
Backlash flag
Backlash
Stiffness
Damping
Sharpness factor
Definition:
10 Adams/Driveline
Bearings
A bearing component describes a force-based connection between two parts. Adams/Driveline models a
bearing with a six-component force and allows the two parts to rotate around the z-axis. Adams/Driveline
also models all contact forces and drag. You can specify both radial and axial backlash for the bearing.
Learn about bearings:
Creating or Modifying Bearings
About Bearings
Modeling Bearings
Example Bearing Property File
Creating or Modifying Bearings

To create or modify a bearing:
From the Driveline Components menu, point to Bearing, and then select New/Modify.
Press F1 and then follow the instructions in the dialog box help for Bearing.
Select OK.
About Bearings
In Adams/Driveline you can create two types of bearings:
Axial
Tapered
The driveline bearing formulation is based on values obtained from the Timken Company manual (for
free online resources register at http://www.timken.com/timken_ols/bearings/). The running torque
equations are for bearings whose torque has stabilized after a period of running under operating
conditions, so called a "running" bearing. The equations apply to bearings lubricated with circulating oil
or oil level systems. You can use the equations to model all single-row bearing loading conditions.
The component consists of the following objects:
A general force component featuring the actions and reactions between the inner and outer ring
of the bearing.
A request to output force and torque values.
Two revolution geometries to visualize the rings. The component creates these geometries on the
parts to be connected by the bearing (that is, shaft and housing).

Adams/Driveline calculates the forces and torques between the rings using a user-defined general force,
which acts properly depending on the bearing type.
Displacement Request (disp_request)
11
Component:
Component
name:
Component
units:
F2
dx
length
The displacement between the i marker and the

reference marker in the x direction.
F3
dy
length

reference marker in the y direction.
F4
dz
length

reference marker in the z direction.
F6
ax
angle
The angular displacement between the i marker and

the reference marker around the x-axis.
F7
ay
angle

the reference marker around the y-axis.
F8
az
angle

the reference marker around the z-axis.
Definition:
Velocity Request (velo_request)
Component:
Component
name:
F2
vx
velocity
The velocity between the i marker and the

F3
vy
velocity

F4
vz
velocity

F6
wx
angular velocity
The angular velocity between the i marker and

the reference marker around the x-axis.
F7
wy
angular velocity

the reference marker around the y-axis.
F8
wz
angular velocity

the reference marker around the z-axis.
Force Request (force_request)
Component
units:
Definition:
12 Adams/Driveline
Component:
Component
name:
Component
units:
Definition:
F2
fx
force
The force between the i marker and the

F3
fy
force

F4
fz
force

F6
tx
torque
The torque between the i marker and the

reference marker around the x-axis.
F7
ty
torque

reference marker around the y-axis.
F8
tz
torque

reference marker around the z-axis.
Adams/Driveline calculates the force and torque for the bearing using backlash expressions. The force
or torque is almost zero until the relative translational or angular displacement is lower than the specified
lash, then the force or torque follows an elastic law.
For tapered roller bearings, the thrust force acts only along one direction (z-positive), being zero along
the other.
The reaction forces in the three translational directions are defined with a linear stiffness + backlash. The
two cardanic reaction torques are calculated based on the translational forces and the geometric
properties (bearing diameter). Learn about the rotational backlash formulation.
To calculate the running torque of the bearing, depending on several factors (bearing geometry, applied
loads, load zone, speed of rotation, and so on) the following expressions have been used:
Radial load or combined radial thrust load:
Pure thrust load:
where:
T = Running torque
13
k1 = Constant being 2.56e-5 for T in N*m, 3.54e-5 for T in lbf*in

G1 = Bearing geometry factor
S = Running speed (rpm)
Mu = Lubricant viscosity (Cp)
K = Bearing K-factor. The K-factor is the ratio of basic dynamic radial load rating to basic
dynamic thrust load rating of a single row bearing.

f1 = Combined load factor. The combined load factor can be read from Timken tables as a
function of (K*Fa)/(Fr).
Fr = Radial load
Fa = Thrust road
Request Definition
Component:
Component
name:
Component
units:
Definition:
F2
angle
angle
The angle between the two parts (gear and

shaft).
F3
angular_velocity
angular velocity The relative velocity between the two parts

connected with the synchronizing force
component.
F4
torque
torque
Rotational force exerted by the

synchronizer component.
Modeling Bearings
In Adams/Car and Adams/Driveline you can model bearings in different ways, according to the effects
you want to observe in your models.
If, for example, you want to model a shaft with two bearings, the simplest solution is to connect the shaft
to the case with a revolute joint. The revolute joint is an ideal constraint that removes five degrees of
freedom. With this solution, compliance and drag effects are ignored. In addition, reaction forces on the
revolute joint are not comparable with the reaction forces you experience in a physical model.
A second solution is provided with a combination of kinematic joints: an inline primitive joint and a
spherical joint. The inline acts as a pure radial bearing (ideal) and the spherical joint as a combined radial
and axial bearing. This solution still does not take into account compliance and drag effects but provides
meaningful reaction forces.
When you want to model the connection between shaft and case, taking into account the compliance
effects, you can use the standard Adams/Car bushing element. You can define the radial and axial
stiffnesses using force versus displacement characteristics, and approximate the drag effects with a
constant rotational damping.
14 Adams/Driveline
The Adams/Driveline bearing component allows you to specify, in the three translational directions, a
linear stiffness with backlash effects. It also allows you to specify the same for the torques in the x and y
direction, while the torque along the z (spin) direction is computed based on values obtained from the
Timken Company manual (for free online resources register at
http://www.timken.com/timken_ols/bearings/). You can use the current implementation to model all
single-row bearing loading conditions, except for the pure thrust load (that means radial or combined
radial and thrust load bearing).

$--------------------------------------------------MDI_HEADER
[MDI_HEADER]
FILE_TYPE = 'bea'
FILE_VERSION = 4.0
$--------------------------------------------------UNITS
[UNITS]
LENGTH = 'mm'
ANGLE = 'degrees'
FORCE = 'newton'
MASS = 'kg'
TIME = 'second'
$----------------------------------------------BEARING_PARAMETERS
[BEARING_PARAMETERS]
G1 = 1000
MU = 10
K_FACTOR = 1
$--------------------------------------------------BEARING_SPLINE
[BEARING_SPLINE]
{ x y}
-100.0 6.0E-02
-50.0 6.0E-02
0.0 6.0E-02
50.0 6.0E-02
100.0 6.0E-02
15
Chains
This component describes a simplified chain model in its global behavior. This component does not
model chain parts. It does, however, model the global behavior of the chain, which is a torsional load and
a longitudinal force (tension).
Learn about chains:
Creating or Modifying Chains
About Chains
Creating or Modifying Chains

To create or modify a chain:
1. From the Driveline Components menu, point to Chain, and then select New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Chain.
3. Select OK.
About Chains
A chain describes a force-based connection between two sprockets. In Adams/Driveline you create a
simple chain model in which no chain links are modeled. Adams/Driveline models torsional and
translational loads in the chain with a rotational spring damper and a single-component force.
If you want to take into account the backlash effect, you can connect each sprocket to the respective shaft
with a rotational backlash component.
If you want to have a transmission ratio different from 1:1, you can connect the output sprocket to
another part with a kinematic gear component.
Adams/Driveline creates the following forces between the input and the output sprocket:
A rotational spring damper (acting between CM marker of the input sprocket and the CM
marker of the output sprocket).

Note:
The reason why a rotational spring damper is used instead of a coupler is so that chain
elastic characteristics can be taken into account.
A translational single-component force (acting between driving sprocket and driven sprocket).
The translational force expression is:

-TM(Input sprocket marker, output sprocket marker) / Input Sprocket Radius
16 Adams/Driveline
If you decide to use the gear geometry (revolution) for sprockets, the radius will be deduced from that
component. Otherwise, you will have to enter the value in the create/modify dialog box.
Rotational stiffness
Rotational damping
Sprocket radius (in case gear geometry has not been used)
Stiffness
Damping
17
Churning-Drag Forces
The churning-drag force component allows you to model the oil resistance acting on gears when they
rotate in oil. A churning drag describes a force-based component that models the oil resistance that forms
between gears and the gearbox case as soon as gears have a relative angular velocity with respect to the
gearbox case.
Learn about churning-drag components:
Creating or Modifying Churning-Drag Forces
About Churning-Drag Forces
Creating or Modifying Churning-Drag Forces

To create or modify churning-drag forces:
1. From the Driveline Components menu, point to Churning Drag, and then select New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Churning-Drag Force.
3. Select OK.
About Churning-Drag Forces

Adams/Driveline calculates the resistance force using a rotational single-component force and its
expression is as follows:
SIGN(K * Viscosity * B * Diam2 * ABS(wz)1.5, -wz)
where:
K = Constant (default 3.0E-12)
B = Gear breadth
Diam = Diameter
wz = Angular velocity
Constant
Breadth
Viscosity
Damping
18 Adams/Driveline
Component:
Component
name:
Component
units:
angle
Definition:
F2
angular
displacement
F3
angular_velocity angular velocity The relative velocity between the two parts
connected with the churning drag component.
F4
torque
torque
The angle between the two parts.
Rotational force exerted by the churning drag

component.
19
Clutch Connectors
This component allows you use the clutch connector in the driveline model. A property file stored in the
database determines the clutch connector characteristics. The component consists of a torque acting
between the two selected parts with the location and the orientation determined by a specified
construction frame.
Learn about clutch connectors:
Creating or Modifying Clutch Connectors
About Clutch Connectors
Creating or Modifying Clutch Connectors

To create or modify clutch connectors:
1. From the Driveline Components menu, point to Clutch Connector, and then select
New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Clutch Connector.
3. Select OK.
About Clutch Connectors

The component contains the following elements:
Single component force
IC motion (used to set the initial velocity)
Array storing the data read in the property file before submitting the analysis
Request
The following defines the clutch connector force:

Torque = STEP(WZ(I_MAR, J_MAR, J_MAR), 0,0, positive_velocity_threshold,
max_positive_transmitted_torque) + STEP(WZ(I_MAR, J_MAR, J_MAR), 0,0,
Negative_velocity_threshold, max_negative_transmitted_torque) - WZ(I_MAR, J_MAR,
J_MAR)*30/PI*drag_coefficient)
In steady-state conditions, equal rotational velocity of the two bodies produces a 0.0 torque.
In Template Builder, when you create a clutch connector, you can specify:
I part
J part
Coordinate reference (construction frame)
Property file
20 Adams/Driveline
In Standard Interface you can vary the property file.

The request outputs the following values:
The angle between the two parts along the reference frame z-axis
The angular velocity between the two parts along the reference frame z-axis
The torque transmitted between the two parts
Request Definition
Result name: torque_cvtr_variables
Component:
Component
name:
Component
units:
Definition:
F2
angle
angle
The angle between the two parts along the

reference frame z-axis.
F3
angular velocity
angular velocity
The angular velocity between the two parts

along the reference frame z-axis.
F4
torque
torque
The torque acting between the two parts.
Property file (<db_name>/clutch_connectors.tbl)
21
Clutch Forces
This component represents contact forces in a clutch component. It models normal contact forces, as well
as friction forces.
Learn about clutch forces:
Creating or Modifying Clutch Forces
About Clutch Forces
Example Clutch-Force Property File
Creating or Modifying Clutch Forces

To create or modify clutch forces:
1. From the Driveline Components menu, point to Clutch Forces, and then select New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Clutch Force.
3. Select OK.
About Clutch Forces

Contact forces are modeled using a property file which stores the cushion characteristic. The behavior is
very similar to a bumpstop element: no force in one direction, and force in the other one when the
distance between two parts (for example, flywheel and pressure plate) is smaller than a specified
clearance. The property file is stored in a designated directory of the database named
<db_name>/clutch_forces.tbl/*.clu.
Adams/Driveline models friction forces by multiplying contact forces with a friction coefficient and an
effective radius that you specify.
The friction coefficient is defined as a function of the relative angular velocity between the two parts.
You can also take into account both the static and dynamic friction coefficient.
Using the create/modify dialog box, you can observe how the friction function changes by changing
parameters such as the static and dynamic friction coefficient.
In Standard Interface, you can vary values for the following:
Property file
Impact length
Static friction coefficient
Dynamic friction coefficient
Static velocity
Dynamic velocity
22 Adams/Driveline
Effective friction radius

$--------------------------------------------------MDI_HEADER
[MDI_HEADER]
FILE_TYPE = 'clu'
FILE_VERSION = 4.0
$--------------------------------------------------UNITS
[UNITS]
LENGTH = 'mm'
ANGLE = 'degrees'
FORCE = 'newton'
MASS = 'kg'
TIME = 'second'
$--------------------------------------------------DAMPING
[DAMPING]
DAMPING = 10
$--------------------------------------------------CURVE
[CLUTCH_FORCE]
{ disp force}
0.0 0.0
3.50 40000.0
5.50 90000.0
7.60 130500.0
12.10 180000.0
15.50 270000.0
17.56 297900.0
40.635 378000.0
23
Complex Springs
This component represents a complex rotational spring with hysteresis. You can use it to model rotational
springs in clutch friction disks, as well as any other connection in which a rotational spring damper with
hysteresis is needed.
Learn about complex springs:
Creating or Modifying Complex Springs
About Complex Springs
Calculation of Complex Spring Force
Example Complex-Spring Property File
Creating or Modifying Complex Springs

To create or modify complex springs:
1. From the Driveline Components menu, point to Complex (Torsional) Spring, and then select
New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Complex Spring.
3. Select OK.
About Complex Springs

This complex spring represents a torsional spring with hysteresis. You can use it to model rotational
springs in clutch friction disks, as well as any other connection in which a rotational spring damper with
hysteresis is needed.
The hysteresis effect is accomplished using two different splines (loading and unloading) stored in a
specific property file (<db_name>/complex_springs.tbl/*.csp). Adams/Solver switches from one spline
to the other according to the value of angular velocity between the I and J marker. The value of velocity
at which the transition has to occur is also stored in the property file. Using two splines allows you to
take into account different values of hysteresis for different values of angular displacement.
In addition, the dependency of hysteresis from engine RPM is taken into account, since loading and
unloading splines are three-dimensional splines. The first independent variable is the angular
displacement and the second independent variable is engine RPM.
Before submitting an , you can switch the hysteresis effect on or off from the modify dialog box. If you
set Hysteresis Activity to no, Adams/Driveline uses only the first spline (loading) to evaluate the force
exerted by this component.In the Standard Interface, you can vary values for the following:
Property file
Hysteresis activity
24 Adams/Driveline
Calculation of Complex Spring Force

The complex spring force is calculated as follows:
FORCE = - load_step * load_scale_factor * load_spline - hysteresis_activity * step2 *
unload_scale_factor * unload_spline - damping * WZ
where:
load_step = step5(WZ,- TRANSITION_VELOCITY/2, 1-activity, TRANSITION_VELOCITY,
1)
unload_step = step5(WZ,- TRANSITION_VELOCITY, 1, TRANSITION_VELOCITY/2, 0)
load_spline = akispl(AZ,load_spline, 0)
unload_spline = akispl(AZ,unload_spline, 0)
When hysteresis_activity is set to off (0), the spring acts as a nonlinear torsion spring with viscous
damping, and only the first spline is used.
Note that you can also model torsion spring with hysteresis (and it's easier to define its parameters) using
the torsion spring.

$--------------------------------------------------MDI_HEADER
[MDI_HEADER]
FILE_TYPE = 'csp'
FILE_VERSION = 4.0
$--------------------------------------------------UNITS
[UNITS]
LENGTH = 'mm'
ANGLE = 'degrees'
FORCE = 'newton'
MASS = 'kg'
TIME = 'second'
$-----------------------------------------------SPRING_PARAMETERS
[SPRING_PARAMETERS]
TRANSITION_VELOCITY = 1e-1
DAMPING = 50
$--------------------------------------------------LOADING_SPLINE
[LOADING_SPLINE]
(Z_DATA)
{rpm}
0.0
1000.0
4000.0
(XY_DATA)
{ x y}
-60 -400000 -400000 -400000
-50 -300000 -300000 -300000
25
-40 -220000 -220000 -220000

-30 -175000 -175000 -175000
-20 -115000 -115000 -115000
-10 -50000 -50000 -50000
0 0 0 0
10 30000 30000 30000
20 50000 50000 50000
30 100000 100000 100000
40 160000 160000 160000
50 200000 200000 200000
60 400000 400000 400000
$--------------------------------------------------UNLOADING_SPLINE
[UNLOADING_SPLINE]
(Z_DATA)
{rpm}
0.0
1000.0
4000.0
(XY_DATA)
{ x y}
-60 -400000 -400000 -400000
-50 -200000 -200000 -200000
-40 -150000 -150000 -150000
-30 -110000 -110000 -110000
-20 -70000 -70000 -70000
-10 -25000 -25000 -25000
0 0 0 0
10 50000 50000 50000
20 110000 110000 110000
30 180000 180000 180000
40 220000 220000 220000
50 300000 300000 300000
60 400000 400000 400000
26 Adams/Driveline
Conceptual Wet Clutches

A wet clutch is a torque that connects an I part and a J part.
Learn about wet clutches:
Creating or Modifying Wet Clutches
About Wet Clutches
Creating or Modifying Wet Clutches

To create or modify wet clutches:
1. From the Driveline Components menu, point to Conceptual Wet Clutch, and then select
New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Wet Clutch.
3. Select OK.
About Wet Clutches

The torque expression is based on the inputs stored in the property file, such as number of surfaces,
effective radius, pressure area, turning point pressure, and MU.
The torque converter element also includes a clutch part that is connected to the J part. The two parts are
connected with a torsion spring (in the property file you also specify the Clutch Compliance Stiffness and
Clutch Compliance Damping parameters).
Adams/Driveline uses the following formulas to evaluate the resulting torque:
Clutch Capacity=STEP(varval(clutch_pressure),0,0,0.1,1)* number_of_surface *
effective_radius * clutch_mu * pressure_area * VARVAL(clutch_pressure)
Torque=clutch_capacity * clutch_switch
In the Standard Interface, you can vary the property file.
Request Definition
Result name: request1
27
Component:
Component
name:
Component
units:
Definition:
F2
angle
angle
The angle between the I and J part.
F3
Angular_velocity
angular velocity
The angular velocity of the I part with

respect to the J part.
F6
Clutch_pressure
pressure
The input pressure of the clutch.
F7
capacity
torque
The capacity that the clutch is able to

develop.
F7
capacity
torque
The torque the clutch applies between the I

and J parts.
Property file (<db_name>/clutch_forces.tbl)
28 Adams/Driveline
Gear Forces
This component represents a gear couple. You can use it to model Spur Gears and Bevel Gears.
Learn about gear forces:
Creating or Modifying Gear Forces
About Gear Forces
Creating or Modifying Gear Forces

To create or modify gear forces:
1. From the Driveline Components menu, point to Gear Force, and then select New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Gear Force.
3. Select OK.
About Gear Forces

The component consists of the following objects:
Two general forces, featuring the actions exchanged between the gear meshes.
A request to output force and torque values.
Adams/Driveline calculates the forces and torques between the gears using a user-defined general force,
whose action depends on the gear type.
To get reaction forces in the right direction, you must identify the orientation of the construction frames
used to define the gear forces. The following figure shows how construction frames must be oriented.
Notice that:
The z-axis must be oriented along the rotation axis
The x-axis has to point to the contact point
The y-axis is located based on the x- and z-axes
29
Construction Frame Orientations
You can specify the parameters as shown next:
Parameter:
Description:
Gear type
Spur, bevel
Gear diameters
Pitch diameter (depending on geometries)
Backlash
Allowed angular backlash
Stiffness
Contact rotational stiffness
Damping
Contact rotational damping
Sharpness factor
See Rotational Backlash
Pressure angle a
--
Average gear radius for bevel gear
Taken from geometry
Adams/Driveline calculates the transmitted torque for the gears using a backlash expression. (Torque is
almost zero until the relative angular displacement, scaled by gear ratio, is lower than the specified lash,
then the torque follows an elastic law.) Learn about rotational backlash.
The other torque and force components (radial and thrust) are derived from the transmitted torque
expression and from the gear type.
Spur Gears
From the transmitted torque, Adams/Driveline calculates the radial forces as follows:
30 Adams/Driveline
where:
Tz = Transmitted torque
Rp = Gear primitive radius
= Pressure angle
Bevel Gears
From the transmitted torque, Adams/Driveline evaluates the radial and thrust forces expressions as
follows:
where:
Fx = Radial load
Fz = Thrust load
= Gear ratio
31
Gear Pairs
This component represents a connection between two gears on two different shafts, according to a gear
ratio and a specified rotational backlash. To create a gear pair, input and output shafts, and input and
output gears must exist. A coupler element constrains the rotation of the output gear to the input gear.
Learn about gear pairs:
Creating or Modifying Gear Pairs
About Gear Pairs
Creating or Modifying Gear Pairs

To create or modify gear pairs:
1. From the Driveline Components menu, point to Gear Pair, and then select New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Gear Pair.
3. Select OK.
About Gear Pairs

You can use gear pairs to model the connection between spur gears of a constant mesh gearbox model.
In the constant mesh gearbox all gears are positively meshed to each other. They are mounted on bearings
and, when selected, are coupled to proper shafts by means of various types of devices. The gear pair
component consists of:
Ideal bearing between input shaft and gear (modeled as revolute joint).
Ideal bearing between output shaft and gear (modeled as revolute joint).
Two perpendicular joints that constrain, on demand, the residual rotational degree of freedom of
the input and output gears.

Coupler between the two revolute joints representing the positive connection between gears.
An additional dummy part (mesh carrier).
.
Note:
The dummy part is required to allow proper behavior of the mechanism. Adams/Driveline creates the
part representing the mesh carrier within the UDE instance. It is used to effectively define the connection
of the input gear to the output gear via coupler element. Without the mesh carrier part, a rigidly connected
input gear would not produce any rotation of the output gear with respect to the output shaft.
32 Adams/Driveline
You can select the initial configuration of the synchronizing mechanism by choosing one of the following
options:
Input gear connected to input shaft (input gear perpendicular JPRIM is active)
Output gear connected to output shaft (output gear perpendicular JPRIM is active)
Reduction ratio, in case it was not parameterized on the gear revolution geometries
Gear pair configuration
Output-to-input direction
Backlash
Stiffness
Damping
Sharpness factor
Ratio
Request Definition
Result name: gear_states_1 (input gear/shaft) and gear_states_2 (output gear/shaft)
33
Gear Parameters
Component:
Component
name:
Component
units:
angle
Definition:
F2
angle
F3
angular_velocity angular velocity The relative velocity between the two parts
(gear and shaft).
F4
torque
torque
The angle between the two parts (gear and

shaft).
Rotational force exerted by the synchronizer

element.
34 Adams/Driveline
Hypoid Gear Forces

This component represents hypoid gear forces. It consists of the following objects:
A general force featuring the actions and reactions between the ring gear and pinion gear.
Two differential equations to calculate gear angular error and angular error integral.
Learn about hypoid gear forces:

Creating or Modifying Hypoid Gear Forces
About Hypoid Gear Forces
Example Hypoid Gear-Forces Property File
Creating or Modifying Hypoid Gear Forces

To create or modify hypoid gear forces:
1. From the Driveline Components menu, point to Hypoid Gear Force, and then select
New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Hypoid Gear Force.
3. Select OK.
About Hypoid Gear Forces

Theoretical Background
35
The forces exchanged between ring gear and pinion gear at the mesh point can be evaluated as shown in
the following tables.
36 Adams/Driveline
Front and Rear Axles in Drive Conditions
Axial force:
Separating force:
PINION
GEAR
Front and Rear Axles in Coast Conditions
Axial force:
PINION
GEAR
The gear mesh point position can be calculated as:
Separating force:
37
x, y, z
= Mesh point location
p,
= Pinion face, gear root angles
= Gear offset angle
p, g
= Pinion and gear offset angles
= Pressure angle
p, g
= Pinion and gear spiral angles
Ap, Ag
= Pinion and gear mean cone distances
= Offset of gear and pinion centerlines
Rp, Rg
= Pinion and gear mean radius
z'
= Gear pitch apex beyond crossing point
Adams/Driveline implements the component with general forces using, as reference, frame markers
positioned at the gear mesh point. It calculates the location and orientation of these reference markers
into the component using data you provide.
The following figure shows how you must orient reference frames for a correct evaluation of gear forces
38 Adams/Driveline
You must create the case reference frame on the intersection of the z-axis of the pinion reference frame
and the z-axis of the ring reference frame. Adams/Driveline uses the case reference frame to locate the
marker at the gear contact point.
In the Template Builder, you can specify the parameters as shown next.
Hypoid Gear Parameters
Parameter:
Description:
Pinion gear I part
Rigid part modeling the pinion
Pinion gear J part
Rigid part to which pinion part is connected
Ring gear I part
Rigid part modeling the ring gear
Ring gear J part
Rigid part to which ring gear is connected
Pinion reference frame At pinion gear joint location, z-axis pointing towards pinion apex
Ring reference frame
At ring gear joint location, z-axis pointing towards ring apex
Case reference frame
At crossing point of ring reference frame and pinion reference frame
39
Parameter:
Description:
Stiffness
Gear forces stiffness
Damping
Gear forces damping
Differential location
Front or rear
Property file
Stores the hypoid gear properties (see Hypoid Gear Example Property File).
PINION_N_OF_TEETH
PRESSURE_ANGLE
PINION_OFFSET
PINION_MEAN_CONE_DISTANCE
PINION_PITCH_ANGLE
PINION_MEAN_SPIRAL_ANGLE
RING_N_OF_TEETH
RING_MEAN_CONE_DISTANCE
RING_PITCH_ANGLE
RING_MEAN_SPIRAL_ANGLE
RING_OFFSET_ANGLE
RING_FACE_WIDTH
RING_PITCH_APEX

$--------------------------------------------------MDI_HEADER
[MDI_HEADER]
FILE_TYPE
= 'hyp'
FILE_VERSION
= 4.0
FILE_FORMAT
= 'ASCII'
$--------------------------------------------------UNITS
[UNITS]
LENGTH
= 'mm'
ANGLE
= 'degrees'
FORCE
= 'newton'
MASS
= 'kg'
TIME
= 'second'
$--------------------------------------------------GEAR_PARAMETERS
[GEAR_PARAMETERS]
PINION_N_OF_TEETH
= 133
PRESSURE_ANGLE
= 15.633
PINION_OFFSET
= 38.1
PINION_MEAN_CONE_DISTANCE
= 120.0404
PINION_PITCH_ANGLE
= 20.1
40 Adams/Driveline
PINION_MEAN_SPIRAL_ANGLE
= 48.533
RING_N_OF_TEETH
= 43
RING_MEAN_CONE_DISTANCE
= 102.0572
RING_PITCH_ANGLE
= 68.5333
RING_MEAN_SPIRAL_ANGLE
= 27.20
RING_OFFSET_ANGLE
= 20.0667
RING_FACE_WIDTH
= 32.512
RING_PITCH_APEX
= 3.556
41
Limited Slip Differentials

This component is described as a force acting between differential side gears and the differential casing.
No additional parts are modeled.
Learn about limited slip differentials:
Creating or Modifying Limited Slip Differentials
About Limited Slip Differentials
Creating or Modifying Limited Slip Differentials

To create or modify a limited slip differential:
1. From the Driveline Components menu, point to Limited Slip Differential, and then select
New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Limited Slip Differential.
3. Select OK.
About Limited Slip Differentials

A limited slip differential can be:
Viscous - You must select a property file containing the characteristic describing the way the
torque is transferred from one side to the other if one wheel starts to spin. During the simulation,
as soon as one wheel start to spin the torque applied at that wheel decreases and is transferred to
the other wheel. The sum of torques applied at both wheels is kept constant and equal to the
torque exerted by the engine.
Clutch-pack - You can simulate the behavior of a clutch device which prevents one wheel from
spinning. Input parameters are friction coefficient, friction arm, preload, ramp angle of the gear,
side gear radius, and the revolute joints between side gears and the differential casing. This
component can evaluate thrust forces due to gear contacts, and can use these forces to calculate
the friction forces in the clutch.
Torque-sensing - You must specify the bias ratio and the torque threshold at which the
differential starts acting as a torque-sensing differential. You can also use the Adams variable,
which defines the input torque, as additional input. (In some cases, this variable is replaced by
the input communicator pointing to an Adams variable defined in another subsystem.)
The expression of the additional torque is as follows:
Dtorque = Input Torque * Scale * STEP(ABS(Dw),0,0,10,1)*
STEP(Input Torque, 0, 0, Torque Threshold, 1)
where:
Scale = 0.5 * (bias -1) / (bias + 1)
42 Adams/Driveline
Dw = difference in angular velocity between the left and right wheel
You can deactivate the limited slip differential using the Adams/Driveline Activity Wizard.
Property file (for viscous-sensing limited slip differentials)
Friction (for clutch-pack limited slip differentials)
Friction arm (for clutch-pack limited slip differentials)
Preload (for clutch-pack limited slip differentials)
Ramp (for clutch-pack limited slip differentials)
Side gear radius (for clutch-pack limited slip differentials)
Bias ratio (for torque-sensing limited slip differentials)
Torque threshold (for torque-sensing limited slip differentials)
Request Definition
Result name: lim_slip_diff_states
Component
name:
Component:
Component
units:
Definition:
F2
left angular velocity
F3
right angular velocity angular velocity The angular velocity of the right side gear.
F4
left force
torque
Torque applied between the left side gear

and the differential casing.
F6
right force
torque
Torque applied between the left side gear

and the differential casing.
Type
Property file
Bias ratio
Torque threshold
angular velocity The angular velocity of the left side gear.
43
Planetary Gears
This component represents a planetary gear.
Learn about planetary gears:
Creating or Modifying Planetary Gears
About Planetary Gears
Creating or Modifying Planetary Gears

To create or modify planetary gears:
1. From the Driveline Components menu, point to Planetary Gear, and then select New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Planetary Gear.
3. Select OK.
About Planetary Gears

You define a planetary gear using the following parts:
Sun part (lp sun)
Ring part
Carrier part
These parts are attached to the powerplant by the following joints:

Sun joint (to powerplant)
Ring joint (to powerplant)
Carrier joint (to powerplant)
A reference frame determines the planetary gear axis construction frame.

The planetary gear properties are stored in a property file.
The planetary gear connects the sun part to a sun_lash part (and the ring part to a ring_lash part). The
sun_lash part is connected to the sun part through a revolute joint and a torque to model the gear lash and
stiffness properties (defined in a property file). The same modeling technique is used for the ring. The
torque expression uses the backlash formulation as explained for rotational backlash.
The planetary gear ratio is set between sun_lash part, ring part, and carrier part through a coupler, using
the formula:
(r1 * q1) + (r2 * q2) + (r3 * q3) = 0,
where r1, r2, and r3 are the scale factors for the three joints, and for each joint, q1, q2, and q3, are
rotational displacements of the joint I marker with respect to the joint J marker.
44 Adams/Driveline
Therefore, using the Willis formula, we can determine that the coupler factors are:
sun number of teeth -> applied to the sun joint
(sun number of teeth + ring number of teeth) -> applied to the carrier joint
ring number of teeth -> applied to the ring joint
In the Standard Interface you can vary the property file.
Request Definition
Component:
Component
name:
Component
units:
F2
Sun_rpm
angular velocity Angular velocity of the sun with respect to the

powerplant.
F3
Ring_rpm
angular velocity Angular velocity of the ring with respect to the

powerplant.
F4
Carrier_rpm
angular velocity Angular velocity of the carrier with respect to the

powerplant.
Definition:
Component:
Component
name:
Component
units:
F2
Sun_backlash
F3
Ring_backlash angle
Angular lash between ring and ring lash parts.
F6
Sun_torque
torque
Torque acting between sun and sun lash parts.
F7
Ring_torque
torque
Torque acting between ring and ring lash parts.
angle
Property file (<db_name>/torque_converters.tbl)
Definition:
Angular lash between sun and sun lash parts.
45
Ravigneaux Gears
This component represents a ravigneaux gear.
Learn about ravigneaux gears:
Creating or Modifying Ravineaux Gears
About Ravigneaux Gears
Creating or Modifying Ravineaux Gears

To create or modify ravineaux gears:
1. From the Driveline Components menu, point to Ravineaux Gear, and then select New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Ravineaux Planetary Gear.
3. Select OK.
About Ravigneaux Gears

You define a ravigneaux gear using the following parts:
Long pinion sun part (lp sun)
Short pinion sun part (sp sun)
Ring part
Carrier part
These parts are attached to the powerplant by the following joints:

Long pinion sun joint (to powerplant)
Short pinion sun joint (to powerplant)
Ring joint (to powerplant)
Carrier joint (to powerplant)
A reference frame determines the ravigneaux gear axis construction frame.

The ravigneaux gear properties are stored in a property file.
The ravigneaux gear connects the two sun parts to the two sun_lash parts (and the ring part to a ring_lash
part). The sun_lash part is connected to the sun part through a revolute joint and a torque to model the
gear lash and stiffness properties (defined using a property file). The same model technique is used for
the ring. The torque expression uses the backlash formulation, as explained for rotational backlash.
The ravigneaux gear ratio is set between lp sun lash part, sp sun lash part, ring part, and carrier part
through two couplers using the formula:
(r1 * q1) + (r2 * q2) + (r3 * q3) = 0,
46 Adams/Driveline
where r1, r2, and r3 are the scale factors for the three joints, and for each joint, q1, q2, and q3 are
rotational displacements of the joint I marker with respect to the joint J marker.
Therefore, using the Willis formula, we can determine that the coupler factors are:
COUPLER 1 (sp_planetary_gear_ratios), acting between sp sun lash joint, carrier joint and ring lash
joint:
Sp sun number of teeth -> applied to the sun joint
(- sp sun number of teeth + ring number of teeth) -> applied to the carrier joint
- ring number of teeth -> applied to the ring joint
COUPLER 2 (lp_planetary_gear_ratios), acting between lp sun lash joint, carrier joint, and ring lash
joint:
lp sun number of teeth -> applied to the sun joint
- (lp sun number of teeth + ring number of teeth) -> applied to the carrier joint
ring number of teeth -> applied to the ring joint
In the Standard Interface you can vary the property file.
Request Definition
Component:
Component
name:
F2
Sp_Sun_rpm
angular velocity Angular velocity of the short pinion sun with

respect to the powerplant.
F3
LP_sun_rpm
angular velocity Angular velocity of the long pinion sun with

respect to the powerplant.
F4
Ring_rpm
angular velocity Angular velocity of the ring with respect to the

powerplant.
F6
Carrier_rpm
angular velocity Angular velocity of the carrier with respect to the

powerplant.
Component
units:
Definition:
47
Component:
Component
name:
Component
units:
Definition:
F2
Sp_Sun_backlash
angle
Angular lash between the short pinion

sun and its lash parts.
F3
Lp_Sun_backlash
angle
Angular lash between the long pinion

F4
Ring_backlash
angle
Angular lash between the ring and ring

lash parts.
F6
SP_Sun_torque
torque
Torque acting between the short pinion

F7
LP_Sun_torque
torque
Torque acting between the long pinion

F8
ring_torque
torque
Torque acting between the ring and ring

lash parts.
48 Adams/Driveline
Ride Wheels
The tire component consists of a rim and a ring.
Learn about ride wheels:
Creating or Modifying Ride Wheels
About Ride Wheels
Example Ride-Wheel Property File
Creating or Modifying Ride Wheels

To create or modify ride wheels:
1. From the Driveline Components menu, point to Ride Wheel, and then select New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Ride Wheels.
3. Select OK.
About Ride Wheels

The tire model consists of two parts:
Rim - Is connected to the suspension hub during the assembly.
Ring - Is connected to the rim with a vertical spring damper, a longitudinal spring damper, and a
torsion spring damper to describe the elasticity of the tire itself.

The rim and ring parts are also connected to each other with a planar joint, which constrains the two parts
to moving in the global XZ plane.
The ring is then connected to another part, named road, with a vertical force. This force is used to evaluate
traction forces exerted between the ring and the road in case a driving/braking torque is applied to the
driveline model. The traction force is applied at the wheel center. Therefore, a torque is needed equal to
the traction torque times the loaded tire radius.
If we call the vertical force between the ring and the road Fz, then we can say that the traction force, Fx,
is equal to:
Fx = m * Fz
where:
m = road friction coefficient
Fz = vertical load
The friction coefficient is calculated using the tire slip and the spline defining the dependency of the
friction on the tire slip (see figure Friction-Slip Function). The calculation follows:m = AKISPL(slip,0,
friction_spline) * friction_var
49
where:
slip = tire slip
friction_var = friction scaling function. This value is used to scale to the original friction spline, defined
for a maximum friction coefficient of 1.
Friction_var is defined using an adams_variable and can be defined to change either as a function of time
or traveled distance.
For example, if you want to have the friction on the front left tire go down to 0.5 at time = 1 sec and then
back to 1 at time = 2.5 with a transition time of 0.5 seconds, the expression for front left friction_var is
as follows:
STEP(TIME,1,1,1,5,0.5) + STEP(TIME, 2, 2.5, 0, 0.5)
You can set this dependency using a specific dialog box from the Adams/Driveline Standard Interface,
prior to submitting the . This dialog box allows you to set any kind of expression for the friction
coefficient, for an expression similar to the one explained above. You also have the graphical support
that gives you feedback on the shape of function you are using.
To access the dialog box, from the Simulate menu, point to Full-Vehicle Analysis, point to
Environmental Conditions, and then select Road Friction.
An Adams variable named traveled_distance automatically evaluates the distance traveled by the fullvehicle model. If friction has to be defined as a function of the traveled distance, the expression could be
something like:
STEP(VARVAL(traveled_distance),1,1,1,5,0.5) + STEP(VARVAL(traveled_distance), 2, 2.5, 0, 0.5)
50 Adams/Driveline
Friction-Slip Function
Adams/Driveline evaluates the tire slip according to the following formula (note that slip will be always
between -1 and 1):
slip = MAX(MIN((V - wr)/ABS(v), 1), -1)
where:
V = longitudinal speed of the car
w = rotational velocity of the wheel
r = loaded radius of the wheel (DZ(rim_cm, road))
Note that the reason why the ring part is connected to the road instead of the ground is because this
modeling technique allows you to put vertical and longitudinal actuators between the road and the
ground. This makes it possible to apply imposed motions to the full-vehicle model, such as known road
profiles or frequency sweep profiles.
The interposition of a rotational spring damper between the rim and the ring part is very important for
those analyses in which it is important to capture natural frequencies of the tire, such obstacle-passing
maneuver or tip in - tip out analyses.
51
Request Definition
Component:
Component
name:
Component
units:
Definition:
F2
Longitudinal slip
none
The longitudinal slip of the tire.
F3
Omega
RPM
The angular velocity of the tire.
F4
Traction
force
Traction force exerted by the tire.
F6
Vertical force
force
Vertical load on the tire.
Property file

$--------------------------------------------------MDI_HEADER
[MDI_HEADER]
FILE_TYPE = 'rti'
FILE_VERSION = 2.0
(COMMENTS)
{comment_string}
'Tire - Ride Tire'
$--------------------------------------------------UNITS
[UNITS]
LENGTH = 'mm'
ANGLE = 'degrees'
FORCE = 'newton'
MASS = 'kg'
TIME = 'second'
$--------------------------------------------------MODEL
[MODEL]
PROPERTY_FILE_FORMAT = 'RIDE'
$--------------------------------------------------DIMENSION
[DIMENSION]
RADIUS = 300
WIDTH = 300
ASPECT_RATIO = 0.55
RIM_RADIUS = 190
RIM_WIDTH = 139
$--------------------------------------------------TIRE_PARAMETERS
[TIRE_PARAMETERS]
STIFFNESS = 9e5
DAMPING = 1e4
TORSION_STIFFNESS = 6e4
TORSION_DAMPING = 1e1
$---------------------------------------------------RING_PARAMETERS
[RING_PARAMETERS]
MASS = 4.5
Ixx = 1
IYY = 1
IZZ = 1
52 Adams/Driveline
$------------------------------------------------FRICTION_vs_SLIP
[FRICTION_vs_SLIP]
{ slip_speed friction }
-1.0 -0.6508
-0.95 -0.6624
-0.91 -0.6799
-0.87 -0.6945
-0.83 -0.7061
-0.79 -0.7265
-0.75 -0.7497
-0.7 -0.7673
-0.666 -0.7847
-0.62 -0.8021
-0.58 -0.8168
-0.54 -0.8312
-0.5 -0.8487
-0.45 -0.8662
-0.41 -0.8837
-0.375 -0.9012
-0.33 -0.9274
-0.29 -0.9477
-0.25 -0.9639
-0.2 -0.9869
-0.166 -0.9927
-0.125 -1.0007
-8.0E-02 -0.9777
-4.0E-02 -0.8092
0.0 0.0
4.0E-02 0.8092
8.0E-02 0.9777
0.125 1.0007
0.166 0.9927
0.2 0.9869
0.25 0.9639
0.29 0.9477
0.33 0.9274
0.375 0.9012
0.41 0.8837
0.45 0.8662
0.5 0.8487
0.54 0.8312
0.58 0.8168
0.62 0.8021
0.666 0.7847
0.7 0.7673
0.75 0.7497
0.79 0.7265
0.83 0.7061
0.87 0.6945
0.91 0.6799
0.95 0.6624
1.0 0.6508
53
Torque Converters
This component allows you to define a torque converter in the driveline model.
Learn about torque converters:
Creating or Modifying Torque Converters
About Torque Converters
Example Torque-Converter Property File
Creating or Modifying Torque Converters

To create or modify torque converters:
1. From the Driveline Components menu, point to Torque Converter, and then select
New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Torque Converter.
3. Select OK.
About Torque Converters

You define torque converters using three parts:
Impeller (input shaft)
Turbine (output shaft)
Case
On these three parts, you apply two different forces:

Action force
Reaction force
These forces are defined according to the content of the property file you specify.
The property file stores two curves:
Torque ratio versus RPM ratio
Capacity factor versus RPM ratio
The following figures show sample plots for these two curves.
54 Adams/Driveline
Torque Ratio
Capacity Factor
The torque converter also includes a clutch part that is connected to the turbine with a torsion spring. The
clutch allows the direct engagement of the impeller to the turbine when the torque converter change-over
point is reached. You can define the clutch expression by either specifying the change-over point (so the
speed ratio at which the clutch must be engaged) or a clutch expression as a function of time.
Adams/Driveline uses the following formulas to evaluate action and reaction torque:
55
Impeller drag (acting between impeller and turbine):

direction* AKISPL(VARVAL(.RPM_ratio),0, Capacity_factor,0))
Turbine torque (acting between turbine and case):
AKISPL(VARVAL(.RPM_ratio),0, Capacity_factor,0)) *
AKISPL(VARVAL(.RPM_ratio),0, Torque,0))
Converter damping (acting between turbine and clutch part):
-clutch_torsional_stiffness*AZ(I,J)-clutch_torsional_damping*AZ(I,J,J)
Converter clutch (acting acting between impeller and clutch part):
clutch switch * clutch force
You can define the clutch force as a function of time or using the change-over point: in this case, the
clutch function will be:
STEP5(speed_ratio, change_over_point-.05, 0, change_over_point + .05, clutch_slip_gain*WZ(I,j)
In the Standard Interface, you can vary the property file.
Request Definition
Component:
Component
name:
Component
units:
Definition:
F2
impeller_rpm
angular velocity
Angular velocity of the impeller (input

shaft) with respect to the torque converter
case.
F3
turbine_rpm
angular velocity
Angular velocity of the turbine (output

case.
F4
conv_clutch_rpm
angular velocity
Angular velocity of the clutch (output

shaft) with respect to the turbine.
F6
speed_ratio
no units
The ratio between the output and the input

torque.
56 Adams/Driveline
Component:
Component
name:
Component
units:
Definition:
F2
impeller_drag
torque
Angular velocity of the impeller (input

case.
F3
turbine_torque
angular velocity
Angular velocity of the turbine (output

case.
F4
conv_clutch
angular velocity
Angular velocity of the clutch (output shaft)

with respect to the turbine.
F6
Capacity_factor
SQRT(angle/(force The torque converter capacity factor.

*length*second))
F8
Torque Ratio
no units
The torque converter torque ratio.

$--------------------------------------------------MDI_HEADER
[MDI_HEADER]
FILE_TYPE = 'tcf'
FILE_VERSION = 4.0
$------------------------------------------TORQUE_CONVERTER_HEADER
[TORQUE_CONVERTER_HEADER]
MODEL = 'torque_ratio_impeller_torque'
$--------------------------------------------------UNITS
[UNITS]
(BASE)
{length force angle mass time}
'mm' 'newton' 'degrees' 'kg' 'sec'
(USER)
{unit_type length force angle mass time conversion}
'Nmm' 1 1 0 0 0 1.0
$-------------------------------------------TORQUE_RATIO
[TORQUE_RATIO]
{ rpm_ratio torque_ratio}
0.0 6.3
0.1 5.6
0.2 4.9
0.3 4.2
0.4 3.5
0.5 2.8
0.6 2.1
0.7 1.4
0.8 0.7
0.9 0.0
57
1.0 0.0
$--------------------------------------------------IMPELLER_TORQUE
[IMPELLER_TORQUE]
(Z_DATA)
{ impeller_rpm <rpm>}
0.0
1000
1500
2000
2500
(XY_DATA)
{ rpm_ratio <rpm> impeller_torque <Nmm>}
0.0 0.0 1e4 1e4 1e4 1e4
0.1 0.0 9000 9000 9000 9000
0.2 0.0 8000 8000 8000 8000
0.3 0.0 7000 7000 7000 7000
0.4 0.0 6000 6000 6000 6000
0.5 0.0 5000 5000 5000 5000
0.6 0.0 4000 4000 4000 4000
0.7 0.0 3000 3000 3000 3000
0.8 0.0 2000 2000 2000 2000
0.9 0.0 1000 1000 1000 1000
1.0 0.0 900 900 900 900
58 Adams/Driveline
Torsion Springs
This component represents a simple torsional spring-damper connector. A torsion spring describes a
rotational connection between two parts. Adams/Driveline models the torsion spring with a singlecomponent force that works with the relative angular displacement and the relative angular velocity.
Adams/Driveline creates a revolute joint between the I and J parts.
Learn about torsion springs:
Creating or Modifying Torsion Springs
About Torsion Springs
Creating or Modifying Torsion Springs

To create or modify a torsion spring:
1. From the Driveline Components menu, point to Torsion Spring, and then select New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Torsion Spring.
3. Select OK.
About Torsion Springs

The elements that the torsion spring creates are:
Revolute joint connecting the two parts
Rotational single-component force connecting acting between the two parts
Request
Note:
The torsion spring force is defined as follows:

Torque= - Stiffness * AZ(I mar, J mar) - Damping * WZ(I mar, J mar, I mar)
where:
Stiffness = Torsional stiffness
Damping = Torsional damping
I mar = Marker belonging to the I part
J mar = Marker belonging to the J part
59
Note:
The following applies to those using these components for shaft elasticity: In the
create/modify dialog box in the Template Builder and in the modify dialog box in the
Standard Interface (learn about the interface modes), you can access an additional dialog
box that helps you select "first attempt" values for Stiffness and Damping based upon the
material, length, and section type of the shaft. This option can be very useful in early stage
studies in which adequate data are not yet available.
In the Standard Interface, you can vary values for torsional stiffness and damping.
Request Definition
Result name: vcoupling_states
Component:
Component
name:
Component
units:
Definition:
F2
angular
displacement
angle
The angle between the two parts connected

with the torsion spring.
F3
angular velocity
velocity
The angular velocity between the two parts

connected by the torsion spring.
F4
torque
force
Force exerted by the torsion spring.
Stiffness
Damping
60 Adams/Driveline
Unbalanced Mass
This component describes an unbalanced mass by its unbalanced momentum.
Learn about unbalanced mass:
Creating or Modifying Unbalanced Mass
About Unbalanced Mass
Creating or Modifying Unbalanced Mass

To create or modify unbalanced mass:
1. From the Driveline Components menu, point to Unbalanced Mass, and then select
New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Unbalanced Mass.
3. Select OK.
About Unbalanced Mass

An unbalanced mass introduces an inertial out-of-balance in your model. When creating an unbalanced
mass in Adams/Driveline, you fix a concentrated mass to a specified part, at a reference distance (for
example, 1 mm in MMKS) from a specified coordinate system.
Adams/Driveline computes the element mass as a function of the specified unbalanced momentum:
Mass = Unbalanced Momentum / (Reference Distance)2
Unbalanced momentum
Viscous Coupling
This component represents viscous coupling. A property file determines the viscous characteristics. The
component consists of a rotational force acting between the two parts with the location and orientation
determined by the selected construction frame. A viscous coupling describes a force-based connection
between two parts. A viscous coupling exerts a torque whenever the relative angular velocity between
two parts exceeds a certain value. When the relative angular velocity is zero, no torque is transmitted.
Learn about viscous coupling:
Creating or Modifying Viscous-Coupling Components
About Viscous-Coupling Components
Example Viscous-Coupling Property File
61
Creating or Modifying Viscous-Coupling Components

To create or modify a viscous-coupling component:
1. From the Driveline Components menu, point to Viscous Coupling , and then select
New/Modify.
2. Press F1 and then follow the instructions in the dialog box help for Viscous Coupling.
3. Select OK.
About Viscous-Coupling Components

The elements that a viscous-coupling component creates are:
General spline based on a property file
Torque function of the 2D general spline
Cylinder graphics
Request
The viscous coupling force is defined as follows:

Torque=-SIGN(akispl(ABS(WZ(I mar, J mar, J mar)),0, Spline), WZ(I mar, J mar, J mar))
where:
Spline = The two-dimensional spline that defines the slip-speed versus torque characteristic
I mar = Marker belonging to the I part
J mar = Marker belonging to the J part
In steady state conditions, equal velocities of the two half shafts produce a 0.0 torque.
In the Standard Interface, you can vary values for the property file, which effectively determines the
torque/slip-speed characteristic.
Request Definition
Result name: vcoupling_states
Component:
Component
name:
Component
units:
Definition:
F2
angular
displacement
angle
The angle between the two parts connected with

the vcoupling element.
F3
velocity
velocity
Relative angular velocity.
F4
force
force
Force exerted by the viscous coupling element.
62 Adams/Driveline
Property file (<db_name>/differentials.tbl) (see Viscous Coupling Example Property File)

$--------------------------------------------------MDI_HEADER
[MDI_HEADER]
FILE_TYPE = 'dif'
FILE_VERSION = 4.0
$--------------------------------------------------UNITS
[UNITS]
LENGTH = 'mm'
ANGLE = 'degrees'
FORCE = 'newton'
MASS = 'kg'
TIME = 'second'
$--------------------------------------------------DIFFERENTIAL
[DIFFERENTIAL]
{ slip_speed torque}
0.0 0.0
4.1 868.0556
8.3347 2.2222
12.5 7812.5
16.6 13888
Working with Templates
2 Adams/Driveline
Introducing the Templates

Your template-based product's library includes a variety of templates. Templates define the topology,
Major Role, and default parameters for subsystems. This tab includes template information that is
specific to your product.
For general template information, as well as information about the other files that make up model
architecture, see Building Models.
Running Analyses
2 Adams/Driveline
Overview of Analyses
Adams/Driveline allows you to create virtual prototypes of vehicle subsystems, and analyze the virtual
prototypes much like you would analyze the physical prototypes.
Adams/Driveline lets you analyze virtual prototypes of full vehicles. Using Adams/Driveline, you can:
Easily modify the geometry and the properties of the components of your subsystems.
Select from a standard set of vehicle maneuvers to evaluate the dynamic characteristics of your
virtual prototype.
View the vehicle states and other characteristics through plots.
When setting up an analysis in Adams/Driveline, you specify the following:

The virtual prototype to be tested - You specify the virtual prototype by opening or creating an
assembly that contains the appropriate components, or subsystems, that make up the prototype.
For example, you create a suspension assembly containing suspension and steering subsystems.
The kind of analysis you'd like performed - You specify the test or analysis by selecting one
from the Adams/Car Simulate menu. There are two major types of analyses: suspension and fullvehicle.
The analysis inputs to be used - You specify the inputs to the analysis by typing them directly
into an analysis dialog box or by selecting a loadcase file that contains the desired inputs from an
Adams/Car database.
After specifying the prototype assembly and its analysis, Adams/Driveline, like your companys testing
department, applies the inputs that you specified and records the results. To understand how your
prototype behaved during the analysis, you can plot the results. After viewing the results, you can modify
the prototype and analyze it again to see if your modifications improved its behavior.
Each kind of analysis that you perform requires a minimum set of subsystems. For example, a full-vehicle
analysis requires front and rear suspension subsystems, front and rear wheel subsystems, one steering
subsystem, and one body subsystem. Before you can create an assembly and perform an analysis in
Adams/Driveline, you must open or create the minimum set of subsystems required.
(Standard Interface) Simulate -> Full-Vehicle Analysis -> Driveline Tests -> Bench Test
3
Running Analyses
Bench-Test Analysis
Performs a bench-test analysis.
For the option:
Do the following:
Assembly
Select the assembly you want to analyze. The menu lists all open
assemblies.
Output Prefix
Enter a string that specifies the analysis output name. The string can
contain only alphanumeric characters and underscores (_).
Adams/Driveline appends the suffix _bench to form the complete
analysis name. For example, if you enter test45 as the output prefix, the
analysis name becomes test45_bench.
End Time
Enter a number greater than zero to specify the duration of the simulation.
Number of Steps
Enter the number of output steps in output files (.req, .gra). It affects the
resolution of your animations and plots. Make sure that the number of
steps you specify is high enough to display the highest frequency you
want to observe.
Mode of Simulation
Select interactive, background, or files only.
Road Data File
Specify a road data file. Tire subsystems use the information in road data
files to calculate the tire/ground interaction forces. If your model uses ride
tire subsystems, Adams/Driveline automatically deactivates this text box
because tire/ground interaction forces are evaluated in a different way.
For more information about road data files, see the Adams/Tire online
help.
4 Adams/Driveline
For the option:

Initial Velocity
Do the following:
Enter the initial velocity of the car at the beginning of the simulation. You
can enter any number greater than or equal to zero. Adams/Driveline uses
this value to run an initial velocity analysis just after the static equilibrium
and to set all rotational velocities of the driveline.
Adams/Driveline performs this initial velocity analysis using a

CONSUB. You can check the syntax in the. acf file. Adams/Driveline
automatically deactivates this text box when there is no body subsystem
in the selected assembly, because it assumes that without a body
subsystem it doesn't make sense to specify an initial velocity.
In the text box to the right of Initial Velocity, select the most suitable units
set for the initial velocity. Before performing the analysis,
Adams/Driveline automatically converts the model units to the specified
units set.
5
Running Analyses
For the option:

Gear Position
Do the following:
Select the initial gear to be used during the simulation. Adams/Driveline
sets the transmission_demand in the test rig to the value you specify.
If the model you want to analyze contains gear-pair elements, then
Adams/Driveline engages the correct one to both the input and output
shafts with kinematic joints.
Create Analysis Log File
Select if you want Adams/Driveline to write information about the

assembled model and simulation to a log file.
Adams/Driveline names this log file after the output prefix and an output
suffix, depending on the full-vehicle analysis you selected. The log file
contains information about the type and success of the analysis, date and
user, analysis parameters, and the active subsystem used in the
simulation.
Select to display the Modify Entity Comments dialog box, where you can
add multi-line comments to any entity to describe its purpose and
function.
Select to display the Modify Testrig Demands dialog box, where you can
set any expression for test-rig demands (steering, throttle, brake, clutch,
and transmission) to perform any kind of analysis. Using this dialog box
you can, for example, set time histories for clutch and transmission
demands to perform a gear shift event:
TRANSMISSION DEMAND: STEP(TIME, 1.3, 1, 1.5, 2)IC = 1
CLUTCH DEMAND: STEP(TIME,1.2, 0, 1,3, 1) + STEP(TIME, 1.6,

0.0, 1.7, -1) IC = 0
6 Adams/Driveline
Setting up Dropped-Clutch Analyses

A dropped-clutch analysis is an Adams/Driveline full-vehicle analysis.
Adams/Driveline sets up the crankshaft initial velocity according to the value you specify. The clutch is
initially disengaged and is engaged during the maneuver. You can either directly specify the input torque
applied to the crankshaft or specify a throttle value and an engine property file. If you choose the latter
option, Adams/Driveline calculates the engine torque according to the crankshaft RPM and throttle
position.
To set up a dropped-clutch analysis:
1. From the Simulate menu, point to Full-Vehicle Analysis, point to Driveline Tests, and then
select Dropped Clutch.
2. Press F1 and then follow the instructions in the dialog box help for Dropped-Clutch Analysis.
3. Select OK.
7
Running Analyses
Setting up Initial Condition Motions Activity Analyses

As explained in Setting up Initial-Velocity Analyses, Adams/Driveline creates a point motion whenever
you define a force-based connection between two parts. You can use this point motion to make the entire
driveline behave as a kinematic system, so it can inherit the initial rotational velocity from the tires.
Before running the dynamic analysis, Adams/Driveline automatically deactivates initial condition
motions.
Deactivating Point Motions
In some instances, one or more point motions can cause the system to be overconstrained. For example,
when creating a clutch assembly, the friction disk is typically constrained both to the flywheel and to the
pressure plate with a clutch force element, and to the hub of friction disk with a torsion spring damper.
In this situation, there are three point motions but only two are needed to fully constrain the model. You
can deactivate one of the point motions between the friction disk and flywheel, or between the friction
disk and the pressure plate.
To deactivate a point motion:
1. Open your assembly in Adams/Driveline.
2. From the Tools menu, select IC Motions Activity.
3. Press F1 and then follow the instructions in the dialog box help for Driveline IC Motions Status.
Note:
If your assembly does not use a subsystem with initial condition motions,
Adams/Driveline informs you that there are no IC motions in your template. Select
OK, and the Driveline IC Motions Status dialog box opens.
4. Select Close.
Adams/Driveline skips the deactivated point motions from the group called lock array, and
ignores them during the initial velocity analysis.
8 Adams/Driveline
Setting up Initial-Velocity Analyses

In Adams/Driveline, a control subroutine (CONSUB) called from the acf file sets the initial longitudinal
velocity of the vehicle automatically before a dynamic simulation is performed. You specify the initial
velocity in the Submit Analysis dialog box. If the tires in the model use standard tire subroutines, the
initial rotational velocity of the tires is also automatically set.
All parts constrained to the tire along the rotational axis automatically inherit the initial velocity of the
tire. If a part with an initial rotational velocity is not constrained to another part along the rotational axis,
the second part will not inherit the initial rotational velocity from the first part. For example, suppose you
have a drive shaft consisting of an inner and an outer shaft. The two shafts might be connected to each
other with a rotational spring damper, which is a force-based connection (not a constraint). A way around
this problem is to temporarily constrain all rotational parts along the rotational axis while Adams is
calculating the initial velocity. Before you submit the dynamic analysis, you must remove (deactivate)
all temporary constraints.
All Adams/Driveline components available in the Template Builder automatically include a rotational
constraint (if needed). This constraint is a point motion (a motion between two markers) named
ic_motion and it is set to zero and deactivated by default. All ic_motions in the model are also
automatically added to a group named lock_array.
When you submit an analysis, Adams/Driveline activates all ic_motions and stores their Adams IDs in a
solver array named lock_array.
In the .acf file, a second Adams/Driveline-specific CONSUB is called after the regular Adams/Car
CONSUB. This CONSUB first performs an initial-condition velocity analysis and then deactivates all
ic_motions found in the Solver array lock_array. After the initial-condition velocity analysis is run, all
parts have a longitudinal and rotational velocity according to the initial velocity of the vehicle and tires.
The next line in the .acf file could be a dynamic simulation command.
Restrictions
Note the following when running the Initial Velocity Analysis:
If you do not use a standard tire subroutine, the Adams/Car CONSUB will not recognize the tire
as a wheel part; therefore, no initial rotational velocity will be given to the tires. In this case, you
must manually add an initial rotational velocity to the wheel part. If you use Adams/Driveline
ride tires, the initial rotational velocity of the wheels is set automatically when the tires are
created.
If you build a model with standard Adams/Car components, Adams/Driveline will not
automatically create the ic_motion. You can create the ic_motion in the Template Builder by
selecting the Driveline Components menu, pointing to Advanced, and then selecting IC Motions
Create.
Currently, the procedure of setting initial rotational velocity only works for Adams/Driveline-
specific analyses. This is due to the specific set-up macro being called from a submit macro.
9
Running Analyses
If you manually specify initial rotational velocity on two parts that are constrained to each other,
Adams/Driveline will calculate the average initial rotational velocity and use it for both parts
(and all parts constrained to them).
If you are driving the model with a motion active during the initial condition analysis, the
motion velocity will overwrite all initial rotational velocities set on parts constrained by the
motion.
10 Adams/Driveline
Setting up Impulse-Torque Analyses

An impulse-torque analysis is a specific Adams/Driveline full-vehicle analysis.
To set up an impulse-torque analysis:
select Impulse-Torque.
2. Press F1 and then follow the instructions in the dialog box help for Impulse-Torque Analysis.
3. Select OK.
11
Running Analyses
Setting up Ramp-Torque Analyses

A ramp-torque analysis is an Adams/Driveline full-vehicle analysis.See a plot of the torque function
during analysis.
To set up a ramp-torque analysis:
select Ramp-Torque.
2. Press F1 and then follow the instructions in the dialog box help for Ramp-Torque Analysis.
3. Select OK.
12 Adams/Driveline
Setting up Rock-Cycle Analyses

A rock-cycle analysis is an Adams/Driveline full-vehicle analysis.
During this analysis, Adams/Driveline submits the vehicle alternatively to a positive and a negative
engine torque simulating a 1st gear - reverse gear engagement, as shown in the figure Effect on Torque.
This test modifies only the direction of the engine torque. It does not shift gears.
To set up a rock-torque analysis:
select Rock-Cycle.
2. Press F1 and then follow the instructions in the dialog box help for Rock-Cycle Analysis.
3. Select OK.
13
Running Analyses
Setting up RPM Sweep Analyses

An RPM-sweep analysis is an Adams/Driveline full-vehicle analysis.
Adams/Driveline sets up the initial velocity according to the RPM values you specify. A motion drives
the simulation and applies the RPM-sweep law to the driveline.
To set up an RPM-sweep analysis:
select RPM Sweep.
2. Press F1 and then follow the instructions in the dialog box help for RPM-Sweep Analysis.
3. Select OK.
14 Adams/Driveline
Setting up Step-Torque Analyses

A step-torque analysis is an Adams/Driveline full-vehicle analysis.
To set up a step-torque analysis:
select Step-Torque.
2. Press F1 and then follow the instructions in the dialog box help for Step-Torque Analysis.
3. Select OK.
15
Running Analyses
Setting up Throttle Tip In - Tip Out Analyses

A throttle tip in - tip out analysis is an Adams/Driveline full-vehicle analysis.
Adams/Driveline sets the throttle demand expression based on the values you specified for driving and
coasting, and determines the input torque applied to the crankshaft according to the throttle position and
crankshaft RPM as inputs for the engine property file.
To set up a throttle tip in - tip out analysis:
select Tip In - Tip Out.
2. Press F1 and then follow the instructions in the dialog box help for Tip In - Tip Out Analysis.
3. Select OK.
16 Adams/Driveline
Setting up Torque-Loadcase Analyses

A torque-loadcase analysis is an Adams/Driveline full-vehicle analysis.
Adams/Driveline sets the input torque according to the torque loadcase file you select. When you use a
torque loadcase file, you can store an experimental torque time history in an ASCII file and then deliver
that to the engine for a dynamic simulation.
To set up a torque-loadcase analysis:
select Tip In - Tip Out.
2. Press F1 and then follow the instructions in the dialog box help for Torque-Loadcase Analysis.
3. Select OK.
17
Running Analyses
Setting up Torque Tip In - Tip Out Analyses

A torque tip in - tip out analysis is an Adams/Driveline full-vehicle analysis.
To set up a torque tip in - tip out analysis:
select Torque Tip In - Tip Out.
2. Press F1 and then follow the instructions in the dialog box help for Tip In - Tip Out Analysis.
3. Select OK.
18 Adams/Driveline
Controlling Analysis Output Files

Your template-based product lets you control the type and content of files an analysis outputs. You can
specify whether an analysis outputs a graphics file or results file. Graphics files contain time-dependent
data describing the position and orientation of each part in the model. Results files contain a basic set of
state variable information that Adams/Solver calculates during a simulation.
Your template-based product automatically reads the files that an analysis outputs.
If any subsystems within the assembly being analyzed contain flexible bodies, your template-based
product automatically outputs a results file, regardless of the specifications you made.
To specify analysis output files:
1. From the Settings menu, point to Solver, and then select Output Files.
The Output Files dialog box appears.
2. Select the types of files you want to output.
3. Select OK.
19
Running Analyses
Examples
Getting Started Using Adams/Driveline
Example Files:
Engine Map Property File

$--------------------------------------------------MDI_HEADER
[MDI_HEADER]
FILE_TYPE
= 'pwr'
FILE_VERSION
= 1.0
FILE_FORMAT
= 'ASCII'
$--------------------------------------------------UNITS
[UNITS]
(BASE)
{length
force angle mass time}
'mm'
'newton' 'degree' 'kg' 'sec'
{unit_type
length force angle mass time conversion}
'Nmm'
1 1 0 0 0 1.0
$--------------------------------------------------ENGINE
[ENGINE]
(Z_DATA)
{throttle}
0.0
1.00
(XY_DATA)
{engine_speed
<no_units> torque <Nmm>}
0
0 0
500
-20000
80000
1000
-42000 135000
1500
-44000 200000
2000
-46000 245000
2500
-48000 263000
3000
-50000 310000
3500
-50000 358000
4000
-50000 404000
4500
-50000 455000
5000
-50000 475000
5500
-50000 485000
6000
-50000 468000
6250
-50000 462000
6500
-52000 455000
6750
-56000 427000
7000
-60000 370000
7500
-64000 259000
20 Adams/Driveline
Reviewing Results
206 Adams/Car
Requests
Requests contain standard displacement, velocity, acceleration, or force information that can help you
investigate the results of simulations. You can also define other quantities (such as pressure, work,
energy, momentum, and more) that you want output during a simulation.
Adams stores the requests in request files (.req).
Setting Request Activity

By default, requests for each element type are active. You can, however, deactivate requests for a certain
element type. Any activity changes will only be retained during the current session.
Note that for the bushing element, the activity switch is saved in the subsystem/assembly file.
To set request activity:
1. From the Standard Interface's Tools menu, select Request Activity.
2. Press F1 and then follow the instructions in the dialog box help for Toggle Request Activity.
3. Select OK.
Storing Request Activity

To store the request activity, you should group activity using parameter variables, which are stored in
subsystem files.
To store request activity in Template Builder:
1. Create a parameter variable to store the activity of the request as a 1 for active, 0 for inactive.
For example, pvs_request_activity.
2. Create a group with command language:
Tools -> Command Navigator, group -> create
3. Add your requests to the group.
4. For the expr_active parameter of the group (1 = active, 0 = inactive), create a function that uses
the parameter variable in step 1.
The commands might look as follows:
group create &
group_name = ._my_template.my_request_activity
objects_in_group = ._my_template.request0, &
._my_template.request1, &
expr_active = (pvs_request_activity)
Reviewing Results
For more examples, investigate templates in the shared database that have the group
kinematic_mode_active, which is used for the Kinematic Mode option.
Request 907
Request 907 (req907) outputs displacement, velocity, accelerations, and body side-slip angle depending
on the value of par(2) in the parameter list. Req907 is compatible with both dynamic and steady-state
type analyses.
The definition of the parameters array and the resulting output is:
par(1) = Branch Flag 907
par(2) = Request Type:
0 = Displacement(Angles in radians)
1 = Velocities
(Translational vel. in KPH)
(Angular velocity in radians/s)
2 = Accelerations
(Translational acc. G's)
(Rotational acc. in radians/s/2)
3 = Body Side Slip Angle in Radians
par(3) = id I marker
par(4) = id J marker
par(5) = id RM marker
Any results with a magnitude less than 1e-7 are set to zero.
207
208 Adams/Car
Plot Configuration Files

You can plot the results of an analysis using the standard functionality in Adams/PostProcessor. To help
you manage your plots, however, your template-based product provides plot configuration files that
define a series of plots.
For information on Adams/PostProcessor, see the Adams/PostProcessor online help.
Learn more about plot configuration files:
About Plot Configuration Files
Creating Plots Using a Plot Configuration File
Creating Plot Configuration Files
Format of Plot Configuration Files
Renaming Plots in Plot Configuration Files
Example Plot Configuration File
About Plot Configuration Files

Plot configuration files tell your template-based product:
Which plots to create
The vertical and horizontal components that it should plot
General settings and preferences, such as titles, labels, horizontal and vertical spacings, scaling,
legend text, and more
The files currently support only one plot per page, which can contain multiple axes. You can cross-plot
multiple analyses of the same type using one plot configuration file.
Plot configuration files are TeimOrbit files and are stored in your database in the plot_configs.tbl
directory.
You can access the plot configuration file functionality in Adams/PostProcessor. Learn about creating a
plot configuration file through the interface. Learn about using plot configuration files.
Note:
To modify plots and curves, you can use the command statement in each block to invoke
macros, which must contain the modification commands. The macros must be contained in
your current binary file, which can be either private or site.
Creating Plots Using a Plot Configuration File

After you've run an analysis, you can view the series of plots defined in a plot configuration file. If your
plot configuration file contains customization command keywords and it has created the plots and curves,
Reviewing Results
you can have your template-based product invoke the macro that contains a command keyword in its
user-entered command.
The plot configuration file specifies a subtitle for your plots. In addition, in the File Import dialog box
you can:
Add a title to all the plots.
Plot results of multiple analyses on one plot using the Cross Plotting option.
Change the look of your plot, such as fonts and size, using the option Execute Custom Macros.
To use this option, you must have a macro that defines the commands to be executed.
To view the plots defined in a plot configuration file:

1. From the Review menu, select Postprocessing Window or press F8.
2. From the File menu, point to Import, and then select Plot Config File.
The File Import dialog box appears.
3. In the Analyses text box, enter the analysis or analyses from which you want to view results.
4. In the Plot Configuration File text box, enter the name of the plot configuration file defining the
plots that you want to view.
5. In the Plot Title text box, enter the title to appear at the top of the plots.
6. Select Cross Plotting to plot analysis data on existing plots containing data from other analyses.
If you selected multiple analyses in the Analyses text box, your template-based product
automatically plots the data from the different analyses on the same plots.
7. If you have customization command keywords in the plot configuration file you selected in Step
4, then select Execute Custom Macro.
Your template-based product invokes the macro which executes any commands that customize
the plots.
8. Select OK.
Creating Plot Configuration Files

You can create a plot configuration file containing all of the plots currently in Adams/PostProcessor or
only a selected set of plots. Your template-based product stores the configuration files in the plot_config
table of your default writable database.
Note that you can create only one plot per page.
To create a plot configuration file:
1. From the Review menu, select Postprocessing Window or press F8.
2. Create and configure plots as desired, including specifying labels and spacing. For example, you
can create a set of plots and add subtitles to all of them that describe the type of analysis with
which the plots are associated.
209
210 Adams/Car
3. From the File menu, point to Export, and then select Plot Configuration File.
The Save Plot Configuration File dialog box appears.
4. In the Configuration File Name text box, enter the name for the plot configuration.
5. If you want to include all plots currently in the Plotting window, including every page, select All
Plots.
6. If you did not select All Plots, in the Plot Name(s) text box, enter the names of the plots that you
want to include in the plot configuration file.
7. In the Plots and Curves text boxes, enter command keyword to invoke the macro that customizes
the plots and curves.
Your template-based product saves the command keyword with your plotting configuration file.
After it creates the plots and curves, your plotting configuration file invokes the macro which
contains the commands.
8. Select OK.
Format of Plot Configuration Files

Plot configuration files consist of two data blocks:
Plot Data Block
Plot-Curve Data Block
Plot Data Block

The plot data block has the following structure:
NAME
SUBTITLE
TIME_LOWER_LIMIT
TIME_UPPER_LIMIT
PLOT_AXES (subblock)
COMMAND
command_keyword
After your template-based product creates each plot, it executes the following commands if you defined
a command keyword:
acar custom_plots <command_keyword> & plot_name=<plot_name>
The command acar custom_plots <command_keyword> must already be created in the current session,
either interactively or already present in the acar.bin, or aengine.bin file.
Plot-Curve Data Block
The plot-curve data block has the following structure:
NAME
PLOT
Reviewing Results
VERTICAL_AXIS
HORIZONTAL_AXIS
VERTICAL_COMPONENT
HORIZONTAL_COMPONENT
LEGEND_TEXT
COLOR
red, blue, yellow, magenta, cyan, black, white, skyblue,
midnight_blue, blue_gray,dark_gray, silver, peach, maize
STYLE
solid, dash, dotdash, dot
SYMBOL
none, x, o, plus, star, at
LINE_WEIGHT
Real value from 1-4
COMMAND
command_keyword
After your template-basedproduct creates each curve, it executes the following commands if you defined
a command keyword:
acar custom_plots <command_keyword> &
analysis=<analysis> &
plot_name=<plot_name> &
vertical_data=<y> &
horizontal_data=<x> &
curve_name=<curve_name>
The command acar custom_plots <command_keyword> must already be created in the current session,
either interactively or already present in the acar.bin, aengine.bin or arail.bin file.
Renaming Plots in Plot Configuration Files

When Adams/PostProcessor creates plot configuration files, it assigns generic names to the plots: plot_1,
plot_2, and so on. In general, it's best to manually rename all the plots in each configuration file you
generate. This will prevent conflicts if you later create plots using multiple plot configuration files that
contain the same plot names.
To prevent conflict, simply rename the plots by manually editing the plot file. It is an ASCII file in your
private database in the plot_configs.tbl directory. Choose a descriptive name.
For example, in the AA_aircraft.plt file, the first plot has been renamed to aircraft_plot_1, the second
plot has been renamed to aircraft_plot_2, and so on. The plot names are entered on the lines that start
with the string, "NAME = ". Be sure to also change the name of the plot in each section that describes a
curve that belongs to that plot (search for the lines starting with "PLOT ="). To make the changes all at
once, for this example, "aircraft_plot_" was globally substituted for "plot_".
Here is an example of renamed plots in the file, AA_aircraft.plt. These are the first three sections of the
file. Adams
$-----------------------------------------------------------------MDI_HEADER
[MDI_HEADER]
FILE_TYPE
= 'plt'
211
212 Adams/Car
FILE_VERSION = 1.0
FILE_FORMAT
= 'ASCII'
$----------------------------------------------------------------------PLOT
[PLOT]
NAME = 'aircraft_plot_1'
SUBTITLE = 'Aircraft Linear CG Acceleration in Ground Coordinates'
TIME_LOWER_LIMIT = 0.0
TIME_UPPER_LIMIT = 0.0
(PLOT_AXES)
{axis_name
type
label
scaling divisions low_limit
up_limit}
'vaxis'
'vertical'
'Acceleration (inch/sec**2)'
'linear'
10
0
0
'haxis'
'horizontal'
'Time (sec)'
'linear'
4
0
0
$-----------------------------------------------------------------PLOT_CURVE
[PLOT_CURVE]
NAME = 'curve_1'
PLOT = 'aircraft_plot_1'
VERTICAL_AXIS = 'vaxis'
HORIZONTAL_AXIS = 'haxis'
VERTICAL_COMPONENT = 'AC_CG_Acc_GRND.ACCx'
HORIZONTAL_COMPONENT = 'AC_CG_Acc_GRND.TIME'
LEGEND_TEXT = 'AC_CG_Acc_GRND.ACCx'
COLOR = 'red'
STYLE = 'solid'
SYMBOL = 'NONE'
LINE_WEIGHT = 2.5
Example Plot Configuration File

The following is an example of an Adams/Car plot configuration file:
$------------------------------------------------------------plot
[PLOT]
NAME = 'toe_angle'
SUBTITLE = 'Toe Angle'
TIME_LOWER_LIMIT = 1
TIME_UPPER_LIMIT = 1e+10
(PLOT_AXES)
{axis_name type label scaling divisions lower_limit upper_limit}
'vaxis' 'vertical' 'Angle' 'linear' 6 0 0
'haxis' 'horizontal' 'Wheel Travel' 'linear' 10 0
$------------------------------------------------------------plot_curve
[PLOT_CURVE]
NAME = 'toe_angle_r'
PLOT = 'toe_angle'
VERTICAL_COMPONENT = 'toe_angle.right'
HORIZONTAL_COMPONENT = 'wheel_travel.vertical_right'
LEGEND_TEXT = 'Right'
COLOR = 'red' STYLE = 'solid'
SYMBOL = 'none'
LINE_WEIGHT = 1.5
$------------------------------------------------------------plot_curve
Reviewing Results
[PLOT_CURVE]
NAME = 'toe_angle_l'
PLOT = 'toe_angle'
VERTICAL_COMPONENT = 'toe_angle.left'
HORIZONTAL_COMPONENT = 'wheel_travel.vertical_left'
LEGEND_TEXT = 'Left'
COLOR = 'blue' STYLE = 'dash'
SYMBOL = 'none'
LINE_WEIGHT = 2.0
213
214 Adams/Car
Configuring Your Product
354 Adams/Car
About the Management Tasks

When you start your template-based product, it automatically creates the necessary files for you to begin
working immediately. As you become more familiar with your template-based product, you may find that
you want to set up custom private versions of it or change the way it is configured. In addition, you may
want to set up custom site versions that several users can share.
The template-based products let you do these different management tasks depending on the type of user
access you have been assigned. You should give one user, who has expert-user access, the responsibility
of managing the site version, if you have one, of your template-based product so only one user, the site
manager, makes changes.
The following table lists the different management tasks that you can perform depending on your user
access. You can perform many of these tasks using themenus in your template-based product. Other tasks
require you to set variables in different configuration files.
Management Tasks by User Type
This type of
user:
Standard user
Can:
Create and set up private databases in which to store files, such as
subsystems and property files, with which you are working.
Make copies of files in your private database or copy the entire database
to share with other users.
Configure the operation of your template-based product for your private
use.
Expert user
Perform the same tasks as a standard user.

Publish a template so all users can use it.
Site manager
Set up site databases in which general project information is stored.

Define the access that users can have to functionality.
Set up a custom version of your template-based product and configure its
operation.
Assigns access to common databases to allow read and write permissions
for standard and expert users.
To access management tools:

Your access to management tools depends on your user access:
Standard users - You can access your template-based product's tools that let you manage your
private database. The tools are under the Tools menu.
Expert user - You can access the management tools from the Tools menu.
To get expert-user access, modify your private .acar.cfg configuration file and change your user mode to
EXPERT. Learn about setting your product's environment.
355
356 Adams/Car
About Database Management

The template-based products define assemblies using several different files. The files define the topology,
dynamic element characteristics, analysis information, and more. Your template-based product stores
these files in hierarchical databases.
The template-based products provide two types of default databases:
Private database for each user - A private database is for your personal use. You can store and
retrieve data from your private database. In addition, you can share your private database with
others. If a private database does not exist, your template-based product creates the private
database at the beginning of a session.
Shared database for all users - A shared database provides all users with access to standard,
accurate data. To prevent loss of data or the storing of inaccurate data in a shared database,
standard users can only retrieve data from a shared database. Typically, only the site manager has
the permissions necessary to create files in a shared database. An example of a shared database is
distributed with your template-based product, and it is usually placed in the installation
directory.
Learn more about databases:

Database Structure
About the Database Search List
Database Structure
Each database consists of one directory (*.cdb) and several subdirectories (*.tbl), called tables. Each
subdirectory contains files for specific types of components, such as springs and dampers, or files for
performing tests, such as loadcasesand wheel envelopes. The number of tables varies, but you can define
the number in the shared and private configuration files.
By default, your template-based product divides a database into the following table elements:
Models and topological information (templates, assemblies, subsystems, and flexible bodies)
Analysis information (such as analysis scripts, loadcases, driver loadcases, and suspension
curves)
Postprocessing (plot configuration files)

In Adams/Car, driver files (such as driver inputs and roads)
In Adams/Car, tires and roads
Property files (such as springs, dampers, and remaining tables)
Each type of file that a table stores has a unique three-letter extension that identifies its contents. For
example, all files stored in the assembly table contain a .asy extension.
An example of the default structure of a database for Adams/Car is shown in the Information window. The
information window shows all the tables in the database, their names, the type of files they store, and the
file extension of the files that they store.
You can also add your own tables since the database is an open-architecture file repository. For example,
you might want to create a table that stores data files for an analysis that is specific to your company.
Learn about managing tables.
About the Database Search List

During startup, your template-based product stores any databases that are defined in your private, site,
and shared configuration files in its search list. The databases in the search list are the only databases that
appear in dialog boxes when you select to display databases and files, such as subsystem or property. For
example, when you want to change the database to which you can write files, your template-based
product only displays those databases in its search list in the dialog box.
Your template-based product searches the databases in its search list using a search order that you can
modify.
You can change the databases in the search list and their search order either by using the menus or by
editing the configuration files directly. All configuration files can define the databases, including the
private, site, and shared configuration files.
357
358 Adams/Car
For your template-based product to be able to store a database in its search list, the file system to which
the database points must be accessible on the current file system of the computer.
Learn about setting up the search list and the order in which databases are searched.
Managing Databases
Select a topic to learn about the operations you can perform on databases:
Creating Databases During a Session
Setting the Writable Database
Managing Tables in a Database
Creating Tar Files of Databases
Creating Databases During a Session

You can create a new database anytime during a session. When you create a database, your templatebased product adds it to its search list and places the database at the lowest level in its database search
order. Your template-based product also creates database tables within the newdatabase according to the
table information stored in your private, site, and shared configuration files. Learn about search order.
Note:
Unless you save database changes to your private configuration file, Adams/Solver will
not be able to access the databases you added or created in a session
You should create a database for every project on which you are working. By creating separate databases
for each project, you can ensure that the property files belonging to different subsystems are kept
separate.
When you create a database, you define two elements for it:
Name - You use the name, or database alias, to select the database from the search list in dialog
boxes.
Path - The location of the database in the file system.
Note:
You can also create databases directly using the configuration files. Learn about managing
databases through configuration files.
To create a database:
1. From the Tools menu, point to Database Management, and then select Create Database.
2. Press F1 and then follow the instructions in the dialog box help for Create New Database.
3. Select OK.
359
360 Adams/Car
Setting the Writable Database

You can set up one of your active databases as the repository for templates, subsystems, and property
files. This database is called your default writable database. The default writable database is defined in
your private configuration file, but you can change it at anytime during a session. You can select any
database in the search list as your default writable database, as long as you have permission to write to
the file system to which the database points.
To create a database:
1. From the Tools menu, point to Database Management, and then select Set Default Writable.
2. Press F1 and then follow the instructions in the dialog box help for Set Default Writable Database.
3. Select OK.
Managing Tables in a Database

You can add your own tables to a database. You use the configuration files to define the tables that you
want to include in a database. Learn more about configuration files and table definitions in them.
Creating Tar Files of Databases

On UNIX, you can create a tar file of any database that is listed in the search list. When you create a tar
file of a database, your template-based product groups together all of the database's subdirectories and
files into one tar file. It then writes the tar file to the default writable database using the name
database_name.tar, where database_name is the name of the database you saved.
Saving a database as a tar file is an efficient way to save a snapshot of the current state of a database or
to transfer the database to an external file system. You can easily transfer the databases through e-mail
or through a file transfer protocol (ftp) process.
As you create a tar file, you can select to encode and compress the database using standard UNIX
compression and encoding techniques.
To create a tar file of a database in UNIX:
1. From the Tools menu, point to Database Management, and then select Bundle Database.
2. Press F1 and then follow the instructions in the dialog box help for Bundle Database.
3. Select OK.
Setting Up the Search List and Order

As explained in About the Database Search List, your template-based product stores in its search list, all
the databases currently defined in your configuration files. When you request a file from the databases,
your template-based product uses a defined search order to search the databases for the requested file.
Note:
By default, your template-based product doesn't search all defined databases when it
cannot locate a file. You can, however, re-enable the searching by setting the
MDI_CDB_SEARCH environment variable to yes. In the Command Navigator, you can
issue the following command:
variable set variable_name=do_search &
integer_value=(putenv("MDI_CDB_SEARCH","yes"))
For more information, see the Adams/Car release notes.
See the following topics to learn more about the search order, how it impacts you, and how you set it up:
About Search Order
Adding Databases to the Search List
Removing Databases from the Search List
Changing the Search Order
About Search Order

During a session, you can have many databases listed in the search list. Your template-based product
assigns to each database in the search list a numerical value representing its place in the search order. For
example, if there are three databases in your search list, your template-based product numbers them 1,
2, and 3, with 1 representing the first database it searches.
When you request a file, such as a property file, your template-based product searches the databases in
the specified search order. It first tries to open the file as specified. If the filename has a database alias,
your template-based product expands it to a full file system path.
If your template-based product cannot find the file in the specified database, it begins searching the other
databases in its search list in the search order. Your template-based product begins with the first database
in the search order. It continues through all the databases in the search order until it finds a matching
filename.
Your private configuration file sets the search order of these databases, but you can change it at anytime
during a session.
Note that in many cases changing the database search order can cause your template-based product to
find a different file. For example, if two databases contain a file with the same name but with different
data, changing the search order may change which file your template-based product uses. You may find
361
362 Adams/Car
this helpful in many cases, but it can produce unintended results when you change the search order
without realizing that you can access different files. The database search order is also important if you
specify the database path incorrectly.
To avoid using the search order to find a file, which can result in longer searches and unintended results,
you can specify the database name (its alias) directly in the associated property file to ensure that your
template-based product searches the correct database.
You can look at the search order of thedatabases in the search list usingthe Database Info command, as
shown in Viewing Database and Table Information. Your template-based product displays the current list
of databases, showing the search order level of each database in the first column. Learn about displaying
database information.
Adding Databases to the Search List

As you are working with your template-based product, you can add databases to the current search list.
Your template-based product adds the databases to the end of the search order. Learn about changing the
search order.
To add a database to the search list:
1. From the Tools menu, point to Database Management, and then select Add to Search.
2. Press F1 and then follow the instructions in the dialog box help for Add Database to Search.
3. Select OK.
Removing Databases from the Search List

You can remove a database from the search list so that your template-based product does not search for
files in it. Removing a database from the search list does not remove the database from the file system.
If you want to remove the current default writable database from the search list, you must first specify
another database as the default writable database.
To remove a database from the search list:
1. From the Tools menu, point to Database Management, and then select Remove from Search.
2. Press F1 and then follow the instructions in the dialog box help for Remove Database from
Search.
3. Select OK.
Changing the Search Order

You can change the order in which your template-based product searches databases for files. Learn about
search order.
To change the search order:

1. From the Tools menu, point to Database Management, and then select Change Search Order.
2. Press F1 and then follow the instructions in the dialog box help for Change Database Search
Order.
3. Select OK.
363
364 Adams/Car
Saving and Publishing Database Information

Viewing Database and Table Information
You can view the current set of databases in the search list. The information includes the database names,
file system paths, and levels in the current search order. You can also view the table structure of the
current writable database.
To view database information:
1. From the Tools menu, point to Database Management, and then select Database Info.
2. View the database information, and then select Close.
To view the tables in the writable database:
From the Tools menu, point to Database Management, and then select Table Info.
View the table information, and then select Close.
Saving Database Management Changes

At any point during a session, you can save the list of databases that is currently available during the
session and the search order to your private configuration file. Learn about private configuration files.
To save database management changes:
From the Settings menu, select Save <product name> Configuration.
When you publish a subsystem, you copy the subsystem file and all its associated property files to the
target database, which is the database where your template-based product saves all files. You can also
select to publish the subsystem's template file. As you publish the subsystem, you can choose to write
over existing files or create backups of the files.
You can also select to update the in-session subsystem data to point to the target database or to have the
subsystem retain the existing references.
The subsystem you are publishing must be currently opened in the standard interface, and the target
You can also publish an entire assembly. Learn about publishing an assembly.
To publish a subsystem:
1. From the Tools menu, point to Database Management, and then select Publish Subsystem.
2. Press F1 and then follow the instructions in the dialog box help for Publish an Open Subsystem.
3. Select OK.
When you publish an assembly, you copy each subsystem file included in the assembly definition,
including the associated property files for each subsystem, to the target database, which is the database
where your template-based product saves all files. You can also select to publish each subsystem's
template file. As you publish the assembly, you can select to write over existing files or create backups
of the files.
You can also select to update the in-session assembly data to point to the target database or to have the
assembly retain the existing references.
The assembly you are publishing must be currently opened in the standard interface, and the target
You can choose to publish only a subsystem, not an entire assembly. Learn about publishing a subsystem.
To publish an assembly:
1. From the Tools menu, point to Database Management, and then select Publish Assembly.
2. Press F1 and then follow the instructions in the dialog box help for Publish an Open Assembly.
3. Select OK.
365
366 Adams/Car
About Configuration Files

Your template-based product's configuration file contains information that your template-based product
reads during startup to correctly initialize the session. Your template-based product looks for the
following configuration files when it starts up: shared, site (if it exists), and private configuration files,
in that order.
The private configuration file contains personal settings that are then merged with the general settings
defined in the shared or site configuration file. Together, the settings define your work environment. The
shared and private configuration files are required, while the site configuration file is optional. You use
the site configuration file only if you want to set up a custom version that all users can access.
To personalize the settings in the configuration files, you edit the configuration file using a text editor.
You can, however, use the menus to set up the databases without having to directly edit the configuration
files. Learn about managing databases.
Each of the configuration files is explained in the next topics:
About Private Configuration Files
About Site Configuration File
About Shared Configuration File
About Plugin Configuration Files
About Private Configuration Files

As an expert or standard user, you have your own private configuration file with a default name of
.acar.cfg. Your template-based product accesses this file at the beginning of every session. The private
Note:
acar.cfg file located in the installation.
If you have more than one private configuration file, you can choose the file you want to use for a given
session. Depending on the platform you are using, you do the following:
On UNIX - You use the Registry Editor on the Adams Toolbar to choose the file you want to
use. The registry setting name for your private configuration file is privateCfg.
On Windows - You can specify the private configuration file using an environment variable.
You can set this environment variable using the System option from the Control Panel, just as
you would for any other variable. Depending on your template-based product, you can specify
the following environment variables:
For Adams/Car, enter MDI_ACAR_PRIVATE_CFG
For Adams/Driveline, enter MDI_ADRV_PRIVATE_CFG
You should set up your private configuration file so it contains information specific to the work you are
performing. For example, you can set up your own tables in databases in which to store project data. You
can also override many of the default settings provided in the shared and site configuration files.
About the Site Configuration File

If you create a site configuration file, you call it <your_product_name>.cfg, and place it in the templatebased product site repository. You can have only one site configuration file for a site installation of your
template-based product. The site configuration file provides settings common to users at a particular site.
For example, your company may have engineers working across a network, each wanting toaccess some
common information, such as files and variables. You could set up the site configuration file so that when
they run the site version, each engineer's session is configured to access the common information.
We recommend that only the site manager changes the site configuration file. You should make any
personal modifications using private configuration files.
About the Shared Configuration File

The shared configuration file is called <your_product_name>.cfg, and is generally found in the
installation directory. See your system administrator for location details.
Only one shared configuration file exists for an installation of your template-based product. The shared
configuration file contains predefined information common to all users.
We recommend that no one changes the shared configuration file. You should make any personal
modifications using private configuration files, and any common changes for multiple users in site
configuration files.
About Plugin Configuration Files

Many plugins that work with the Template Builder have their own shared and site configuration files.
Your template-based product follows the same logic for processing the plugin configuration files as it
does for any other configuration file.
Format of Configuration Files

A configuration file is divided into the blocks listed below. An example of the blocks in a configuration
file are shown in figure Configuration File Blocks. In the example, ! indicates comments.
Environment Variables - The first block in a configuration file sets up the environment of your
template-based product. For example, it identifies the type of user associated with the
configuration file. It also sets the mode in which your template-based product starts, Standard
Interface or Template Builder, and any other environment settings.
367
368 Adams/Car
Databases - The second block defines the databases in which users store files, the order in which
your template-based product searches databases, and the database to which files are written by
default.
Table Directories - The third block defines the list of personal table directories. For example,
you could create a table in which to store examples.
Property Files - The fourth block contains a listing of default property files. When a dialog box
requires a property file, it automatically knows to load the desired files if you enter property files
in the property file block. You usually define property files in the shared configuration file. If
you enter values in your private configuration file, your template-based product overrides the
shared files with your personal property files.
Test Rigs - The fifth block defines the default test rig for a given assembly class. When a dialog
box requires a test rig, it automatically knows to load the desired test rigs. You usually define test
rigs in the shared configuration file.
Configuration File Blocks

!-------------------------------------------------------------------!
!*************** Adams/X Configuration File *************** !
!-------------------------------------------------------------------!
!-------------------------------------------------------------------!
! - List of personal environment variables
!-------------------------------------------------------------------!
ENVIRONMENT MDI_ACAR_USERMODE expert
!-------------------------------------------------------------------!
! - List of personal database directories
!
Database name
Path of Database
!-------------------------------------------------------------------!
DATABASE
private
/usr/private.cdb
DATABASE
staff
/staff/private.cdb
DEFAULT_WRITE_DB private
!
!-------------------------------------------------------------------!
! - List of personal tables directories
!
Type class
Name of table
Extension
!-------------------------------------------------------------------!
! Example table entry:
!TABLE
list2+
example.tbl
exa
!
!-------------------------------------------------------------------!
! - List of personal default property files
!
Type class
Default property file
!-------------------------------------------------------------------!
! Example property file entry:
!PROPFILE
assembly
<private>/assembly.tbl/myfile.dpr
!
! Example test rig entry:
!TESTRIG four_post .__MY_FOURPOST
Setting Up the Environment Through Configuration

Files
To work efficiently with your template-based product, you must set a standard set of environment
variables in a configuration file. The environment variable has the following format:
ENVIRONMENT
VARIABLE_NAME
VARIABLE_VALUE
We've set up default environment variables in the shared configuration file, but we recommend that you
redefine them in the private or site configuration file to customize the work environment of your
template-based product. You can also define your own environment variables for use with user-written
subroutines or macros.
Learn about the standard environment entries that you can set and how to create your own environment
variables:
Setting User Access
Accessing Adams/View
Setting Defaults and Display of the Welcome Dialog Box
Replacing the Image on the Welcome and Exit Dialog Boxes
Setting Up Side Preferences
Setting the Orientation of the Global Reference Frame
Managing Result File Output
Redefining Environment Variables
Defining Your Own Environment Variables
Editing Files Using a Text Editor
Setting User Access

You use the MDI_ACAR_USERMODE keyword in your private configuration file to set your user
access, which determine you access to the Template Builder and other development tools. Your private
Note:
acar.cfg file located in the installation.
You can set USERMODE to:

STANDARD - User can only access the Standard Interface.
369
370 Adams/Car
EXPERT - User can access the Template Builder and create and modify templates. User can
access the Template Builder and other development tools that are located under the Tools menu.
Expert users can use the MDI_ACAR_PLUS_AVIEW keyword in the private configuration file
to access Adams/View. Learn about accessing Adams/View.
To change the value of this keyword, you must edit the private configuration file (.acar.cfg) using a text
editor and modify the corresponding string. The following gives you expert access:
! Desired user mode (standard/expert)
When you start a new session, your template-based product reflects the changes to the private
configuration file.
Accessing Adams/View
If you are an expert user, you can use the MDI_ACAR_PLUS_AVIEW environment variable in the
private configuration file to obtain access to Adams/View.
MDI_ACAR_PLUS_AVIEW has the following format:
ENVIRONMENT
MDI_ACAR_PLUS_AVIEW
(yes, no)
To access Adams/View:
1. Set MDI_ACAR_PLUS_AVIEW to yes.
2. From the Tools menu, select Adams/View Interface.
To return to your template-based product:
From the Tools menu, point to Select Mode, and then select the interface mode to which you
want to return: Standard Interface or Template Builder.
Setting Full Vehicle Solver Preference/Solver Preference

You can set your solver preferences, either from the settings menu or in your private configuration file.
Setting HHT Integrator Preferences

If using Adams/Solver (C++), you can also set a preference for using the HHT integrator as the the
default integrator, as explained next.
To set HHT integrator preference:
1. In a text editor, such as Jot or Notepad, open .acar.cfg in your home directory.
2. Add the following line to set HHT as the default integrator:
ENVIRONMENT
MDI_AENG_HHT_ERROR 1e-5
This sets the HHT integrator as the default integrator with a default error tolerance of 1e-5 when
using Adams/Solver (C++).
3. Start a new session.
Setting Defaults and Display of the Welcome Dialog Box

Setting Defaults
You can use the MDI_ACAR_INITMODE environment variable to set the default selection in the
Welcome dialog box when the user has expert-user access. MDI_ACAR_INITMODE has the following
format:
ENVIRONMENT
MDI_ACAR_INITMODE
(template_builder, standard_interface)
In Adams/Driveline for example, if you set MDI_ACAR_INITMODE to standard_interface, the

Welcome dialog box sets the selection of Standard Interface as the default, as shown next.
Setting the Display

You can use the MDI_ACAR_MODEPROMPT environment variable to set your template-based
product so that it does not display the Welcome dialog box at start up. MDI_ACAR_MODEPROMPT
has the following format:
ENVIRONMENT
MDI_ACAR_MODEPROMPT
(yes, no)
Setting it to yes displays the Welcome dialog box; setting it to no turns off the display of the Welcome
dialog box.
371
372 Adams/Car
Replacing the Image on the Welcome and Exit Dialog Boxes

You can replace the image on the Welcome and Exit dialog boxes with another image.
To replace the image:
1. Create a color X pixmap image (.xpm) with a size of approximately 197 x 192 pixels.
2. Copy the new pixmap file to a designated directory.
3. Add the following entry in your .acar configuration file:
ENVIRONMENT MDI_ACAR_LOGO_BMP <your_directory/filename>
Setting Up Side Preferences

You can use the MDI_ACAR_SIDE_PREF environment variable to define the preferred side for
creation. When you set the side preferences:
The creation dialog box in the Template Builder sets the default type based on the side
preference you set.
The guesses in the pop-up menus in dialog boxes only contain left and single or right and
single entities based on the side preference. Your template-based product does this to limit the
number of guesses.
The MDI_ACAR_SIDE_PREF environment variable has the following format:

ENVIRONMENT
MDI_ACAR_SIDE_PREF
(right, left)
Setting the Orientation of the Global Reference Frame

You can set the orientation of the global reference frame using direction cosines. You use either of the
following environment variables to define the orientation:
ENVIRONMENT
ENVIRONMENT
MDI_ACAR_VEHICLE_REAR
MDI_ACAR_VEHICLE_LEFT
1,0,0
0,-1,0
Managing Result File Output

Result files include all the simulation output from an analysis. The following environment variable sets
the default attribute of whether the result file is output during the analysis. If the assembled model
contains flexible bodies, your template-based product automatically outputs a result file regardless of the
environment variable setting.
If the assembled model does not contain flexible bodies, use the following command (example is for
Adams/Car) to indicate that you want your template-based product to output a result file:
ENVIRONMENT
MDI_ACAR_WRITE_RES
(yes, no)
If a result file exists, your template-based product will automatically read it in with the analysis, if you
run an interactive simulation.
If you run the simulation externally (background, files_only), you can read in the result file using either
of these two methods:
Review -> Analysis Management -> Read
File -> Import -> Adams Results File (*.res)
Redefining Environment Variables

We've set up default environment variables in the shared configuration file, but we recommend that you
redefine them in the private or site configuration file to customize the work environment of your
template-based product.
To redefine environment variables, use the format below. Your template-based product initializes the
variables at startup.ENVIRONMENT VARIABLE_NAME VARIABLE_VALUE
The following gives you expert access to your template-based product:
ENVIRONMENT
MDI_ACAR_USERMODE
expert
Defining Your Own Environment Variables

You can define your own environment variables in the private and site configuration files for use with
user-written subroutines or macros. For example, you can define a variable named debug_mode in your
private or site configuration file. Then, in your own macros, you can query for the value of debug_mode,
and execute some instructions depending on its value. The example below shows a portion of the macro
that would query for the value of debug_mode:
IF condition =(getenv("debug_mode")=="yes")
default command echo=on
END
.
.
.
To define your own environment variables, use the format below. Your template-based product initializes
the variables at startup
ENVIRONMENT
VARIABLE_NAME
VARIABLE_VALUE
For the previous example, you would use the following:

ENVIRONMENT
debug_mode
yes
373
374 Adams/Car
Editing Files Using a Text Editor

You can use an environment variable to edit files from within your template-based product. Creating this
environment variable in your .acar.cfg file causes the View Property File tool
to launch your text
editor instead of the Information window. In the variable, simply specify the location of your preferred
text editor executable.
For example, an Adams/Car user who wants to launch Wordpad would set up the environment variable
as follows:
ENVIRONMENT MDI_ACAR_USE_EDITOR C:\Program
Files\WindowsNT\Accessories\wordpad.exe
Managing Databases Through Configuration Files

You can use two environment variables to manage your template-based product's databases in the
configuration file:
DATABASE - Sets up databases.
DEFAULT_WRITE_DB - Sets the default writable database.
You can place DATABASE entries in the private, site, or shared configuration files. The
DEFAULT_WRITE_DB, however, is reserved for the private and site configuration files.
Note that you can also set up databases through menus, as explained in Managing Databases. You may
find it more convenient to use the menus.
Learn more about managing databases through configuration files:
Setting Up Databases
Specifying Default Writable Database
Setting Up Databases
You can define databases in your template-based product using the keyword DATABASE. A
DATABASE keyword entry has the following format:
DATABASE
DB_NAME
DB_PATH
In the format, DB_NAME is the name assigned to the database and DB_PATH is the location of the
database in your file system. You can add any database to the DATABASE definition in any
configuration file. If the database does not exist, your template-based product creates it in the specified
location and adds it to the database list.
Specifying Default Writable Database

You can specify the database that you want to use as the database to which all files are written. You use
the environment variable DEFAULT_WRITE_DB to define the default writable database. The
DEFAULT_WRITE_DB environment variable has the following format:
DEFAULT_WRITE_DB
DB_NAME
The environment variable defines the initial database that you want as the default location for writing
files. Usually, you define the default writable database in your private configuration file, although you
can set the writable database in any configuration file. You can change it during the session as explained
in Setting the Writable Database. Note that you will need permission to write to the file system location
to which the DEFAULT_WRITE_DB points.
375
376 Adams/Car
Managing Tables Through Configuration Files

As explained in Database Structure, a template-based product's database is comprised of a number of
directories or tables in which you store files. In addition to the standard set of table directories, you can
create your own tables.
Generally, you only add table directories to the databases defined in your private configuration file. As
the site manager, you may decide to add tables for general use in the site configuration file.
Learn more about creating tables and the standard table entries:
Creating Tables
Standard TABLE Directory Entries
Creating Tables
At start up, your template-based product determines when to create new table directories as follows:
1. Your template-based product verifies that all database directories defined in the private
configuration file contain table directories for the corresponding table directories also defined in
the private configuration file.
2. If a table directory does not exist inside the database, your template-based product creates one.
3. If a site configuration file exists, your template-based product ensures that for any table directory
specified in the site configuration file, a corresponding table directory exists for all database
directories defined in both the site and private configuration files.
4. Your template-based product ensures that for all table directories specified in the shared
configuration file, a corresponding table directory exists for all database directories defined in the
private, site (if it exists), and shared configuration files.
The TABLE keyword entry for creating tables has the format:
TABLE
TABLE_CLASS
TABLE_NAME
TABLE_EXTENSION
where:
TABLE_CLASS - A string identifying the table.
TABLE_NAME - The name that you want used to access the table.
TABLE_EXTENSION - The three-character extension of files stored in the table. Your
template-based product only recognizes files in the table that have the extension that you specify.
For example, the following creates a table that stores aerodynamic forces:
TABLE
aeroforces
/staff/my_name/my_db.cdb/aeroforces.tbl
aer
Adding the table definition shown above in the configuration file causes your template-based product to
recognize and correctly access files stored in that particular database table.
Standard TABLE Directory Entries

The TABLE directory entries in the shared configuration file are briefly explained in the following
tables:
Adams/Car Standard TABLE Entries
They are the standard set of tables that are distributed with your template-based product's database. You
cannot reconfigure TABLE entries. Changing these values disables your template-based product's ability
to assign properties to a class of entities.
Managing Property Files Through Configuration Files

A PROPFILE environment variable in the configuration file assigns a default property file used when
creating the following entity types: bumpstop, bushing, damper, reboundstop, spring, and tire.
A PROPFILE environment variable in a configuration file has the following format:
PROPFILE
PROPFILE_CLASS
PROPFILE_NAME
where:
PROPFILE_CLASS is a string that identifies the property file.
PROPFILE_NAME is the name of the property file.
For example:
PROPFILE
bushing
mdids://shared/bushings.tbl/mdi_0001.bus
You can define the property files in the private, site, or shared configuration files.
Managing Test Rigs Through Configuration Files

A TESTRIG environment variable in the configuration file assigns a default test rig to a particular class
of assemblies.
A TESTRIG environment variable in a configuration file has the following format:
TESTRIG
TESTRIG_CLASS
TESTRIG_NAME
where:
ASSEMBLY_CLASS is a string that identifies the type of assemblies which correspond to the
test rig.
TESTRIG_NAME is the name of the test rig model.
For example:
TESTRIG
four_post
.__MY_FOURPOST
You can define the default test rigs in the private, site, or shared configuration files.
377
378 Adams/Car
Customizing Your Product
380 Adams/Car
Overview
If you are an expert user or site manager, you can customize your template-based product to your
company's needs and preferences. You can extend your template-based product by adding new
functionality, modifying standard functionality, or tailoring its appearance to fit the needs of your work
environment. Customizing your template-based product lets you create a familiar environment in which
users can work.
Note:
You cannot customize all dialog boxes and tools. For example, you cannot customize the
Plugin Manager or the Information window. The Dialog-Box Builder's Dialog Box ->
Open menu provides access to those dialog boxes, containers, and toolbars that you can
customize.
You can typically modify your template-based product in three main areas. These require different levels
of understanding, ranging from the Adams macro language, Standard Developer Kit (Adams/SDK),
through FORTRAN and C solver routines, as described next.
Customizing the interface - Involves creating or modifying interface objects, such as macros,
dialog boxes, menus, and windows. This uses Adams command language to modify the look and
feel of the interface. It can be used to automate recurring tasks, using the scripting language, but
has limitations in terms of speed and would not be used to generate computationally complex
objects (1000 parts located and oriented to generate a chain). For these tasks, you would use an
Adams/View library written in C.
Note:
You save interface objects and macros in custom binaries.
Creating a custom Adams/View library - Takes advantage of user-written subroutines and
functions to automate highly repetitive and computationally complex tasks in an efficient

manner, using C. Using functions delivered in the SDK, you can quickly generate and
manipulate Adams elements.
Creating a custom Adams/Solver library - Create user-written subroutines and functions to
extend the functionality of your template-based product in terms of the solver. You save them in
custom libraries for later use.
Note:
For Adams/Driveline - Because of the plugin structure of Adams/Driveline, you cannot

create a custom version. You can, however, create a custom Adams/Car version, adding
your own custom elements, analyses, and so on, and then load in the standard
Adams/Driveline plugin.
Once you have finalized your customization of your template-based product, you can store your
customized dialog boxes, macros (binary files), Adams/View and Adams/Solver libraries in a site
directory, for use by all users, or in a private directory for personal use. You can extend this hierarchy to
support multiple operating systems from one installation.
Select an entry on the left to learn how to efficiently customize the environment of your product.
381
382 Adams/Car
Customizing the Interface

All of the menus, windows, and dialog boxes that you see in your template-based product are interface
objects that you can modify easily. Most of the interface customization that you'll do involves creating
new dialog boxes, modifying existing ones, or modifying menus and push buttons. Learn about saving
changes to interface objects.
A template-based product stores the interface objects in its modeling database along with all the other
modeling objects (such as parts, models, and markers). You access the interface objects through the
Database Navigator. The objects have a defined hierarchy, which you can also view through the Database
Navigator. You use the Adams/View Dialog-Box Builder to access and edit the interface objects that you
can include in a dialog box, such as labels, fields, and buttons.
For an overview of all aspects of customizing an Adams product interface, including menus, and using
the Dialog-Box Builder, see the Adams/View online help.
Learn more about customizing the interface:
Naming Conventions
Using Libraries
Creating and Modifying Dialog Boxes
Creating and Modifying Macros
Creating Dialog Boxes for Templates
Adding a Minor Role
Adding a Major Role
Creating Menus for Template Builder
Automatically Loading Interface Changes
Saving Interface Changes
Naming Conventions
We recommend that you use a naming convention when you create and modify interface objects or
macros. A naming convention reduces the chances of naming conflicts and provides a simple method for
organizing files, macros, and dialog boxes.
The naming convention that we recommend is the same one that template-based products currently use.
The naming convention uses the abbreviation of the object (for example, mac for macro) followed by a
set of characters that identify the commands or functionality that the object executes or performs. The
naming conventions for macros and dialog boxes are explained next.
Macro naming convention - The macro naming convention uses the abbreviation mac for
macro followed by the first three characters of each command in the user-entered command that
executes the macro. For example, if the user-entered commands for a macro are as shown below
(the first three characters are highlighted in boldface type):
acar analysis
suspension
Then, the name of the macro is:
single_travel
submit
mac_ana_sus_sin_sub
Dialog box naming convention - The naming convention for dialog boxes uses the abbreviation
dbox for dialog box followed by the first three characters of the words that identify the
functionality of the dialog box. For example, if a dialog box is the interface through which a user
creates a hardpoint, then the words that define its functionality are:
template_builder
and, its name is:
hardpoint
create
dbox_tem_har_cre
If, however, the dialog box performs two or more functions, as many dialog boxes do, then the
dialog box name does not include the words for the function. For example, if a dialog box lets a
user both create and modify a spring damper, the words that define its functionality are:
template_builder
and, its name is:
damper
create/modify
dbox_tem_dam
Using Libraries
We recommend that you use libraries to store the interface objects and macros that you create. Libraries
are repositories for Adams/View objects such as variables, assembly instances, macros, and dialog
boxes. Using libraries allows you to easily find, retrieve, or remove specific custom objects. You can add
to your template-based product as many libraries as you need. You can also have libraries within
libraries.
Your template-based product stores all its objects in libraries, named as follows:
Product name:
Library name:
Adams/Car .ACAR
You can view the objects in the library using the Database Navigator.
To create libraries, execute the following command either in your .cmd file or during an interactive
session. In the following command, MY_LIBRARY is the name of the library that will be created:
library create library_name=.MY_LIBRARY
Alternatively, you can add the command in the file you use to generate the site or private custom binary.
The files are named as follows:
383
384 Adams/Car
Product name:
File name:
Adams/Car acar_build.cmd
Learn more about those files.
Libraries can also be nested. For example:

library create library_name=.MY_LIBRARY.variables
library create library_name=.MY_LIBRARY.variables.torques
Creating and Modifying Dialog Boxes

The template-based products use dialog boxes to provide you with an easy way to input data or perform
operations. A dialog box is usually an entry point to a custom or standard macro. The dialog box collects
data from you, manipulates it, and then communicates the data to a macro or to an Adams/View function,
which performs an operation using the data. Learn about macros.
Although you can set up a dialog box so that commands perform a particular task within the dialog box,
we recommend that you use the dialog box as an entry point to a macro or a set of macros. By making
the dialog box an entry point to a macro, you:
Are consistent with the standard dialog boxes in template-based products.
Take advantage of the Adams powerful macro language programming.
Note that we supply many examples of how to code dialog boxes. You can find those examples in their
respective libraries. For example, acar.dboxes.
The next topics explain more about creating dialog boxes. For a general overview of creating and editing
dialog boxes in Adams products, see the Adams/View online help, under the Customize tab.
Dialog Box Objects
Layout and Sizing of Dialog Boxes
Commands in Dialog Boxes
Dialog Box Error Handling
Start, Execute, and Finish Commands
OK, Apply, and Cancel Buttons
When you have finished modifying your dialog boxes, review the options for saving your changes and
having them automatically included in your own version of your template-based product. Learn about
saving dialog boxes.
Accessing Dialog Box Programming Tools
You use the Dialog Box command on the Tools menu to create and modify dialog boxes.
To view, change, and create dialog boxes, you must have expert user access to your template-based
product.
Dialog Box Objects
Dialog boxes are a combination of different interface objects that you can modify using the Dialog-Box
Builder. These include the following:
List of Common Dialog Box Objects
The objects:
Are:
Containers
Subregions in a dialog box that can hold objects.
Text boxes
Boxes in which you can enter information.
Pull-down menus
Menus that display a list of options from which you can select only
one option.
Radio boxes
Toggles that set a state or mode. You can only select one state or
mode.
Toggle buttons (Check boxes)
Toggles that indicate an active state. You can select more than one
state.
Push buttons
Buttons that execute a command or set a state.
Sliders
A continuous range of possible values from which you can select one
value.
The following figure shows some of the different objects.
385
386 Adams/Car
Layout and Sizing of Dialog Boxes

When you create dialog boxes, always try to minimize the amount of screen area that they take up. To be
consistent with the other dialog boxes in your template-based product, you should use the size
specifications listed in tables Standard Interface Dialog Box Specifications and Template Builder Dialog
Box Specifications. The specifications also include where on the screen dialog boxes should appear, so
they always appear in the same location on the screen.
We also recommend that you fix the height of dialog boxes. In most cases, only the ability to change the
width of a dialog box is useful to a user because he or she may want to stretch the dialog box to see the
full name of an object in a particular text box. This isn't really necessary for the height of a dialog box.
To fix the height of a dialog box, include the parameters height_minimum and height_maximum in the
interface command that creates the dialog box. You must do this directly in the command file that
contains the commands to create the dialog box. You cannot do this through the Dialog-Box Builder. For
example, for Adams/Car, you can enter:
interface dialog modify &
dialog=.ACAR.dboxes.dbox_tem_har_mod &
height=150.0 height_minumum=150.0 height_maximum=150.0
When building dialog boxes, always test to ensure that the resizing attributes of each object in the dialog
box are appropriate. Under Resizing in the Dialog-Box Builder, there are resizing attributes for interface
objects. These attributes describe how the size of the objects on a dialog box are affected if the width or
height of the dialog box changes. You should set the resizing attributes of the objects on a dialog box so
that if the size of the dialog box changes, the general look of the dialog box remains the same. For
example, if all the text boxes in a dialog box are right justified along the edge of the dialog box, the text
boxes should all remain right justified if you increase or decrease the width of the dialog box.
Standard Interface Dialog Box Specifications
For the dialog box attribute:
Set its position or size to:
Location 3
3, 154
Width 3
70
Label width
150
Label height
25
Text box width
240
Template Builder Dialog Box Specifications

Location 15
, 150
Width 40
Label width
150
Label height
25
Text box width
244
Commands in Dialog Boxes

All of the objects in dialog boxes can execute commands when a user acts on the object. For example, a
button can execute a command when a user pushes on it, and an option choice can execute a command
when a user selects that option from a pull-down menu. Having an object execute a command gives you
great flexibility in how your dialog box works.
For example, you can set up your dialog box so that the commands assigned to a particular database
object field can:
Check to determine whether the object that the user selects exists in the database
Issue a warning message if it does not exist
You can also have commands operate on other objects in dialog boxes, which causes the dialog box to
change its appearance when a user makes a selection from an object. For example, when a user selects
an option from a pull-down menu, the dialog box changes to display objects for entering values for the
selected option as shown next.
387
388 Adams/Car
Dialog Box Error Handling

Each dialog box that you create should have a variable, named errorFlag, that represents the error
condition of the dialog box. You should use the start commands of a dialog box to create the variable and
set its initial value to zero or no error condition, as shown next:
variable set variable_name=$_self.errorFlag int=0
You should also reference the variable in the OK command that executes the dialog box.
For information on:
Variables, see Using Local Variables.
$_self, see Using Commands in Dialog Boxes.
OK command, see OK, Apply, and Cancel Buttons.
Start, Execute, and Finish Commands

You can assign start, execute, and finish commands to higher-level objects, such as containers, and to the
dialog box itself. The commands are described below.
Start commands - Your template-based product automatically executes start commands
associated with a particular interface object when that object is displayed. The start commands
ensure, for example, that the dialog box is displayed properly based on the display parameters.
You should use the start commands to set an errorFlag variable to an initial value of zero, or no
error condition, as shown next:
variable set variable_name=$_self.errorFlag int=0
Template Builder dialog boxes usually have two possible startup parameters, which you should
set up in the start commands when a dialog box is displayed. The states are:
mode - Mode has two states, which represent the creation or modification states of a dialog
box. The states are create and modify.
object - Object used with the state modify.
An example of using the states in a start command for Adams/Car:

interface dialog display dialog=.ACAR.dboxes.dbox_tem_dam &
parameters="modify", ".template1.dal_ride_damper"
Execute commands - The execute commands of a dialog box usually work with OK and Apply
buttons. You should limit the execute commands to calling macros because we recommend that
you use dialog boxes as a front-end to macros. Using dialog boxes as input mechanisms to
macros ensures consistency and upgradeability.
Finish commands - Your template-based product automatically executes finish commands
when an object is no longer displayed. You use them to clean up after a macro, delete
unnecessary objects, such as temporary variables, and so on.
To clean up variables:
You can use the command:
variable delete variable_name=(eval(db_children($_self, "variable")))
To clear the text boxes of a dialog box:
You can use the command:
for var=$_self.loopobj
object(eval(db_children($_self,"graphic_interface_field")))
interface field set
field=(eval($_self,"graphic_interface_field")))
string="" execute=no
end
OK, Apply, and Cancel Buttons
Each dialog box in your template-based product has three standard buttons:
389
390 Adams/Car
OK - Executes the commands associated with the dialog box, and if it executes the command
successfully, it exits the dialog box.
Apply - Executes the commands associated with the dialog box but leaves the dialog box open
so that you can execute the command again.
Cancel or Close - Exits the dialog box without executing a command or executing only a
selected command. Only dialog boxes that have an Apply button have a Close button.
Button Size
To keep your dialog boxes consistent with the dialog boxes of your template-based product, you should
always keep the size of these buttons to 25 pixels high and 76 pixels wide.
Error Handling
Make sure that the commands associated with the OK button reference the dialog box error variable
(errorFlag). By referencing the error variable you ensure that the dialog box will not be closed if an
errorFlag was set during the execution of the dialog box commands. Because the following commands
are generic, you can use them to reference the errorFlag with any dialog box:
interface dialog execute dialog=$_parent undisplay=no
if condition=(!$_parent.errorFlag)
interface dialog undisplay dialog=$_parent
end
Learn about error handling in dialog boxes.
Creating and Modifying Macros

A macro is a collection of single commands that enable you to perform a series of actions during a
session. You write commands using the Adams/View command language.
You can modify the existing macros or add customized macros to your template-based product so your
users work smarter in their template-based product. For example, in Adams/Car you can write a macro
to perform a particular full-vehicle analysis. By implementing the macro, a user only needs to enter the
requested values for the analysis in adialog box and push a button. The button executes the macro, which
performs the full-vehicle analysis.
You can use macros to:
Automate repetitive procedures.
Build general-purpose extensions, such as custom analyses, to your template-based product.
See an example of creating a macro. Although this is an Adams/Car example, you can use the general
concepts to create a macro for any template-based product.
For a complete overview of creating macros, see About Creating Macros.

Learn more about adding macros to your template-based product:
Accessing Macro Programming Tools
Viewing Existing Macros

Using Parameters
Using the Echo Command
Using Local Variables
Macro Error Handling
When you have finished modifying your macros, review the options for saving your changes and having
them automatically included in your own version of your template-based product. Learn about saving
macros.
Accessing Macro Programming Tools
You use the Macro command on the Tools menu to create and modify macros. For information on the
Macro command, see Editing and Creating Macros Using the Macro Editor.
To view, change, and create macros, you must have expert user access to your template-based product.
Viewing Existing Macros
Because macro programming is so well developed in your template-based product, you may find it
helpful to look at existing macros. Once you find a macro that most closely meets your needs, use it as
the basis of customization.
As you look at the existing analysis macros within your template-based product, notice that all of them
have the same basic structure.
To view existing macros:
1. From the Tools menu, point to Macro, point to Edit, and then select Modify.
The Database Navigator appears.
2. Select a macro to view.
The Macro Editor appears with the macro commands of the selected macro in the Commands text
area.
Using Parameters
Parameters are placeholders for information that users provide when they execute a macro in a templatebased product. You write parameters in a macro as a $followed by the name of the parameter. Parameters
let you make macros very flexible. When you create a macro, your template-based product scans the
command text to identify all the parameters.
When you issue the command to execute the macro, you provide values for the parameter or the
parameters assume default values. Your template-based product substitutes the values in place of the
parameters in the macro and executes the macro commands.
You identify parameters in macros using qualifiers. Qualifiers define a parameter's type, range, count
(number of values), and defaults.
391
392 Adams/Car
The following is an example of a list of parameters and their qualifiers for a macro:
! $part_name:t=string
! $location:t=location
! $type:t=string
! $orientation:t=orientation
! $mass:t=real
! $cm_location_from_part:t=location:d=0,0,0
! $Ixx:t=real
! $Iyy:t=real
! $Izz:t=real
! $Ixy:t=real:d=0
! $Izx:t=real:d=0
! $Iyz:t=real:d=0
!END_OF_PARAMETERS
Using the Echo Command
The command echo=on, which is the default, is a very helpful command because it lets you review the
full log of the macro execution in the command window or echoed in the acar log file.
To use the echo command, you can add the following line at the top of your macro:
default command echo=on
You will find it very helpful for debugging purposes.
Using Local Variables
You can create Adams/View variables to be used in your macros. A variable is storage location that can
contain data. Once you define a variable, you can use it in any parameter, macro, or function in your
You can define a variable as a child of any modeling object, including a macro. Defining a variable as a
child of a macro is helpful in macro programming when you need to create auxiliary Adams/View
variables, such as variables that call an Adams/View function or that act as a return variable from a called
macro. Being able to create these variables as children of the macro results in a cleaner macro.
As a child of the macro object, the variable inherits the object's name. Therefore, the text $_SELF
evaluates to the name of the parent object, which is the macro.
In addition, most often you will want to delete these auxiliary variables when the macro is finished.
Creating these variables under the macro simplifies this cleanup procedure.
You can delete local variables very easily as shown next:
To use local variables:
You should do the following:
variable set variable_name=$_self.filename &
string_value="tmpfile.cmd"
To clean up local variables:

You should do the following:
variable delete variable_name=(eval(db_children($_self,"variable")))
For more information on variables and the commands to create and clean them up, see the help in the
Command Navigator associated with the command variable.
Macro Error Handling
Each macro that you create should have checks to:
Identify inappropriate or invalid user-entered values.
Ensure that the values specified by the user for specific parameters are realistic.
The following Adams/Car example shows how error handling works in a macro. The acar toolkit
warning utility macro displays a message in a window, informing you that it encountered an error
condition. The window remains open until you close it.
!---- Ensure a brake subsystem exists ---if condition=(!subsystem_role_exists($assembly,"brake_system"))
acar toolkit warning &
warning="This assembly does not have a brake subsystem!"
variable set variable_name=$error_variable integer=1
return
end
You can use the acar toolkit in all template-based products.
Creating Dialog Boxes for Templates

In your template-based product's Template Builder, you can create your own dialog boxes to access
parameters within a template that you may want to modify on a regular basis.
After you create a custom dialog box, you can attach it to a particular template. When you save the
template to your default writable database, your product saves the dialog box with the template. You can
also export dialog boxes as command files, and later import them into other templates.
We recommend using your template-based product's dialog boxes as a starting point to understand what
you can achieve with the Dialog-Box Builder.
To create a custom dialog box for templates:
1. From the Build menu, point to Custom Gui, point to Dialog Box, and then select Create.
Your product displays an empty dialog box named dbox_1, along with the Dialog-Box Builder.
2. Add buttons and commands as explained in Customizing Dialog Boxes Using the Dialog-Box
Builder in the Adams/View online help.
3. To close the Dialog-Box Builder, from the Dialog-Box Builder's Dialog Box menu, select Exit.
393
394 Adams/Car
To validate your dialog box:

From the Dialog-Box Builder's Option menu, select Test Box.
To permanently attach the dialog box to a template:
Note:
If you do not attach your dialog box to a template, the dialog box will be lost when you
close the current session.
1. From the Build menu, point to Custom Gui, point to Dialog Box, and then select Attach.
2. Select << Add.
3. In the Selections dialog box, double-click the name of your dialog box. In this case, dbox_1. If
you have multiple dialog boxes you want to store, repeat these steps for each dialog box.
4. Select OK.
To verify that your product stored your dialog box:
1. From the Build menu, point to Custom Gui, point to Dialog Box, and then select Display.
2. In the Selections dialog box, double-click the name of the dialog box you want to display.
Your product displays the dialog box.
To export a custom dialog box:
From the Dialog Box Builder's Dialog Box menu, point to Export, and then select Command
File.
To import a dialog box:
To import a dialog box from a command file and attach it to a template, you must manually
rename every entity in the command file for .ACAR.custom. For example:
MY_LIBRARY.dboxes.dbox_1 becomes .ACAR.custom.dbox_1
MY_LIBRARY.dboxes.dbox_1.field_1 becomes .ACAR.custom.dbox_1.field_1
Adding Minor Roles

The file <product_name>BS.cmd is a command file that your template-based product automatically
reads in when you start a new session. You use this type of file to add a new minor or major role to your
To add a new minor role in your template-based product:
1. Create a command file named <product_name>BS.cmd (where product_name is the
abbreviation for your product). The contents of the command file should be similar to the contents
of the following Adams/Car command file:
!--- Add a new minor role ----
variable modify variable=.ACAR.variables.minor_roles &

string_value=(eval(.ACAR.variables.minor_roles)),"rear2"
2. Place the command file in your home directory.

3. When your template-based product starts, it automatically reads in <product_name>BS.cmd. The
command file will expand the minor roles available in your template-based product. The
minor_roles variable is referenced everywhere in the underlying software and is the only change
required to allow you to create new subsystems with minor roles different than the default.
4. Create a new subsystem with the new minor role. (File -> New -> Subsystem).
Notice the new entry in the Minor Role option menu.
Keep in mind the new minor role you define when you are creating/matching communicators.
Adding Major Roles

The file <product_name>BS.cmd is a command file that your template-based product automatically
reads in when you start a new session. You use this type of file to add a new minor or major role to your
Learn how to add minor roles.
To add a new major role in your template-based product:

1. Create a command file named <product_name>BS.cmd (where product_name is the
abbreviation for your product). The contents of the command file should be similar to the contents
of the following Adams/Car command file:
!--- Add a new major role ---variable modify variable=.ACAR.variables.major_roles &
string_value=(eval(.ACAR.variables.major_roles)),"subframe"
2. Place the command file in your home directory.

3. When your template-based product starts, it automatically reads in <product_name>BS.cmd. The
command file will expand the major_roles available in your template-based product. The
major_roles variable is referenced everywhere in the underlying software and is the only change
required to allow you to create new subsystems with major roles different than the default.
4. Create a new template with the new major role. (File -> New).
5. Notice the new entry in the Major Role option menu.
Creating Menus for Template Builder

You can modify your template-based product to add custom menus and buttons to the Template Builder:
Submenu - You can create submenus using the Build menu. A submenu provides a container
that you can use to collect push buttons (in this context, think of push buttons as options located
under a submenu). For example, under the Build menu, Hardpoint is a submenu containing five
push buttons/options (Modify, Table, New, Info, and Delete), as shown next.
395
396 Adams/Car
Push button - You can use a push button to execute a command such as displaying a dialog box
or executing a macro.
When creating menus, we recommend that you first think about the structure of what you are trying to
achieve. By using a hierarchical approach, you can use submenus to categorize different buttons.
In the following example we assume that you have created a custom dialog box named dbox_1. We are
first going to create a submenu named Example.
To create a submenu:
1. From the Build menu, point to Custom Gui, point to Menu, point to Submenu, and then select
Create.
Your product displays the Create Custom Submenu dialog box.
2. Enter the label that you want to use, in this case Example, and then reference the template in
which this custom menu will be stored.
3. Select OK.
Now you create a push button that resides as a child of submenu, and call the button Display. You then
execute a command to display the custom dialog box, dbox_1.
To create a push button:
1. From the Build menu, point to Custom Gui, point to Menu, point to Push Button, and then
select Create.
Your product displays the Create Custom Push Button dialog box.
2. Enter the label that you want to use, in this case Display.
3. Set Parent Menu to menu1, which is the submenu Example you created above. Note that as you
create submenus, your product references them internally as menu1, menu2, and so on, rather
than by name (in this case, Example). If you created several submenus and lost track of their
names, you can use the Info command to see how your product names them: from the Build
menu, point to Custom Gui, point to Menu, and then select Info.
4. The execution command is highly dependent on what you want to achieve. In this example, you
want to display the custom dialog box, dbox_1, so in the Commands text box enter:
interface dialog_box display dialog_box_nam = .ACAR.custom.dbox_1
If, however, you wanted to view the front view of your model, you would enter a command
similar to the following:
acar interface view_restore view_orientation = front
5. Select OK.
6. To validate that the push button works, from the Build menu, point to Example, and then select
Display. Your template-based product should display your dialog box.
To change the order of your submenus:
1. From the Build menu, point to Custom Gui, point to Menu, and then select Reorder.
2. Press F1 and then follow the instructions in the dialog box help for Reorder Custom Menus.
To get information about your custom menu structure:
From the Build menu, point to Custom Gui, point to Menu, and then select Info.
Your product displays the information in the Information window.
Automatically Loading Interface Changes

You can configure the user interface by automatically reading one of the start-up scripts for your
template-based product. Learn more.
The following is an example command file, acar_build.cmd, that customizes Adams/Car. It changes the
title at the top of the Adams/Car window and reads in menu and dialog box command files that customize
the Adams/Car interface. If this file is located in the start-up directory used by your template-based
product, then your template-based product will read and execute it automatically. Although this file can
be used to configure the product at startup, we recommend that you save either a site or private binary,
as they are more efficient at startup.
You can customize the other template-based products in a similar way, using the appropriate build
command files listed in table File Names. In this example, we assume that the environment variable
MDI_ACAR_SITE is set.
! Adams/Car
! Copyright (C) 1995-2005 MSC.Software
! All Rights Reserved. !
!****************************************************
!---- Modify the window title ----
397
398 Adams/Car
interface window modify &

window_name=.gui.main &
title="Adams/Car: Company XYZ" &
icon_label="A/XYZ"
!---- Set-up libraries and variables ---file command read
file_name=(getenv("MDI_ACAR_SITE")//"/build_gui/libraries.cmd")
!---- Interface Menus ---file command read
file_name=(getenv("MDI_ACAR_SITE")//"/interface/menus_int.cmd")
!----Dialog Boxes ---file command read
file_name=(getenv("MDI_ACAR_SITE")//"/dboxes/dbox_ana_1.cmd")
file command read
file_name=(getenv("MDI_ACAR_SITE")//"/dboxes/dbox_ana_2.cmd")
If you decide to build either a site or private binary file, then you must place this file at the top level, as
defined by the path in MDI_ACAR_SITE or MDI_ACAR_PRIVATE.
Saving Interface Changes

All the changes that you make to the interface are active as long as you stay in your current session. This
includes changes to interface objects and macros. You can save the changes for yourself in your private
directory or you can make the changes so that all users can access them from the site directory.
There are many ways to save the changes. The most efficient is to create a private or a site binary that
contains the changes. You can then instruct your template-based product to read the changes when it
starts up. The following procedure summarizes the steps you would perform to save the changes in a
binary. For more information, see the references noted in each step. In addition, for an overall description
of creating binaries for your template-based product, see Running and Configuring Adams.
To save changes as a binary:
1. Export the new or modified macro as a command file:
From the Tools menu, point to Macro, and then select Write.
In the Macro Name text box, enter the name of a macro you have created or modified.
Note that it's not mandatory to provide a file name for the macro. If you name the macro
.MY_LIBRARY.macros.mac_ana_ful_tst_sub, then Adams/Car saves it as

mac_ana_ful_tst_sub.cmd, automatically adding the .cmd extension.
2. Export the new or modified dialog box, as a command file:

From the Tools menu, point to Dialog Box , and then select Modify, to open the Database
Navigator.
Select the dialog box you want to export.
Adams/Car displays the dialog box in build mode, along with the Dialog Box Builder.
From the Dialog Box Builder's Dialog Box menu, point to Export, and then select Command
File.
Adams/Car writes a command file to your file system. The name of the resulting command
file will be derived from the dialog box name. If the dialog box is named
dbox_ana_ful_tst_sub, then the dialog box will be saved as dbox_ana_ful_tst_sub.cmd.
3. Create a command file, named as shown in tableFile Names, that reads in thecommand files that
customize the interface. See an example of an acar_build.cmd file.
4. Add commands to that command file that automatically reads the macro and dialog box. The
following would read the macro and dialog box, as saved in the steps above.
!------Read a macro----macro read &
macro_name = .MY_LIBRARY.mac_ana_ful_tst_sub &
file_name = "C:\temp\mac_ana_ful_tst_sub.cmd" &
user_entered = "Analysis full-vehicle test submit" &
wrap_in_undo = no &
create_panel = no
!------Read a dialog box----file command read &
file_name = "C:\temp\abox_ana_ful_tst_sub.cmd
5. Store the file in the desired private or site file repository. Learn about private and site file
repositories.
6. Create a private or a site-specific binary, including the saved interface objects, as explained in
Creating Binary Files in the guide Running and Configuring Adams
399
400 Adams/Car
Introducing Adams/View Libraries

Libraries let you use your user-written subroutines and compiled functions. User-written subroutines and
compiled functions let you tailor your template-based product to your needs and go beyond the functions
you can define using macros. For more on compiled functions, see Compiled Functions in the guide,
Using the Adams/View Function Builder.
You will find subroutines most helpful when the operations to be performed are heavily recursive or
require file input or output.
To use your custom subroutines and functions, you create an Adams/View library. An Adams/View
library extends the functionality of your template-based product during the design phase and during
plotting. Using an Adams/View library, you can create compiled functions in C and use them in an
Adams/View expression just as you would use standard, built-in Adams/View functions.
You register the user-written functions by calling a subroutine built into Adams/View. You must place
this subroutine call in the registration subroutine supplied in source-code form in Adams/View. To
automate tasks, you can write a custom Adams/View library in C. As an example, you might want to
create a wavefront file that given a number of macro parameters, such as road width, length, and color,
can be used to define a road graphic. In such an example, you would create a C file that when combined
with some macro-wrapping code can be set up to pass parameters from the macro to your custom C
routine. The following example shows five parameters (road_width, road_length, color, shell_file,
error_flag) being passed to a routine named create_a_road:
variable set variable_name = $_self.generate_road &
integer_value = (eval(create_a_road("$road_width", "road_length", "color",
"shell_file", "error_flag" )))
If successful, this execution results in the generation of a wavefront file based on the input parameter
contained in shell_file (as an example, my_road.obj).
In this case, you call a function (create_a_road) in your Adams/View library. You can set up this code to
return a Boolean flag, such as 0 if it failed and 1 if it was successfully executed. You can check this flag
to see if the operation was successful or not, and take action based on the result.
After you check the error flag, you can execute a read Wavefront file in the macro, specifying the
shell_file file as generated by the Adams/View library:
file wavefront read &
file_name = (eval($_self_shell_file)) &
port_name = $assembly_ground
Learn more about Adams/View libraries:

Requirements for Creating Custom Libraries
Creating and Using Adams/View Libraries

To be able to create Adams/View or Adams/Solver libraries, you must meet the following requirements:
To link Adams/Solver (run-time) routines, you must have a FORTRAN or C compiler.

To link Adams/View (design-time) routines, you must have a C compiler.
You can input C or FORTRAN source files to create Adams/Solver user libraries and only C source files
to create Adams/View user libraries. You must compile these subroutines before linking them with an
Adams product. See the hardware and software specifications that come with your Adams product for
the type of compiler you need
(http://www.mscsoftware.com/support/prod_support/adams/?Q=135&Z=144&Y=174). Also refer to your
compiler documentation for details.
Therefore, you can write an Adams/Solver routine in FORTRAN or C, but keep in mind that:
The solver subroutine is expected to be in FORTRAN.
If the solver subroutine is written in C, you must make it emulate a FORTRAN subroutine, as
specified in Knowledge Base Article 8384, at
http://support.adams.com/kb/faq.asp?ID=kb8384.dasp. If you write an Adams/Solver routine in
C, it requires a FORTRAN header, and also requires a FORTRAN compiler (linker).
You must have the linkers from the FORTRAN compilers to create a library, even if the
subroutine is in C.
Creating and Using Adams/View Libraries

An Adams/View library is a custom piece of C code that you can use to extend the functionality of the
interface. See a simple example to automatically create a Wavefront file based on a number of input
parameters from a macro.
Modifying vc_init_usr_c
You can find the file vc_init_usr.c in the distribution of Adams, under /aview/usersubs. This file provides
an interface between Adams/View and user-defined functions. For this example, you'll assume that a
user-defined function, named create_road, is going to be used. Following the instructions in
vc_init_usr.c, you would do the following:
1. Copy vc_init_usr.c and mdi_c.h to your local working directory.
2. Modify vc_init_usr.c to suit your function (create_road). The file includes help inside comment
blocks.
3. Create a C file containing the function create_road. Use the parameters that are passed to and
from the function.
4. Compile the two files using the appropriate compile flags (can be found by opening an advanced
session):
On Windows:
From the Start button, point to Programs, point to MSC.Software, point to MD Adams R3,
point to your template-based product (in this case, ACar), and then select Advanced.
At the prompt, enter cr-acarprivate, and then press Enter.
401
402 Adams/Car
Press Enter again to select the default, which tells the compiler not to build debug libraries.
Your template-based product displays the compile options.
On UNIX:
At the prompt, enter mdi -c acar cr-acarprivate, and then press Enter.
Your template-based product displays the compile options.
5. To end this session, type Exit, and then press Enter.

6. Once the files have been compiled, repeat this process, this time specifying the two object files
that were compiled. If everything is successful, you will now have a .dll file (.so on UNIX).
Using the Custom Adams/View Library
For the custom Adams/View library to be automatically loaded, see thenotes for organizing your custom
code. Once you've loaded the library into your template-based product, you should be able to reference
your custom function. You can reference your function using the Function Builder or macro code.
Introducing Adams/Solver Libraries

Custom Adams/Solver libraries let you use your user-written subroutines with Adams/Solver. Userwritten subroutines let you tailor your template-based product to your needs and go beyond the
functionality provided with Adams/Solver and the specific solver functionality delivered with your
product. For general information about subroutines, see:
Using Adams/Solver Subroutines
Running and Configuring Adams
For example, you want to create a force element that represents an aircraft landing-gear damper, then you
could create a custom Adams/Solver library to define the calculations used to produce that force. Inputs
to the damper might include damper velocity, damper displacement, and operating temperature. Output
could be force.
To use your custom Adams/Solver subroutine, you first compile your C or FORTRAN code. You then
link those files into an Adams/Solver library (*.dll or *.so (on UNIX)). The resulting file is stored in a
location defined by either MDI_ACAR_SITE or MDI_ACAR_PRIVATE_DIR. When you invoke the
site or private solver, the library is automatically loaded and the functions become available (dispatched
using the auto-generated code in dispatch.f). A statement in the solver dataset, for the aircraft damper
mentioned above, may look like this:
SFORCE/1
,TRANSLATIONAL
,I = 1
,J = 2
,FUNCTION = USER (2001, 1, 2, 3)
where:
2001 is the branch ID of your sfo subroutine (your function in your subroutine would be
sfo2001(par, npar)
1 is the ID of the variable measuring damper_velocity

2 is the ID of the variable measuring damper_displacement
3 is the ID of the variable measuring temperature
This function would provide the force to the damper element. Assuming that a subroutine named sfo2001
is included in your custom solver code, the general dispatcher will call this subroutine, pass information
to the subroutine, and return the force from the subroutine.
Learn more about Adams/Solver libraries:
Creating and Using Adams/Solver Libraries

To be able to create Adams/View or Adams/Solver libraries, you must meet the following requirements:
403
404 Adams/Car
To link Adams/Solver (run-time) routines, you must have a FORTRAN or C compiler.

To link Adams/View (design-time) routines, you must have a C compiler.
You can input C or FORTRAN source files to create Adams/Solver user libraries and only C source files
to create Adams/View user libraries. You must compile these subroutines before linking them with an
Adams product. See the hardware and software specifications that come with your Adams product for
the type of compiler you need
(http://www.mscsoftware.com/support/prod_support/adams/?Q=135&Z=144&Y=174). Also refer to your
compiler documentation for details.
Therefore, you can write an Adams/Solver routine in FORTRAN or C, but keep in mind that:
The solver subroutine is expected to be in FORTRAN.
If the solver subroutine is written in C, you must make it emulate a FORTRAN subroutine, as
specified in Knowledge Base Article 8384, at
http://support.adams.com/kb/faq.asp?ID=kb8384.dasp. If you write an Adams/Solver routine in

C, it requires a FORTRAN header, and also requires a FORTRAN compiler (linker).
You must have the linkers from the FORTRAN compilers to create a library, even if the
subroutine is in C.
Creating and Using Adams/Solver Libraries

Before writing user subroutines, make sure you understand the concepts presented in Introducing
Adams/Solver Libraries and Requirements for Creating Custom Libraries, and more importantly the
requirements for the Adams/Solver dataset and the naming conventions for the subroutines and files
containing subroutines. To review some of those concepts, assume that you have an Adams/Solver
statement similar to the following:
REQUEST/1, FUNCTION = USER(123, ..., ...)
Then, you would need to generate a file named REQ123.f, which would contain a subroutine named
req123. For example:
C Request subroutine to calculate Yaw angle
subroutine req123 (par, npar)
If you follow this convention, generating your own custom libraries should be easy.
To generate a custom library:
1. Make a list of files that you want to include in your custom Adams/Solver library.
2. Save this list in a text file named sub_list.lst. The following is an example list:
req123
sfo456
con789
3. Build your custom Adams/Solver Library:
On Windows:
From the Start button, point to Programs, point to MSC.Software, point to MD Adams R3,
point to your template-based product (for example, Adams/Car), and then select Advanced.
At the prompt, type cr-solverprivate, and then press Enter.

Type @sub_list.lst to provide the list of files you want to include in your custom
Adams/Solver library.
Press Enter.
On UNIX:
At the prompt, type mdi -c acar cr-solverprivate, and then press Enter.
Your template-based product displays the compiler options for the C and FORTRAN
compilers. Make a note of the options.
Type @sub_list.lst to provide the list of files you want to include in your custom
Adams/Solver library.
Press Enter.
4. Alternatively, from the command line you can create your custom library by typing the following
command:
mdi -c acar cr-solverpr n @sub_list.lst -n
405
406 Adams/Car
Note:
Adams/Car writes the resulting acarsolver.dll (the name of the file is dependent on
your template-based product) to the directory defined by the environment variable

MDI_ACAR_PRIVATE_DIR.
If you are having difficulty building your custom code, we recommend using a
DOS prompt and the command adamsmdr3 acar cr-solverprivate n @sub_list.lst.

This allows for output to be readable.
If you want to create a site solver library, you can replace the command cr-
solverprivate with cr-solversite. Your template-based product stores the generated

library in the directory defined by the environment variable MDI_ACAR_SITE.
Your compiled files and sub_list.lst are stored in a working directory. Your
template-based product does not necessarily start in that directory. If there is a

mismatch between the two directories, your template-based product is unable to
locate your files and will fail.To make the working directory default to the correct
location, do the following:
On Windows:
From the Start button, point to Programs, point to MSC.Software, point to
MD Adams R3, point to your template-based product (for example,

Adams/Car), and then right-click Advanced.
Select Properties.
In the Start in text box, enter the location of your files (for example, c:\temp).
On UNIX, move into the directory where sub_list.lst is located (for example, cd
/usr/home/my_home/work).
After you created the private Adams/Solver library, modify an existing Adams/Solver dataset to verify
that your custom functions are working. You might find it helpful to write basic 'write' statements in your
FORTRAN code to verify that the code is being executed.
Using the Dispatcher (GENDISP)

Adams/Car has a unique utility for dealing with FORTRAN user subroutines called the generalized
dispatcher or GENDISP. GENDISP automatically creates the necessary subroutines (REQSUB,
SFOSUB, and so on) with all the branches to your routines as part of the linking of a library. The
branching for each category of a subroutine (RESQUB, SFOSUB, and so on) are written into a single
FORTRAN file named dispatch.f. In the topics that fo
llow you will learn more about how this mechanism
works.
Learn why you'll find it valuable to create subroutines and functions and how to create libraries that
reference them:
Overview of GENDISP
Conventions for Using GENDISP
User-Written Subroutines that GENDISP Supports

Adding GENDISP Support For New Subroutine Types
Example of Using GENDISP
How GENDISP Works
Overview of GENDISP
When you write a standard REQSUB subroutine, you often need to process output in more than one way.
You might have one subroutine that computes toe, camber, and caster angle, and another that computes
lateral acceleration and body sideslip angle. In your dataset you may have the following requests, which
reference two user subroutines to calculate toe, camber, and caster, and in the second subroutine lateral
acceleration and body sideslip.
REQUEST/111
!toe, camber, caster
FUNCTION = USER(1, 1, 2, 3)
REQUEST/222
!lateral acceleration, body sideslip
FUNCTION = USER(2, 4, 5, 6)
The parameters of interest are USER(1, and USER(2, where the values 1 and 2 correspond to PAR(1) in
the expression that follows. In your REQSUB, you must have logic to branch to the different subroutines
as shown next:
IF (NINT( PAR(1)) .EQ. 1 ) THEN
CALL TCCREQ( ID, TIME, PAR, NPAR, IFLAG, RESULT )
ELSE IF (NINT( PAR(1)) .EQ. 2 ) THEN
CALL BSAREQ( ID, TIME, PAR, NPAR, IFLAG, RESULT )
.
.
.
In the above example, if PAR(1) is equal to 1 (as defined by REQUEST/111), then the subroutine
TCCREQ is called. Likewise, if PAR(1) is equal to 2 (as defined by REQUEST/222), then the subroutine
BSAREQ is called.
Each time you add a new subroutine, you must rewrite your REQSUB to call that subroutine. If your
company has a standard REQSUB, you have to create a local version for yourself and then add your
subroutines to it.
With the template-based products, however, if you follow a simple naming convention for your userwritten subroutines, GENDISP automatically creates a REQSUB, SFOSUB, and so on, with all the
branches to your routines as part of the linking of a library. GENDISP places these subroutines in an
automatically generated file, named dispatch.f.
For example, if you rename the subroutine TCCREQ to REQ001 and the subroutine BSAREQ to
REQ002, then GENDISP creates a REQSUB for you with branches to REQ001 and REQ002 as shown
next:
IF (NINT( PAR(1)) .EQ. 1 ) THEN
CALL REQ001( ID, TIME, PAR, NPAR, IFLAG, RESULT )
ELSEIF (NINT( PAR(1)) .EQ. 2 ) THEN
407
408 Adams/Car
CALL REQ002( ID, TIME, PAR, NPAR, IFLAG, RESULT )

.
.
.
Using GENDISP makes the generation of dispatcher routines a fully automated process, allowing you to
concentrate primarily on the content of your solver subroutines.
Conventions for Using GENDISP
To use GENDISP correctly, you must do the following:
Name your user subroutines using the convention that the first three characters must be the same
as the calling user subroutine and the last three characters of the subroutine name must be
numbers. For example, the subroutine called by a REQSUB, must be named REQ001, REQ002,
and so on. Another example would be naming GFORCE user subroutines called from a
GFOSUB names like GFO241, GFO534, and so on.
Name your source code or object code files according to this convention. For GENDISP to work,
the source code or object code files must have the same root name as the subroutine (for
example, req001.f or req001.o). Note that GENDISP ignores case. Therefore, REQ001.f is the
same as req001.f or ReQ001.f. GENDISP generates branches based on the root file name.
GENDISP does not examine the contents of a file for names matching the convention.
When invoking a user subroutine from your Adams model, make sure that the first user
parameter matches the subroutine you want to call. For example, the following sensor statement
generates a call to SEN743:
SENSOR/1, FUNC=USER(743, .......)\
Remember to always reserve the first parameter for branching when writing your user
subroutines.
Number all your routines in the 001 to 799 range (for example, REQ300 and SFO465). The
range 900+ is reserved for standard Adams user subroutines.
User-Written Subroutines that GENDISP Supports

GENDISP supports the following Adams/Solver user-written subroutines. Learn about subroutines.
Adams/Solver User-Written Subroutines that GENDISP Supports
Name:
CONSUB Cont
Description:
rol command
COUSUB
Coupler subroutine and partial derivatives
COUXX
Coupler first partial derivatives subroutine (CXX100)
COUXX2
Coupler second partial derivatives subroutine (CXD100)
CURSUB Curve
statement
Name:
DIFSUB D
DMPSUB Mod
FIESUB Field
GFOSUB Gforce
GSESUB
Description:
ifferential equation statement
al damping subroutine
statement
statement
General state equation subroutine
Adams/Car provides generic GSEYU, GSEXU, GSEXX and GSEYX
subroutines that numerically difference a GSE subroutine. The general
dispatcher, however, does not provide support for the revised GSE
implementation using the GSE_DERIV, GSE_UPDATE, GSE_OUTPUT,
and GSE_SAMP subroutines.
MFORCE Modal
force subroutine
MOTSUB Motion
statement
REQSUB Reques
t statement
SENSUB Sensor
statement
SFOSUB Sforce
statement
TIRSUB
Tire statement subroutine (to be discontinued)
UCOSUB Uco
VARSUB V
VFOSUB Vforce
VTOSUB Vtorque
n (user constraint) statement

ariable statement
statement
statement
GENDISP supports the following Adams/Car user-written subroutine types:

Adams/Car Subroutine Types That GENDISP Supports
Name:
BRASUB Brake
STRSUB S
THRSUB Th
Description:
demand
teering demand
rottle demand
Adams/Tire now supports dynamic loading (dispatching) of tire (TYRSUB) and road contact
(ARCSUB) subroutines. Support for standard driver interface (SDISUB) for lack of usage.
409
410 Adams/Car
Adding GENDISP Support For New Subroutine Types

To add support for a new subroutine type, you modify the file dispatch.dat to add the new type. You can
find a copy of dispatch.dat in the directory install_dir/product_name/dispatch.dat, where install_dir is the
directory in which you installed yourtemplate-based product and product_name is acar, aengine, aircraft,
or arail, according to the product you are using.
The file, dispatch.dat, is a TeimOrbit format file containing a block for each supported subroutine type
and follows these rules:
Block names are limited to three characters. For example, [MYU] is valid, but [MYUT] is not.
Branching is always based on PAR(1) in the generated source code. So PAR must either be an
array passed to the user subroutine as in REQSUB or PAR must be created using the
(CODE_BEFORE_BRANCH) option as Example of Using GENDISP.
Code in the (CODE_BEFORE_BRANCH) sub-block is output literally to the generated source
code, and must follow FORTRAN's strict formatting rules. For example, executable code on a
line must be indented six spaces.
For example, the block for REQSUBs looks like:

$********************************************
[REQ]
(PARAMETERS)
{type name}
'INTEGER' 'ID'
'DOUBLE PRECISION' 'TIME'
'DOUBLE PRECISION' 'PAR(*)'
'INTEGER' 'NPAR'
'LOGICAL' 'IFLAG'
'DOUBLE PRECISION' 'RESULT(8)'
$********************************************
With this block in dispatch.dat and given a list of files names
containing req900, req901, and req221, GENDISP would create the
following source code in the file dispatch.f:
Cccccccccccccccccccccccccccccccccccccccccccccccccccc
subroutine reqsub( ID,
& TIME,
& PAR,
& NPAR,
& IFLAG,
& RESULT )
C This is a dispatcher routine written by gendisp
INTEGER ID
DOUBLE PRECISION TIME
DOUBLE PRECISION PAR(*)
INTEGER NPAR
LOGICAL IFLAG
DOUBLE PRECISION RESULT(8)
C Local variables
character*(80) errmsg
IF ( NINT(PAR(1)).EQ.900 ) THEN
CALL req900 ( ID,
& TIME,
& PAR,
& NPAR,
& IFLAG,
& RESULT )
ELSE IF ( NINT(PAR(1)).EQ.901 ) THEN
CALL req901 ( ID,
& TIME,
& PAR,
& NPAR,
& IFLAG,
& RESULT )
CALL req221 ( ID,
& TIME,
& PAR,
& NPAR,
& IFLAG,
& RESULT )
ELSE
WRITE (ERRMSG,'(A,I4.4)')
& 'Error in dispatcher subroutine reqSUB: Invalid
PAR(1): ',
& NINT( PAR(1) )
CALL ERRMES( .TRUE., ERRMSG, 0, 'STOP')
ENDIF
RETURN
END
Each block for a subroutine in dispatch.dat must contain a (PARAMETERS) sub-block that defines the
subroutine parameter types. Optionally, a block may contain a (CODE_BEFORE_BRANCH) sub-block
as illustrated in the example MYUSUB shown in Example of Using GENDISP.
Using GENDISP
The following procedure is only applicable if you want to extend the libraries that GENDISP dispatches.
Here we provide an overview of how to test additions to the dispatch.dat file. The result of this procedure
should be a fully populated dispatch.f file, which you can examine to verify that valid subroutines have
been written. In normal circumstances, this procedure should not required because this process is
automated by the acarcom and acarsolvercom scripts. We provide this procedure as a means to validate
that you correctly modified the dispatch.dat file.
GENDISP is invoked when linking private or site libraries. A list of standard template-based product file
names, plus file names you supply, are passed to GENDISP. GENDISP examines the list of files for
names matching the supported subroutine types given in the file dispatch.dat. For each matching name,
GENDISP creates a branch in the appropriate user subroutine and outputs the source code file dispatch.f
to the working directory.
The file dispatch.f can contain multiple subroutines, but only one of each type (for example, one
REQSUB or one CURSUB). The acarcom and acarsolvercom scripts include dispatch.f when linking.
The files dispatch.f and dispatch.o are left in the working directory so you can look at them.
411
412 Adams/Car
For testing or other purposes, you can execute GENDISP yourself. You can find GENDISP at the
following location, where install_dir is the installation directory, and product_name is the name of your
template-based product:
$install_dir/$product_name/$MDI_CPU/gendisp
For example, the location of GENDISP might be:
/usr/mdi12/acar/irix32/gendisp
You invoke GENDISP with the following arguments:
gendisp file.lst dispatch.f dispatch.dat
where:
file.lst - File containing a list of user subroutine filenames for GENDISP processing.
dispatch.f - Source code file name output by GENDISP.
dispatch.dat - TeimOrbit format file defining the supported subroutine types and their parameter
lists.
Example of Using GENDISP

The following example uses GENDISP to generate a MYUSUB that branches to subroutines named
myu532, myu253, and so on. It also branches to these subroutines based on an integer argument named
SWITCH.
SUBROUTINE MYUSUB( SWITCH, NDPAR,
DPAR, VECTOR )
C
C GLOBAL VARIABLES
C
INTEGER SWITCH
INTEGER NDPAR
DOUBLE PRECISION DPAR(NDPAR)
DOUBLE PRECISION VECTOR(3)
C
C LOCAL VARIABLES
C
CHARACTER*(80) ERRMSG
INTEGER PAR(2)
C
PAR(1) = SWITCH
CALL MYU532 ( SWITCH, NDPAR, DPAR, VECTOR
)
CALL MYU253 ( SWITCH, NDPAR, DPAR, VECTOR
)
ELSE
& 'ERROR in dispatcher subroutine MYSSUB: invalid
& NINT( PAR(1) )
CALL ERRMES( .TRUE., ERRMSG, 0, 'STOP')
ENDIF
RETURN
switch:',
END
To dispatch.dat, you add a block for MYSSUB that looks like the following:
$********************************************
[MYU]
(PARAMETERS)
{type name}
'INTEGER' 'SWITCH'
'INTEGER' 'NDPAR'
'DOUBLE PRECISION' 'DPAR(NDPAR)'
'DOUBLE PRECISION' 'VECTOR(3)'
(CODE_BEFORE_BRANCH)
{code}
' INTEGER PAR(2)'
' PAR(1) = SWITCH'
$********************************************
The code GENDISP generates for MYUSUB looks a little different then the example above, but
functions in the same way:
Ccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc
subroutine myusub( SWITCH,
& NDPAR,
& DPAR
,
& VECTOR )
C This is a dispatcher routine written by gendisp
INTEGER SWITCH
INTEGER NDPAR
DOUBLE PRECISION DPAR(NDPAR)
DOUBLE PRECISION VECTOR(3)
C Local variables
character*(80) errmsg
INTEGER PAR(2)
PAR(1) = SWITCH
CALL myu532 ( SWITCH,
& NDPAR,
& DPAR,
& VECTOR )
CALL myu253 ( SWITCH,
& NDPAR,
& DPAR,
& VECTOR )
ELSE
& 'Error in dispatcher subroutine myuSUB: Invalid
PAR(1): ',
& NINT( PAR(1) )
CALL ERRMES( .TRUE., ERRMSG, 0, 'STOP'
)
ENDIF
RETURN
END
413
414 Adams/Car
Utility Functions
This topic lists utility functions that help you extend the Adams/View macro language. The functions
help you access information that is not easy to access using the standard Adams/View macro language.
You can use the utility functions in macros and in dialog boxes.
The following functions are used by the template-based products. To see information on all functions
available in the Function Builder, see the Function Builder online help.
Units-Conversion Functions
String Functions
Database Functions
File Functions
Database Lookup Functions
Miscellaneous Functions
Units-Conversion Functions
The units-conversion functions convert an input value to a different unit system. The units-conversion
functions are:
convert_from_units
convert_units
convert_to_radians
units_to_mks
convert_from_units
Definition
convert_from_units converts the input value from aunit type to the equivalent modeling units. It accepts
any valid units string (for example, mm, newton, or inch) for the unit type. It returns the converted value.
Format
REAL convert_from_units (STRING from_units, REAL in_value)
Arguments
from_units
A string specifying the current units of the argument in_value.
in_value
A real number to be converted.
Examples
The following example converts the current length units, which are in inches (inch), to millimeters (mm):
variable set variable=units_convert &
real_value=(eval(CONVERT_FROM_UNITS("inch", 1.0)))
units_convert = 25.4
convert_units
Definition
convert_units returns the conversion factor necessary to convert a value from the current units
(from_units) to the desired units (to_units). It accepts any valid units string (for example, mm, newton,
or inch) for the units strings. The units should be equivalent modeling units of length, force, mass, time,
or angle.
Format
REAL convert_units (STRING from_units, REAL to_units)
Arguments
from_units
A string specifying the current units.
to_units
A string specifying the desired units.
Examples
The following example returns the conversion factor necessary to convert miles to millimeters:
variable set variable=convert_factor &
real_value=(CONVERT_UNITS( "mile" , "mm" ))
convert_factor = 1.609344E+06
convert_to_radians
Definition
convert_to_radians converts an angle from degrees to radians. You specify the input value in current
modeling angular units.Format
REAL convert_to_radians (REAL in_value)
Arguments
in_value
A real number to be converted.
415
416 Adams/Car
Examples
The following example converts the current modeling angular units, which are in degrees, to radians:
variable set variable=angle_radians &
real_value=(CONVERT_TO_RADIANS(90))
angle_radians = 1.5707963268
units_to_mks
Definition
units_to_mks returns the conversion factor from user units to database units (meters, kilograms, seconds,
radians, or mks).Format
REAL units_to_mks (INTEGER units)
Arguments
units
An integer value.
Examples
The following example returns the conversion factor necessary to change degrees to database units:
variable ser variable=myvar1 &
real_value=90.0 units=angle
variable set variable=myvar2 &
real_value=(UNITS_TO_MKS( myvar1.units ))
myvar2 = 1.7453...E-02
String Functions
The string functions allow you to manipulate character strings. The string functions are:
str_assembly_class
str_char_swap
str_filename
str_model_class
str_prefix
str_remove
str_replace
str_typecheck
str_assembly_class
Definition
str_assembly_class returns the assembly class of an assembled model. Your template-based product
stores the returned information in the assembly_class variable under all assemblies. For Adams/Car,
typical assembly classes include suspension and full_vehicle. You can also extend the assembly classes.
If no assembly variable exists within the assembled model, str_assembly_class returns an empty string.
Format
STRING str_assembly_class (OBJECT assembled_model)
Arguments
assembled_model Name of the assembled model.
Examples
variable set variable=current_class &
string_value=(STR_ASSEMBLY_CLASS(.susp_assy))
current_class = "suspension"
str_char_swap
Definition
str_char_swap changes a single character in a string (object_name) at a particular location (index) to
another character string. It changes the characters as specified in swap_str.
str_char_swap compares the strings and changes them only in the string following the last . in
object_name. In addition, swap_str must be two or more characters long and contain an even number of
characters.
The first half of swap_str determines the characters to be changed ("from characters") and the second
half of swap_str determines the characters to which the characters are to be changed ("to characters"). If
str_char_swap does not change any characters, it returns the original object_name string.
Format
STRING str_char_swap (STRING object_name, STRING swap_str, INT index)
417
418 Adams/Car
Arguments
object_name
A string that usually contains an object's name.
swap_str
A string that describes the rules for character changing.
index
An integer that specifies the index of the character to be changed.
Examples
In the following Adams/Car example, lrrl is the string that defines what should be changed. The first half
of the string (lr) represents the valid "from characters." The second half of the string (rl) represents the
"to characters."
If the example finds one of the "from characters" at position 3 in the string
._front_susp.ground.hpl_lca_front, it replaces the "from characters" with the corresponding "to
characters." In this example, l would change to r.
variable set variable=symmetric_name &
string_value=(STR_CHAR_SWAP("._front_susp.ground.hpl_lca_front",
"lrrl", 3))
symmetric_name = "._front_susp.ground.hpr_lca_front"
str_filename
Definition
str_filename strips an input string (in_str) to a base file name (with extension) and then substitutes a new
string (new_str) for the old string (old_str) if the old string exists in the base name. If old_str occurs more
than once in the input string, str_filename only replaces the last occurrence.
Format
STRING str_filename (STRING in_str, STRING old_str, INT new_str)
Arguments
in_str
The input string, which is usually a file path.
old_str
The string to be replaced.
new_str
The string to replace old_str.
Examples
variable set variable=base_filename &
string_value=(STR_FILENAME("/usr/car.cdb/test.tpl", "tpl","sub"))
base_filename = "test.sub"
str_model_class
Definition
str_model_class returns a model's model class. This information is stored in the model_class variable
under all models. If no such variable exists within the model, str_model_class returns an empty string.
Typical model classes include template, subsystem, and assembly.
Format
STRING str_model_class (OBJECT model)
Arguments
model
A model entity.
Examples
variable set variable=current_class &
string_value=(STR_MODEL_CLASS(._front_susp))
current_class = "template"
str_prefix
Definition
str_prefix returns the generic prefix for a given string (object_name). The length of the return string is
always four characters long. str_prefix also pares the input down to only the string following the last . in
object_name.
Format
STRING str_prefix (STRING object_name)
Arguments
object_name
Examples
variable set variable=name_prefix &
string_value=(STR_PREFIX("._front_susp.ground.hpl_lca_outer"))
name_prefix = "hps_"
419
420 Adams/Car
str_remove
Definition
str_remove trims an input string (in_str) by removing a string (begin_str) from the beginning of in_str
and a string (end_str) from the end of in_str.
str_remove removes begin_str before removing end_str so if the beginning and ending string in in_str
overlap, str_remove only removes begin_str.
Format
STRING str_remove (STRING in_str, STRING begin_str, STRING end_str)
Arguments
in_str
The input string.
begin_str
A string to be removed from the beginning of in_str.
end_str
A string that defines where to truncate the input string.
Examples
variable set variable=trim_string &
string_value=(STR_REMOVE("abcdef", "ab", "ef"))
trim_string = "cd"
variable set variable=trim_string &
string_value=(STR_REMOVE("abcdef", "", "ef"))
trim_string="abcd"
str_replace
Definition
str_replace replaces a string (old_str) with a new string (new_str) in the string in_str. If there are multiple
occurrences of old_str, str_replace replaces the last occurrence.
Format
STRING str_replace (STRING in_str, STRING old_str, STRING new_str)
Arguments
in_str
The input string.
old_str
The string to be replaced.
new_str
The string to replace old_str.
Examples
variable set variable=other_filename &
string_value=(STR_REPLACE("/usr/car.cdb/test.tpl", "test",
"junk"))
other_filename = "/usr/car.cdb/junk.tpl"
str_typecheck
Definition
str_typecheck returns a 1 if a list of characters (type) matches the third character in the base name of an
object's name (object_name). str_typecheck always pares down the input to only the string following the
last . in object_name.
You can specify more than one character in type.
Format
STRING str_typecheck (STRING object_name, STRING type)
Arguments
object_name
type
A list of characters to match. Allowed characters are l, r, and s.
Examples
variable set variable=check_type &
string_value=(STR_TYPECHECK("._front_susp.ground.hpl_lca_outer",
"ls"))
check_type = 1
variable set variable=check_type &
string_value=(STR_TYPECHECK("._front_susp.ground.hpl_lca_outer",
"r"))
check_type = 0
Database Functions
The database functions let you manage and access the databases of your template-based product. The
database functions are:
cdb_alias2path
cdb_path2alias
cdb_input2base
cdb_input2ext
cdb_input2file
421
422 Adams/Car
cdb_input2path
cdb_input2full
cdb_search_file
cdb_runtime_path_port
cdb_alias2path
Definition
cdb_alias2path returns the full path associated with a given table path alias or cdb_name. If
cdb_alias2path does not find the full table path corresponding to the alias, it returns the input string. By
returning the input string, you can input normal path names and filenames, and cdb_alias2path returns
them without modification.
Format
STRING cdb_alias2path (STRING path_alias)
Arguments
path_alias
Alias used for internal reference to database.
Examples
This example finds the file system path associated with database prototype:
variable set variable=a2p &
string_value=(eval(cdb_alias2path("prototype")))
a2p = "/local/proto.cdb"
cdb_path2alias
Definition
cdb_path2alias returns the path alias associated with a given table path alias or cdb_name. If
cdb_path2alias does not find a path alias corresponding to the full path name, it returns the input string.
By returning the input string, cdb_path2alias allows you to enter normal path names and filenames, and
returns them without modification.
Note:
When comparing strings, UNIX is case sensitive. Windows is not.
Format
STRING cdb_path2alias (STRING path)
Arguments
path
File system path of the database.
Examples
This example finds the database alias associated with database:
variable set variable=p2a &
string_value=(eval(cdb_path2alias("/local/proto.cdb")))
p2a = "prototype"
cdb_input2base
Definition
cdb_input2base returns the base name of a file (input_name). It strips the input_name of both its file
system path prefixes and extension or suffix, if any.
Format
STRING cdb_input2base (STRING input_name)
Arguments
input_name
File system path to be converted to base name.
Examples
This example finds the base name for the file /local/proto.cdb/bushings.tbl/my_bush.bus:
variable set variable=i2b &
string_value(eval(cdb_input2base("/local/proto.cdb/bushings.tbl/m
y_bush.bus")))
i2b = "my_bush"
cdb_input2ext
Definition
cdb_input2ext returns the extension or suffix of a file (input_name). It returns an empty string if it finds
no extension
Format
STRING cdb_input2ext (STRING input_name)
423
424 Adams/Car
Arguments
input_name
File system path to be converted to extension.
Examples
This example finds the extension for the file /local/proto.cdb/bushings.tbl/my_bush.bus:
variable set variable=i2e &
string_value=(eval(cdb_input2ext("/local/proto.cdb/bushings.tbl/my
_bush.bus")))
i2e = "bus"
cdb_input2file
Definition
cdb_input2file returns the filename contained in input_name. cdb_input2file strips input_name of any
file system path prefix and returns the result.
Format
STRING cdb_input2file (STRING input_name)
Arguments
input_name
File system path to be converted to filename.
Examples
This example finds the filename for the file /local/proto.cdb/bushings.tbl/my_bush.bus:
variable set variable=i2file &
string_value=(eval(cdb_input2file("/local/proto.cdb/bushings.tbl/my_bush
.bus")))
i2file = "my_bush.bus"
cdb_input2path
Definition
cdb_input2path returns the file system path prefix of a filename. If the path prefix is not present,
cdb_input2path returns an empty string.
Format
STRING cdb_input2path (STRING input_name)
Arguments
input_name Filename to be converted into file system path prefix.
Examples
This example finds the file system path prefix for the file /local/proto.cdb/bushings.tbl/my_bush.bus:
variable set variable=i2p &
string_value=(eval(cdb_input2path("/local/proto.cdb/bushings.tbl/my_bush
.bus")))
i2p = "/local/proto.cdb/bushings.tbl"
cdb_input2full
Definition
cdb_input2full returns the file system path of a filename containing a database alias. If cdb_input2full
finds no database alias present, it returns the input string.
Format
STRING cdb_input2full (STRING input_name)
Arguments
input_name
Filename with database alias to be converted to file system path.
Examples
This example finds the file system path for the file mdids://prototype/bushings.tbl/my_bush.bus:
variable set variable=i2full &
string_value=(eval(cdb_input2full("mdids://prototype/bushings.tbl/
my_bush.bus")))
i2full = "/local/proto.cdb/bushings.tbl/my_bush.bus"
cdb_search_file
Definition
cdb_search_file returns the file system path of the input file (filename). First, it checks to determine if
the filename as input corresponds to an existing file. It expands any database alias to its corresponding
file system path, and looks for the filename at the resultant location. If it finds no file, it removes any file
system path prefix from the filename, and begins its to search the different databases in the specified
search order.
Remember that search order may be important. If two identically named files exist in different databases,
the search order determines which of these files cdb_search_file finds and returns.
425
426 Adams/Car
cdb_search_file returns an empty string if it does not find the requested filename after searching the
databases.
Format
STRING cdb_search_file (STRING class_name, STRING filename, INT level)
Arguments
class_name
The type class name for the table in which to search for the file. It is defined in the
configuration files.
filename
The filename, either with or without any path prefix, to be found.
level
The level in the search list at which to start searching. The value is usually 1, which
indicates a full search.
Examples
This example finds the file system path for file my_bush.bus:
variable set variable=sfile &
string_value=(eval(cdb_search_file("bushing","my_bush.bus",1)))
sfile="/local/proto.cdb/bushings.tbl/my_bush.bus"
cdb_runtime_path_port
Definition
cdb_runtime_path_port returns the filename of the input string (input_name) converted to the appropriate
operating system format. You will find cdb_runtime_path_port useful when you are sharing filenames
between UNIX and Windows file systems. It also lets you use a database alias instead of a full file system
path.
Format
STRING cdb_runtime_path_port (STRING input_name)
Arguments
input_name
File system path to be converted to an operating-system specific filename.
Examples
This example returns the Windows version of the filename for the file
mdids://prototype/bushings.tbl/my_bush.bus:
variable set variable=rpp &
string_value=(eval(cdb_runtime_path_port(mdids://prototype/bushings.tbl/
my_bush.bus)))
rpp = "mdids://prototype\bushings.tb\my_bush.bus"
File Functions
The file functions return information about the major and minor roles of templates and subsystems:
template_hdr_major_role
subsystem_hdr_major_role
subsystem_hdr_minor_role
template_hdr_major_role
Definition
template_hdr_major_role returns the major role of a template. Your template-based product stores the
major role information in the header information of all template files (.tpl). template_hdr_major_role
automatically opens a template file, retrieves the information from the file header, and closes the file.
Format
STRING template_hdr_major_role (STRING filename)
Arguments
filename
String that contains the full path of the template file.
Examples
This is an example of the header information that is stored in an Adams/Car template file:
$------------------------TEMPLATE_HEADER----------------------$
[TEMPLATE_HEADER]
MAJOR_ROLE = 'suspension'
TIMESTAMP ='1999/02/04,13:13:38'
HEADER_SIZE = 5
The following example returns the major role of a template, which it obtains from the header information
shown above:
variable set variable=tpl_major_role &
string_value=(TEMPLATE_HDR_MAJOR_ROLE
("mdids://shared/template.tbl/_dbl_wish.tpl"))
tpl_major_role = "suspension"
427
428 Adams/Car
subsystem_hdr_major_role
Definition
subsystem_hdr_major_role returns the major role of a subsystem. Your template-based product stores the
major role information in the headerinformation of all subsystem files (.sub). subsystem_hdr_major_role
automatically opens a subsystem file, retrieves the information from the file header, and closes the file.
Format
STRING subsystem_hdr_major_role (STRING filename)
Arguments
filename
String that contains the full path of the subsystem file.
Examples
This is an example of the header information that is stored in an Adams/Car subsystem file:
$--------------------------SUBSYSTEM_HEADER -----------------------$
[SUBSYSTEM_HEADER]
TEMPLATE_NAME = mdids://shared/templates.tbl/_double_wishbone.tpl
MAJOR_ROLE = suspension
MINOR_ROLE = front
TIMESTAMP = 1999/02/04,17:18:18
The following example returns the major role of an Adams/Car subsystem, which it obtains from the
header information shown above:
variable set variable=sub_major_role &
string_value=(SUBSYSTEM_HDR_MAJOR_ROLE("mdids://shared/subsystem.tbl/
front_susp.sub"))
sub_major_role = "suspension"
subsystem_hdr_minor_role
Definition
subsystem_hdr_minor_role returns the minor role of asubsystem. Your template-based product stores the
minor role information in the header information of all subsystem files (.sub).
subsystem_hdr_minor_role automatically opens a subsystem file, retrieves the information from the file
header, and closes the file.
Format
STRING subsystem_hdr_minor_role (STRING filename)
Arguments
filename
String that contains the full path of the subsystem file.
Examples
This is an example of the header information that is stored in an Adams/Car subsystem file:
$------------------------SUBSYSTEM_HEADER ----------------------$
[SUBSYSTEM_HEADER]
TEMPLATE_NAME = mdids://shared/templates.tbl/_double_wishbone.tpl
MAJOR_ROLE= suspension
MINOR_ROLE= front
TIMESTAMP= 1999/02/04,17:18:18
The following example returns the minor role of an Adams/Car subsystem, which it obtains from the
header information shown above:
variable set variable=sub_minor_role &
string_value=(SUBSYSTEM_HDR_MINOR_ROLE("mdids://shared/subsystem
.tbl/front_susp.sub"))
sub_minor_role = "front"
Database Lookup Functions

The database lookup functions find specified models or subsystems based on their classesor roles during
a session.
model_class_exists
subsystem_lookup
subsystem_role_exists
model_class_exists
Definition
model_class_exists lets you easily determine if a model of a particular model class exists in the current
session. model_class returns a 1 if a model of the specified model class exists.
Your template-based product stores the model class information in the model_class variable under all
models. Typical model classes include template, subsystem, and assembly.
Format
INT model_class_exists (STRING model_class)
429
430 Adams/Car
Arguments
model_class
String containing the model class.
Examples
if condition=(model_class_exists("assembly") == 0)
! No Assemblies !
end
subsystem_lookup
Definition
subsystem_lookup returns the subsystem contained in the assembled model with the specified major and
minor role. If no such subsystem exists, subsystem_lookup returns no object or NONE.
Format
OBJECT subsystem_lookup (OBJECT model, STRING major_role, STRING minor_role)
Arguments
model
Name of the assembled model.
major_role
String containing the major role to look up.
minor_role
String containing the minor role to look up.
Examples
variable set variable=front_susp_subsystem &
object_value=(eval(SUBSYSTEM_LOOKUP(.susp_assy, "suspension",
"front")))
front_susp_subsystem = .susp_assy.TR_Front_Suspension
subsystem_role_exists
Definition
subsystem_role_exists lets you easily determine if a subsystem of a particular role exists in an assembled
model. subsystem_role_exists returns a 1 if the assembled model contains such a subsystem. Your
template-based product stores the role information in the role variable that exists in each subsystem.
Format
INT subsystem_role_exists (OBJECT model, STRING role)
Arguments
model
role
String containing the role to look up.
Examples
if condition=(subsystem_role_exists(.fveh_assembly, "brake_system")
== 0)
! No Brakes !
end
Miscellaneous Functions
This topic lists utility functions that help you extend the Adams/View macro language. The functions
help you access information that is not easy to access using the standard Adams/View macro language.
You can use the utility functions in macros and in dialog boxes.
ac_info_mass
ac_info_mass
Definition
ac_info_mass computes the aggregate mass of the assembly.
Format
ac_info_mass(OBJECT model)
Arguments
model
Examples
variable set variable_name=total_mass &
real_value=(EVAL(ac_info_mass(.model_name)))
Organizing Custom Code

You can set up private and site repositories for storing:
Binaries that contain interface changes and macros
Libraries that contain linked subroutines and compiled functions
431
432 Adams/Car
For example, when a group of users needs to access the same information or are working on the same
project, you can create a custom site repository. By having a site repository, they can share site-specific
versions of the template-based product and configuration files.
Also, a private repository is a convenient way for a single user to create several custom versions of a
template-based product or to work on different projects. Private locations let you create an unlimited
number of site binaries and libraries.
In the site or private repository, your template-based product creates a directory structure that mimics the
installation directory structure. The directory contains subdirectories for each platform for which you
created a binary or a library.
You control the location of the private repository using the privateDir setting. The privateDir setting tells
Adams where to locate the appropriate files and where to store the resulting files. The default location of
the private repository is as follows:
Default Location of Private Repository
Product name:
File name:
Adams/Car $HOME/acar_private
Where $HOME represents your user home directory when you log on to your computer.
Note:
The following procedures show how you can define the site and private repositories for
Adams/Car. Follow the same basic procedures to define the site repository for your
Defining Site Repositories

To define the site repository in UNIX:
In Adams Toolbar, change the siteDir setting in the Adams/Car preferences. For example,
change it to:
/usr/people/someone/acar_site
You can also change the siteDir setting using the Registry Shell Tool from the command line.
For example, at the command line enter:
mdi -c rtool
set /MDI/ACar/Preferences/siteDir /usr/people/someone/acar_site
To define the site repository in Windows:
1. From the Start menu, point to Programs, point to MSC.Software, point to MD Adams R3, and
then select Adams - Settings.
2. Double-click the name of your product (ACar).
3. Select Preferences.
4. To the right of siteDir, in the Value column, enter (or right-click to browse for) a directory path,
such as d:\acar_custom.
5. Select Apply or OK.
Defining Private Repositories
To define the private repository in UNIX:
In Adams Toolbar, change the privateDir setting in the Adams/Car preferences. For example,
change it to:
/usr/people/someone/new_private
You can also change the privateDir setting using the Registry Shell Tool from the command
line. For example, at the command line enter:

mdi -c rtool
set /MDI/ACar/Preferences/privateDir /usr/people/someone/new_private
To define the private repository in Windows:

1. From the Start menu, point to Programs, point to MSC.Software, point to MD Adams R3, and
then select Adams - Settings.
2. Double-click the name of your product (ACar).
3. Select Preferences.
4. To the right of siteDir, in the Value column, enter (or right-click to browse for) a directory path,
such as d:\acar_custom.
5. Select Apply or OK.
For more information on the directories, creating the binaries and libraries, and the Adams Toolbar, see
Running and Configuring Adams.
433
434 Adams/Car
Example Four-Post Analysis

Although this is an Adams/Car example, you can use the general concepts presented here to create a
macro for 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:\MSC.Software\Adams\MDR2\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:\MSC.Software\Adams\MDR2\acar\examples\fourpost\customization_example.
On UNIX, it might look like:
/usr/MSC.Software/MDR2acar/examples/fourpost/customization_example.
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 MSC.Software, point to
MD Adams R3, and then select Adams - Command. In the command window, type acar;
cr-sitebin
On UNIX: Type adamsmdr3; 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.
The following tire models support the four-post rig test:
PAC2002, in transient mode, USE_MODE >10
PAC-TIME, in transient mode, USE_MODE >10
PAC-MC, in transient mode, USE_MODE >10
UA-Tire, in transient mode, USE_MODE = 2
Ftire
Note:
By default, the PAC2002 tire model is not used in the assembly packed in the examples
directory. The simulation will not succeed if the default Pacejka '89 tire is used.
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.
435
436 Adams/Car
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 four_post_rig.tpl 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 isparameterized 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.
We recommend that you add the database to your configuration file. Otherwise, when you submit
an analysis, the solver does not know about this new database search path, and consequently will
not read the appropriate tire files.
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.
Note:
You must change the tires from Pacejka '89 model to one of the following tire models:
PAC2002, in transient mode, USE_MODE >10
PAC-TIME, in transient mode, USE_MODE >10
PAC-MC, in transient mode, USE_MODE >10
UA-Tire, in transient mode, USE_MODE = 2
Ftire
You can find these tires in the supplied database shipped in the examples directory. Failure to switch
these tires will result in a solver failure while trying to run an analysis.
437
438 Adams/Car
Because we have not provided a custom dialog box or interface to submit one of the tests outlined above,
you must use the autogenerated dialog box associated with the Command Navigator:
1. To open the Command Navigator, from the Tools menu, select cp10 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 excerptsare
contained in this topic, we also included the appropriate files in the examples directory
(install_dir\acar\examples\fourpost\customization_example\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
439
440 Adams/Car
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 youcreate 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 thefour-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=interact
ive
! $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
441
442 Adams/Car
! $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
units
frequency_range Real
the maximum amplitude of the shaker pad vertical displacement.
Hardcoded to millimeters for tutorial, but you can expand it to include other
units.
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.
!---- Check to ensure the assembly has the proper test rig ---if condition=($assembly.original_testrig_name != "__acme_4PostRig")
acar toolkit warning &
w="Analysis cannot be submitted!", &
"The assembly does not have the proper testrig. This analysis only", &
"works with assemblies using the '__acme_4PostRig' testrig."
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)
return
end
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
443
444 Adams/Car
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_ti
re"),"til_*")))
variable set variable=$_self.rightFrontWheel &
object_value=(eval(db_filter_name(db_children($_self.frontWheel[1],"ac_ti
re"),"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_tir
e"),"til_*")))
variable set variable=$_self.rightRearWheel &
object_value=(eval(db_filter_name(db_children($_self.rearWheel[1],"ac_tir
e"),"tir_*")))
marker modify &
marker_name=(eval($_self.leftFrontWheel.object_value.ref_marker.object_va
lue)) &
new_marker_name=
(eval($assembly.testrig.col_front_pad_mount[1]//"."//$_self.leftFrontWheel.o
bject_value.ref_marker.object_value.name))
marker modify &
marker_name=(eval($_self.rightFrontWheel.object_value.ref_marker.object_v
alue)) &
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_val
ue)) &
new_marker_name=(eval($assembly.testrig.col_rear_pad_mount[1]//"."//$_sel
f.leftRearWheel.object_value.ref_marker.object_value.name))
marker modify &
marker_name=(eval($_self.rightRearWheel.object_value.ref_marker.object_va
lue)) &
new_marker_name=(eval($assembly.testrig.cor_rear_pad_mount[1]//"."//$_sel
f.rightRearWheel.object_value.ref_marker.object_value.name))
variable set variable=$assembly.fourpostSetup &
integer_value=1
end
You must reset the motion actuators drivingthe displacement of the shaker pads for each individual fourpost 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")
acar template_builder actuator set function &
actuator=$assembly.testrig.jms_left_front_actuator
&
function="1*$peak_displacement*sin(.5*360d*$frequency_range/$end_tim
e*time**2)"
actuator=$assembly.testrig.jms_right_front_actuator
&
e*time**2)"
actuator=$assembly.testrig.jms_left_rear_actuator
&
e*time**2)"
actuator=$assembly.testrig.jms_right_rear_actuator
&
e*time**2)"
!-- Pitch Excitation
elseif condition=("$excitation_mode" == "pitch")
&
e*time**2)"
&
e*time**2)"
&
function="1*$peak_displacement*sin(.5*360d*$frequency_range/$end_time*time**2)"
&
!-- Roll Excitation
elseif condition=("$excitation_mode" == "roll")
&
445
446 Adams/Car
e*time**2)"
&
&
e*time**2)"
&
!-- Warp Excitation
elseif condition=("$excitation_mode" == "warp")
&
e*time**2)"
&
&
&
e*time**2)"
end
Submitting the Analysis

After the macro sets up the assembly, you set up the macro to submit the assembly for the four-post
analysis. Since this is a full-vehicle assembly, you use the corresponding full-vehicle submission utility
macro. Note that the syntax for calling this macro is practically the same as that used in the standard
Adams/Car full-vehicle analyses. In this case, two additional parameters are specified to have nondefault values for the four-post simulation: generate_road_geometry and simulation_type.
The following shows the code fragment for calling the full-vehicle submission utility macro:
!---- Perform the analysis ---acar analysis full_vehicle submit &
analysis_name="$'output_prefix'_fourpost"
end_time=$end_time &
number_of_steps=$number_of_steps &
analysis_mode=$analysis_mode &
load_results=$load_results &
brief=$brief &
road_data_file="BEDPLATE" &
generate_road_geometry=no &
simulation_type=fourpost
&
The following table describes the important parameters associated with the four-post full-vehicle
submission macro.
Parameter name:
Description:
load_results
String value that specifies if the results of the analysis should be read in
after the analysis is complete. Expected values are yes or no.
road_data_file
Hardcoded to BEDPLATE to indicate that the carwill not be driven across

a road surface. Adams/Car internally interprets and understands this
hardcoded value.
generate_road_geometry
Set to no to indicate that Adams/Car should not generate a geometric

representation of the data found in the road_data_file.
simulation_type
Hardcoded to fourpost to indicate that the full-vehicle will be attached to

a four-post shaker table. Adams/Car internally interprets and understands
this hardcoded value to produce the correct .adm and .acf files.
Logging the Analysis Results

Once the analysis completed, the macro logs the results to a file. In addition, you can set up the macro
so it displays final diagnostic messages to the message window, as follows:
if condition=($log_file)
acar analysis full_vehicle log &
analysis_name="$'output_prefix'_fourpost"
&
analysis_type="Four Post Shaker Test"
&
analysis_log_file="$'output_prefix'_fourpost.log"
comment=$comment &
end_time=$end_time &
number_of_steps=$number_of_steps &
road_data_file="BEDPLATE" &
initial_velocity=0.0 &
velocity_units="m_sec" &
input_parameters="general input"
&
parameter_values=("$number_of_steps")
end
&
if condition=("$analysis_mode" != "background")
acar toolkit message &
message="Simulation is complete."
end
Finishing up the Macro
Delete all local variables created in the macro using the $_self nomenclature:
variable delete variable_name=(eval(db_children($_self,"variable")))
447
448 Adams/Car
Adding the Four-Post Analysis Macro to a Binary

You can add the four-post analysis macro to either the private or site binary. The command shown next
creates the macro by reading in the command file found at the location you specified. Place the command
in the file acar_build.cmd as described in Configuring Your Product.
macro read macro_name=.acme.macros.mac_ana_ful_fou &
file_name=(getenv("MDI_ACAR_SITE")//"/analysis/macros/mac_ana_ful_fou_s
ub.cmd")
&
user_entered_command="acme analysis full_vehicle four_post submit" &
wrap_in_undo=no &
create_panel=no
Testing the New Analysis Macro

The easiest way to test the four-post analysis macro is to access it from the Command Navigator. The
command you should use is the user_entered_command specified in the acar_build.cmd file shown in
Adding the Four-Post Analysis Macro to a Binary.
When you access the four-post macro from the Command Navigator, Adams/Car automatically creates
a dialog box based on the parameters in the macro. Users can use this dialog box, shown next, to execute
the macro and submit the four-post analysis.
Macro-Generated Dialog Box
Customizing the Four-Post Analysis Dialog Box

Now that you created the four-post analysis macro, the custom graphical interface is also almost
complete. When you access the four-post macro using the Command Navigator, Adams/Car displays a
default dialog box associated with that macro, as shown in figure Macro-Generated Dialog Box. Compare
this dialog box to the one shown in figure Customized Dialog Box. The customized dialog box illustrates
an example of what you might want to do with the default dialog box generated using the Command
Navigator:
Change the dialog box title.
Remove the Comments and Error Variable text boxes (they will take on their default values as
defined in the macro).
Modify the Load Results pull-down menu to be radio boxes, and then decrease the area they
occupy.
Shorten the Brief and Log File pull-down menus to match the Load Results radio boxes.
449
450 Adams/Car
Learn about customizing the interface.
Customized Dialog Box
You can add the four-post custom dialog box to either the private or site binary (or interactively read it
in during your Adams/Car session). The command shown next creates the dialog box by reading in the
command file found at the location you specify or we have provided an example dialog box in the
examples directory (install_dir\acar\examples\fourpost\customization_example\analysis\dboxes).
We have also provided dboxes_ana.cmd in the example, which contains the following code.
You must place these commands either in the acar_build.cmd file as described in Configuring Your
Product or place a command in the macros_ana.cmd file to read the dboxes_ana.cmd file.
!---- Check if dialog box exists and delete it if it does ---if condition=(db_exists(".acar.dboxes.dbox_ana_ful_fou_sub"))
interface dialog_box delete
dialog_box_name=.acar.dboxes.dbox_ana_ful_fou_sub
end
!---- Read the Fouir Post shaker dialog box ----
file command read &

file_name=(getenv("MDI_ACAR_SITE")//"/analysis/dboxes/dbox_ana_ful_fou_sub.c
md")
!---- Check if menu button exists and delete it if it does ---if
condition=(db_exists(".gui.main.aca_sta_mbar.simulate.full_vehicle_analysis.
ACME_FourPost"))
interface push_button delete &
push_button_name =
.gui.main.aca_sta_mbar.simulate.full_vehicle_analysis.ACME_FourPost
end
!---- Add a menu option ---interface push_button create &
push_button_name =
.gui.main.aca_sta_mbar.simulate.full_vehicle_analysis.ACME_FourPost &
enabled = yes &
help_text = "Simulate a full-vehicle on the ACME FourPost testrig" &
units = relative &
horiz_resizing = scale_all &
vert_resizing = scale_all &
location = 0.0, 0.0 &
label = "&ACME Fourpost..." &
commands = "interface dialog_box display
dialog=.acar.dboxes.dbox_ana_ful_fou_sub" &
default = false
451
452 Adams/Car
Examples
2 New Template 2005
Examples
Getting Started Using Adams/Driveline
Example Files:

$--------------------------------------------------MDI_HEADER
[MDI_HEADER]
FILE_TYPE
= 'pwr'
FILE_VERSION
= 1.0
FILE_FORMAT
= 'ASCII'
$--------------------------------------------------UNITS
[UNITS]
(BASE)
{length
force angle mass time}
'mm'
'newton' 'degree' 'kg' 'sec'
{unit_type
length force angle mass time conversion}
'Nmm'
1 1 0 0 0 1.0
$--------------------------------------------------ENGINE
[ENGINE]
(Z_DATA)
{throttle}
0.0
1.00
(XY_DATA)
{engine_speed
<no_units> torque <Nmm>}
0
0 0
500
-20000
80000
1000
-42000 135000
1500
-44000 200000
2000
-46000 245000
2500
-48000 263000
3000
-50000 310000
3500
-50000 358000
4000
-50000 404000
4500
-50000 455000
5000
-50000 475000
5500
-50000 485000
6000
-50000 468000
6250
-50000 462000
6500
-52000 455000
6750
-56000 427000
7000
-60000 370000
7500
-64000 259000

Adams Driveline Mdr3 Help

Hochgeladen von

Dokumentinformationen

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Adams Driveline Mdr3 Help

Hochgeladen von

Copyright:

Verfügbare Formate

Welcome to Adams/Driveline

fixtures, and test procedures.

losing testing time because of poor weather conditions.

Learning the Basics

Adams/Driveline Standard Interface

select Standard Interface, and then select OK.

configured to run in standard-interface mode. Select OK.

The Adams/Driveline Standard Interface appears.

select Standard Interface, and then select OK.

configured to run in standard mode. Select OK.

The Adams/Driveline Standard Interface appears.

Learning the Basics

Adams/Driveline Template Builder

Interfaces and Access

templates for use in the Standard Interface.

About User Access

Learning the Basics

Setting User Access

You can set USERMODE to:

Navigating Through a Modeling Database

Viewing Information About Your Model

About the Database Navigator

Learning the Basics

To display the Database Navigator, do any of the following:

Your template-based product displays the Database Navigator.

Showing, Hiding, and Selecting Objects in the Database

To show or hide objects below a single object:

Managing the Select List

Learning the Basics

To view the select list:

Filtering Objects in the Database Navigator

Sorting Objects in the Database Navigator

Setting Highlighting in the Database Navigator

Setting Appearance of Objects Through the Database

the objects outline or its name.

State of the object during a simulation: active or inactive.

To set the appearance of objects:

Learning the Basics

Renaming Objects Through the Database Navigator

Adding Comments Through the Database Navigator

Viewing Model Topology Through the Database Navigator

constraints or forces are affecting it.

displays any unconnected parts.

To display model topology of parts and connections:

Viewing the Associativity of Objects

3. From the tree list or main window, select an object.

Learning the Basics

To save the current associativity information to a file:

Viewing Object Information Through Database Navigator

Viewing Model Topology Map Through Information Window

constraints or forces are affecting it.

displays any unconnected parts.

To display model topology by parts, do one of the following:

the Model Topology by Parts tool

To display model topology by connections:

Learning the Basics

Working with the Information Window

Displaying Object Information and Accessing Information

Information about the object appears in the Information window.

of the object, and then select Apply.

Displaying Parent and Children Information

To display an object's children:

Learning the Basics

To display an object's parent, do one of the following: