Adams 2021.

3
Getting Started: Adams Controls
Corporate Europe, Middle East, Africa
MSC Software Corporation MSC Software GmbH
5161 California Ave, Suite 200 Am Moosfeld 13
University Research Park 81829 Munich, Germany
Irvine, CA 92617 Telephone: (49) 89 431 98 70
Telephone: (714) 540-8900 Email: [email protected]
Email: [email protected]

Japan Asia-Pacific
MSC Software Japan Ltd. MSC Software (S) Pte. Ltd.
KANDA SQUARE 16F 100 Beach Road
2-2-1 Kanda Nishikicho, Chiyoda-ku #16-05 Shaw Tower
Tokyo 101-0054, Japan Singapore 189702
Telephone: (81)(3) 6275 0870 Telephone: 65-6272-0082
Email: [email protected] Email: [email protected]

Worldwide Web
www.mscsoftware.com

Support
http://www.mscsoftware.com/Contents/Services/Technical-Support/Contact-Technical-Support.aspx

Disclaimer
This documentation, as well as the software described in it, is furnished under license and may be used only in accordance with the
terms of such license.
MSC Software Corporation reserves the right to make changes in specifications and other information contained in this document
without prior notice.
The concepts, methods, and examples presented in this text are for illustrative and educational purposes only, and are not intended
to be exhaustive or to apply to any particular engineering problem or design. MSC Software Corporation assumes no liability or
responsibility to any person or company for direct or indirect damages resulting from the use of any information contained herein.
User Documentation: Copyright © 2021 MSC Software Corporation. Printed in U.S.A. All Rights Reserved.
This notice shall be marked on any reproduction of this documentation, in whole or in part. Any reproduction or distribution of this
document, in whole or in part, without the prior written consent of MSC Software Corporation is prohibited.
This software may contain certain third-party software that is protected by copyright and licensed from MSC Software suppliers.
Additional terms and conditions and/or notices may apply for certain third party software. Such additional third party software terms
and conditions and/or notices may be set forth in documentation and/or at http://www.mscsoftware.com/thirdpartysoftware (or successor
website designated by MSC from time to time). Portions of this software are owned by Siemens Product Lifecycle Management, Inc.
© Copyright 2021
The MSC Software logo, MSC, MSC Adams, MD Adams, and Adams are trademarks or registered trademarks of MSC Software
Corporation in the United States and/or other countries. Hexagon and the Hexagon logo are trademarks or registered trademarks of
Hexagon AB and/or its subsidiaries. FLEXlm and FlexNet Publisher are trademarks or registered trademarks of Flexera Software.
Parasolid is a registered trademark of Siemens Product Lifecycle Management, Inc. All other trademarks are the property of their
respective owners.

ADAM:V2021.3:Z:Z:Z:DC-GS-CONT
Documentation Feedback
At MSC Software, we strive to produce the highest quality documentation and welcome your feedback.
If you have comments or suggestions about our documentation, write to us at: documentation-
[email protected].
Please include the following information with your feedback:
 Document name
 Release/Version number
 Chapter/Section name
 Topic title (for Online Help)
 Brief description of the content (for example, incomplete/incorrect information, grammatical
errors, information that requires clarification or more details and so on).
 Your suggestions for correcting/improving documentation
You may also provide your feedback about MSC Software documentation by taking a short 5-minute
survey at: http://msc-documentation.questionpro.com.

Note: The above mentioned e-mail address is only for providing documentation specific
feedback. If you have any technical problems, issues, or queries, please contact Technical
Support.
 1

Getting Started Using Adams Controls

2 Getting Started Using Adams Controls
Overview

Introducing and Starting the Tutorials

Overview
This chapter starts you off on the process of adding controls to your Adams model. Following this chapter
are tutorials for some of the controls applications you can use with Adams Controls: co-simulation and
Control System Import with Easy5 or MATLAB. After you finish this chapter, continue with the tutorial that
is specific to the controls application you are using.
This chapter contains the following sections:
 About the Tutorial
 How You’ll Learn Adams Controls
 Starting Adams View
 Step One - Build the Adams Model
 Step Two - Creating the Adams Plant Inputs and Outputs
Before doing these tutorials, you should be familiar with the basic features of the Adams View interface. Refer
to the online help for Adams View for information about the Adams View interface.

This tutorial takes about two hours to complete.

About the Tutorial

The tutorials in this guide give you an overview of the four-step process of adding controls to an Adams
model. See About the Adams Controls Four-Step Process in Adams Controls online help, for a description of the four-
step process. This chapter covers Steps One and Two of the process in depth. You'll learn how to:
 Import an Adams model and run a trial simulation with Adams View.
 Use the Adams Controls interface to identify the inputs and outputs from your Adams model, and
create the files for the plant model in Easy5 and MATLAB/Simulink.
Steps Three and Four are covered in the chapters that follow for each controls application.

How You’ll Learn Adams Controls

By following the tutorials in this guide, you’ll apply the four-step process of using Adams Controls on a simple
antenna-pointing problem. The objective of the problem is to add a control system to the antenna that will
move the antenna along a defined path to track a satellite signal.
For this tutorial, you will supply the torque that pivots the antenna in the azimuthal (horizontal) direction.
The torque level will be computed by a control system, based on the error between the actual antenna
position and the desired antenna position. This is more realistic than attaching an Adams motion to the pivot
and driving the motion directly. By applying a torque, you can look at issues related to motor size in an actual
mechanical system.
 Introducing and Starting the Tutorials 3
Starting Adams View

Starting Adams View

In this section, you learn how to create a new directory and start Adams Controls from within Adams View
in the Linux and Windows environments.
In the Linux environment, you start Adams View from the Adams Toolbar, and then, from within Adams View,
you load the Adams Controls plugin. For information on the Adams Toolbar, see the online help for Running
and Configuring Adams.
In the Windows environment, you start Adams View from the Start menu, and then load the Adams
Controls plugin. For more information, see the online help for Running and Configuring Adams.

To start Adams View:

1. Copy all of the files in install_dir/controls/examples/antenna to a new directory.
2. Do either of the following depending on the platform on which you are running Adams View:
• In Linux, type the command to start the Adams Toolbar at the command prompt, and then press
Enter. Select the Adams View tool .
• In Windows, from the Start menu, point to Programs, point to Adams 2021.3, point to and then
select Adams View.
The Welcome to Adams dialog box appears, in the Adams View main window.

Step One - Build the Adams Model

Now you’ll import an Adams model and familiarize yourself with its construction by following the next four
sections:
 Build the Adams Model
 Loading Adams Controls
 Familiarizing Yourself with the Model
 Running a Trial Simulation

Build the Adams Model

1. Select Import a File.
2. In the Start In text box on the Adams View welcome screen, enter the name of your new directory
(the one created in Step 1. in To start Adams View: above).
This sets your new directory as your working directory.
3. Select OK to close the Adams View welcome screen.
4. In the File Import dialog box, right-click the File to Read text box, and then select Browse.
The File Selection dialog box appears.
5. Select the file antenna.cmd.
6. Select OK.
4 Getting Started Using Adams Controls
Step One - Build the Adams Model

The antenna model main_olt appears as shown in Figure 1.

7. To change the display of the antenna from a wire frame into a shaded, three-dimensional image, from

the Status Toolbar, select Wireframe/Shaded toggle for current view.

Antenna
Elevation bearings

Plate
Antenna support

Reduction gear
Azimuth rotor

Figure 1 Shaded Model of Antenna

Loading Adams Controls

Because Adams Controls is a plugin for Adams View, you need to load Adams Controls when you use it with
Adams View.

To load Adams Controls:

1. From the Tools menu, point to Plugin Manager.
2. Select the Load checkbox next to Adams Controls.
3. Select OK.
Adams View loads the Adams Controls plugin.

Note: To automatically load Adams Controls each time Adams View starts up, select Load at
Startup in the Plugin Manager.

Familiarizing Yourself with the Model

This model is designed so that its base turns in the azimuthal (horizontal) direction and its antenna tilts in
the vertical direction.
 Introducing and Starting the Tutorials 5
Step One - Build the Adams Model

To familiarize yourself with the model, locate the following components:

 Azimuth rotor (peach) connected to ground by revolute joint.
 Azimuth reduction gear (sky blue) connected to ground by revolute joint.
 Azimuth plate (magenta) connected to ground by revolute joint.
 Antenna support (silver) connected to plate by fixed joint.
 Elevation bearings (peach) connected to support by fixed joint.
 Antenna (sky blue) connected to bearings by revolute joint.
 rotor_gear, couples the revolute joint at the rotor to the revolute joint at the reduction gear.
 gear_plate, couples the revolute joint at the reduction gear to the revolute joint at the plate.

Running a Trial Simulation

To run a trial simulation with Adams View:
1. Click the Simulation tab on the Adams View ribbon.

2. From the Simulate container, click the Interactive Simulation tool .

3. Enter the following in the Simulation Controls dialog box:
• End Time: 0.5
• Steps: 250
4. Select Start at equilibrium.

5. Select the Start tool .

The base of the mechanism turns counterclockwise as the antenna tilts up and down.

Deactivating the Motion

Now that you know the model is working properly, you can begin the process of adding a control system to
it. The first step is to deactivate the azimuthal motion on the model. After the motion has been deactivated,
you will apply a torque to the joint .main_olt.azimuth_actuator based on values that the controls
system package provides.

To deactivate the motion:

1. From the Edit menu, select Deactivate.
The Database Navigator appears.
2. Double-click the model main_olt.
A list of parts and motions appears.
3. Scroll down the list and select azimuth_motion_csd.
6 Getting Started Using Adams Controls
Step Two - Creating the Adams Plant Inputs and Outputs

4. Select OK.
Adams View deactivates the motion.

5. Select the Reset to Start tool to reset the simulation back to its first frame.
6. Rerun the simulation.
Now that you’ve deactivated the azimuthal motion, the antenna moves up and down, but it does not
sweep horizontally as it did during the last simulation.

Note: You might detect some small movement in the azimuthal direction because the model
has no constraints or restoring forces to control its natural movement. You should also
notice that the bending of the antenna support beam decreases when the azimuthal
motion is deactivated. The flexing illustrates that a certain amount of coupling takes
place between the elevation and azimuthal movements.

Step Two - Creating the Adams Plant Inputs and

Outputs
Now you’ll create the inputs and outputs on the Adams model by:
 Identifying the Adams Plant Inputs and Outputs
 Verifying Input Variables
 Verifying Input Functions
 Verifying Output Functions
 Exporting the Adams Plant Files for the Controls Application

Identifying the Adams Plant Inputs and Outputs

Figure 2 indicates the flow path of the input and output variables shared between the antenna model and its
control system. This diagram shows that when you supply an input control torque to the antenna model, you
send outputs azimuth_position and rotor_velocity to the controller.
The steps you follow to achieve this closed-loop circuit are:
 Define the input and output variables in Adams View.
 Read in the plant and the input/output variables using Easy5 or MATLAB, create an Adams plant,
and run a simulation.
 Animate and plot the simulation results in Adams View.
 Modify the variables and repeat this process as necessary.
 Introducing and Starting the Tutorials 7
Step Two - Creating the Adams Plant Inputs and Outputs

Input = control _torque Adams Output = azimuth_position and

model rotor_velocity

Control
system

Figure 2 Terminology for Adams Inputs and Outputs

Verifying Input Variables

Adams Controls and controls applications, such as Easy5 and MATLAB, communicate by passing state
variables back and forth. Therefore, you must define your model’s input and output variables (and the
functions that those inputs and outputs reference) with a set of Adams state variables.
This step has already been done for you in the antenna model that you imported. When you create a model
of your own, you will have to define the state variables for your input and output variables.
For this tutorial, you will only verify that the state variables in the antenna model and control system
correspond to the correct input and output variables. For a description of state variables, see the online help.

To verify the input variables:

1. From the Model Browser window, click Elements and expand.
2. Expand System Elements.

3. Double-click control_torque.
The Create/Modify State Variable dialog box appears.
8 Getting Started Using Adams Controls
Step Two - Creating the Adams Plant Inputs and Outputs

Figure 3 Modify State Variable Dialog Box

4. Look in the F(time, ...) = text box and verify that the run-time function for the input variable,
control_torque, is 0.0.
Because the control torque will get its value from the control application, the 0.0 will be overwritten
during each step of the simulation.
5. Select Cancel to close the Modify State Variable dialog box.

Note: After you close the box, click in the background of the screen to clear the selection of
the model.

Verifying Input Functions

Now you’ll verify the function that references the input variable.

To verify the function that is referenced to the input variable control_torque:

1. From the Edit menu, select Modify.
The Database Navigator appears.
2. Double-click main_olt, and then double-click azimuth_actuator (azimuth_actuator is the name of
the control torque).
The Modify Torque dialog box appears.
 Introducing and Starting the Tutorials 9
Step Two - Creating the Adams Plant Inputs and Outputs

Figure 4 Modify Torque Dialog Box

3. Look in the Function text box and verify that the run-time function for the input variable reads:
VARVAL(.main_olt.control_torque).

Note: VARVAL (variable value) is the Adams function that returns the value of the given
variable. Notice that the function is defined as the value of the control_torque
variable. In other words, the input control torque (azimuth_actuator) gets its
value from the input variable.

4. Select Cancel to close the Modify Torque dialog box.

Verifying Output Functions

Now you’ll verify the output functions just as you verified the input functions in the previous section.

To verify the output functions:

1. From the Model Browser window, click Elements and expand.
2. Expand System Elements.
3. Double-click azimuth_position.
10 Getting Started Using Adams Controls
Step Two - Creating the Adams Plant Inputs and Outputs

The Create/Modify State Variable dialog box appears.

Figure 5 Modify State Variable Dialog Box

4. Look in the F(time, ...) = text box to verify that the run-time function for the output variable is
AZ(MAR70, MAR26).
This function returns the angle about the z-axis, the vertical axis about which the antenna rotates.
Therefore, the function assigns the rotational position of the antenna to the output state variable.
5. Right-click the Name text box, point to ADAMS_Variable, point to Guesses, and then select
rotor_velocity.
The Modify State Variable dialog box updates.
6. Look at the F(time, ...) = text box and verify the run-time function for the output variable is
WZ(MAR21, MAR22, MAR22).
This function measures the rotational velocity of the rotor relative to ground.
7. Select Cancel to close the dialog box.

Exporting the Adams Plant Files for the Controls Application

In this section, you will export the Adams linear and nonlinear plant files.

To export the nonlinear plant files:

1. From the Plugins tab, click on the Controls container and select Plant Export.
The Adams Controls Plant Export dialog box appears.
2. In the New Controls Plant text box, enter ant_test.
 Introducing and Starting the Tutorials 11
Step Two - Creating the Adams Plant Inputs and Outputs

3. In the File Prefix text box, type ant_test for the filename.
This defines the prefix for the .adm, .cmd, .m, and .inf files created by the Plant Export dialog
box.
4. Right-click the Input Signal(s) text box, point to ADAMS_Variable, and then select Browse.
The Database Navigator appears.
5. In the Database Navigator, select control_torque, and then select OK.
6. In the Adams Controls Plant Export dialog box, right-click the Output Signal(s) text box, point to
ADAMS_Variable, and then select Guesses.
A selection list appears.
7. From the selection list, select rotor_velocity.
8. Repeat Step 6, and then from the selection list, select azimuth_position.

Note: It is important to maintain the above selection order for selecting output signals so
that the model works properly with the example MATLAB or Easy5 model.

9. From the Target Software pull-down menu, select the controls application you are using during this
session: MATLAB or Easy5.
10. Confirm that Analysis Type is set to non_linear and Initial Static Analysis is set to No.

Note: If Analysis Type is set to linear and Initial Static Analysis is set to Yes, Adams Controls
conducts a static analysis before the linear analysis. Otherwise, Adams Controls
performs an initial conditions analysis.

11. Verify that the Adams Solver choice set as desired and Adams Host Name is set to your machine
name.
Be sure that the name for Adams Host is a fully qualified hostname or localhost if using TCP/IP
communication with co-simulation or function evaluation mode. This is not required for PIPE-based
communication. (To be fully qualified, the hostname must contain the workstation and domain
name.) If the Adams Host is not fully qualified, edit the value in the text box so that it is fully
qualified.
12. If Target Software is set to Easy5, verify that Dynamic States Output is selected.
Dynamic States Output performs an initial conditions analysis or a static analysis (if Initial Static
Analysis is set to Yes), and computes the number of states (that is, displacements, velocities) in the
model. This is used by Easy5 for Function Evaluation mode. If your model has difficulty computing
this properly, you can disable this feature, but you will not be able to use Function Evaluation mode
unless the number for NUMBER OF STATES is modified in the .inf file from Plant Export.
13. Verify that the Plant Export dialog box is completed as shown in the figure below.
12 Getting Started Using Adams Controls
Step Two - Creating the Adams Plant Inputs and Outputs

Figure 6 Adams Controls Plant Export Dialog Box

14. Select OK.

Adams Controls saves the input and output information in an .m (for MATLAB) or .inf file (for
Easy5). It also generates a command file (.cmd) and a dataset file (.adm) that are used during the
simulation process. Empty file called aviewAS.cmd is also created which will prevent the startup
screen from displaying when simulating interactively with Adams View.

Note: The ant_test Controls Plant you just created is saved in the modeling database. By
importing settings from an existing plant, you can generate new plants based on plants
you already created.

To export the linear plant files (optional: not required for co-simulation or function evaluation):
1. From the Plugins tab, click on the Controls container and select Plant Export.
2. In the Adams Controls Plant Export dialog box, create a new controls plant by importing settings from a
previous plant.
3. Change the file prefix from ant_test to ant_test_l.
4. Set Analysis Type to Linear.
 Introducing and Starting the Tutorials 13
Step Two - Creating the Adams Plant Inputs and Outputs

5. Set Initial Static Analysis to Yes.

6. Select OK.
Adams Controls generates the linear model of the Adams model in four matrices: ant_test_la,
ant_test_lb, ant_test_lc, and ant_test_ld.
Adams Controls setup is complete after the plant files have been exported. Now you will go to the specific
controls application (Easy5 or MATLAB) and complete the link between the controls and mechanical
systems.

Notes: You have now finished the introduction to the Adams Controls tutorials. To continue
learning the Adams Controls interface, go to the tutorials that follow this section. If you are
using:

 MATLAB Co-Simulation or Function Evaluation, go to Learning Adams Controls with

MATLAB Co-Simulation/Function Evaluation.
 Control System Import with MATLAB, go to Learning Adams Controls with Control System
Import from MATLAB.
 Control System Import from MATLAB with S-Functions, go to Learning Adams
Controls with Control System Import from MATLAB with S-Functions.
 Easy5 Co-Simulation or Function Evalutation, go to Learning Adams Controls with Easy5
Co-Simulation/Function Evaluation.
 Control System Import with Easy5, go to Learning Adams Controls with Control System
Import from Easy5.
14 Getting Started Using Adams Controls
Step Two - Creating the Adams Plant Inputs and Outputs
 Learning Adams Controls with MATLAB Co-Simulation/Function Evaluation 15
Overview

Learning Adams Controls with

MATLAB Co-Simulation/Function
Evaluation
Overview
This chapter teaches you how to use Adams Controls with MATLAB in co-simulation. It contains the
following sections:
 About the Tutorial
 Step Three - Adding Controls to the Adams Block Diagram
 Step Four - Simulating the Model

Note: Before beginning this tutorial, you should have finished Introducing and Starting the Tutorials.

About the Tutorial

This chapter provides procedures for using Adams Controls with MATLAB in co-simulation. It teaches you
Steps 3 and 4 of the four-step process of adding controls to an Adams model. You will learn how to:
 Add an Adams plant to your block diagram in MATLAB simulation.
 Simulate an Adams model with a complex control system.
 Plot simulation results.

Step Three - Adding Controls to the Adams Block

Diagram
You will add controls to the Adams block diagrams by:
 Starting MATLAB
 Creating the Adams Block Diagram
 Constructing the Controls System Block Diagram
 Setting Simulation Parameters in the Plant Mask

Starting MATLAB
A note about your Adams license(s): Running an Adams Controls cosimulation will check out an Adams
Solver license and possibly an Adams View license (for interactive simulations only). To ensure that you are
able to run these products, you may need to close any Adams applications that use these licenses.
16 Getting Started Using Adams Controls
Step Three - Adding Controls to the Adams Block Diagram

To start using MATLAB:

1. Start MATLAB on your system.
2. Change directories to the one in which your ant_test.m file resides (the working directory you
specified during your Adams Controls session).
You can do this by entering the following:
• On Windows: cd c:\new_dir, where new_dir is the name of your working directory.
• On Linux, cd /new_dir, where new_dir is the name of your working directory.
3. At the prompt (>>), type ant_test.
MATLAB echoes:
%%%INFO:Adams plant actuators names:
1 control_torque
%%%INFO:Adams plant sensors names:
1 rotor_velocity
2 azimuth_position.
4. At the prompt, type who to get the list of variables defined in the files.
MATLAB echoes the following relevant information:

ADAMS_communication_interval ADAMS_communications_per_output ADAMS_cwd

_step
ADAMS_exec ADAMS_host ADAMS_init
ADAMS_inputs ADAMS_mode ADAMS_outputs
ADAMS_pinput ADAMS_poutput ADAMS_prefix
ADAMS_solver_type ADAMS_static ADAMS_sysdir
ADAMS_time_offset ADAMS_uy_ids ADAMS_version

You can check any of the above variables by entering them in at the MATLAB prompt. For example,
if you enter ADAMS_outputs, MATLAB displays all of the outputs defined for your mechanism:
ADAMS_outputs=
rotor_velocity!azimuth_position

Notes: If you want to import the linearized Adams model, use ant_test_l.m instead of
ant_test.m. The main difference is in the ADAMS_mode variable:

 In ant_test.m, ADAMS_mode=non_linear.
 In ant_test_l.m, ADAMS_mode=linear.
 Learning Adams Controls with MATLAB Co-Simulation/Function Evaluation 17
Step Three - Adding Controls to the Adams Block Diagram

Creating the Adams Block Diagram

To create the Adams block diagram:
1. At the MATLAB prompt, enter adams_sys.
This builds a new model in Simulink named adams_sys_.mdl. This model contains the MSC
Software S-Function block representing your mechanical system.
A selection window containing the Adams blocks appears. These blocks represent your Adams model
in different ways:
• The S-Function represents the nonlinear Adams model.
• The adams_sub contains the S-Function, but also creates several useful MATLAB variables.
• The State-Space block represents a linearized Adams model.

Note: An error or warning symbol may appear at the State-Space block indicating that the
ADAMS_a, ADAMS_b, ADAMS_c and ADAMS_d variables do not exist in
workspace. This is normal and can be ignored when the model has been exported as
non-linear from the Adams controls plant export as in this example.

The adams_sub block is created based on the information from the .m file (either from
ant_test.m or ant_test_l.m). If the Adams_mode is nonlinear, the S-Function block is used in
the adams_sub subsystem. Otherwise, the State_Space block is copied into adams_sub.
18 Getting Started Using Adams Controls
Step Three - Adding Controls to the Adams Block Diagram

Figure 7 Simulink Selection Window

2. From the File menu, point to New, and then select Blank Model.
A new selection window for building your block diagram appears.
3. Drag and drop the adams_sub block from the adams_sys_ selection window onto the new selection
window.
4. Double-click the adams_sub block.
All of the elements in the subsystem appear.
 Learning Adams Controls with MATLAB Co-Simulation/Function Evaluation 19
Step Three - Adding Controls to the Adams Block Diagram

Figure 8 adams_sub block

Note: The inputs and outputs you defined for the model appear in the sub-block. The input and
output names automatically match up with the information read in from the ant_test.m
file.

Constructing the Controls System Block Diagram

The completed block diagram is in the file, antenna.mdl, in the examples directory. To save time, you can
read in our diagram instead of building it. Remember to update the settings in the plant mask if you decide
to use this file (see Setting Simulation Parameters in the Plant Mask).
20 Getting Started Using Adams Controls
Step Three - Adding Controls to the Adams Block Diagram

Note: If the Simulink model containing the adams_sub block was created in an earlier version of
Adams Controls, you should run adams_sys again to create a new adams_sub block to
replace the existing one for better performance.

Only one adams_sub block is permitted per Simulink model.

To construct the controls system block diagram:

1. At the MATLAB prompt, type simulink.
The Simulink library selection windows appear. Use the block icons from the windows to complete
your controls block diagram. Each icon contains a submenu.
2. Double-click each icon to reveal its submenu.
3. Look at the controls block diagram Figure 9 and Table 1, which describes the topology in tabular form.
4. Drag and drop the appropriate blocks from the Simulink library to complete your block diagram as
shown in Figure 9.

Figure 9 Controls Block Diagram

5. From the File menu, select Save As, and enter a file name for your controls block diagram.
 Learning Adams Controls with MATLAB Co-Simulation/Function Evaluation 21
Step Three - Adding Controls to the Adams Block Diagram

Table 1 Topology in Tabular Form

Quantity Library Block Type
1 Sources Step
2 Continuous Transfer Function
2 Math Ops Sum
3 Sinks Scope(not floating)
Step Parameters Continuous Transfer Function Parameters
Step Time: 0.001 1 Numerator: [1040]
Initial Value: 0 Denominator: [0.001 1]
Final value: 0.3 Absolute tolerance: auto
Sample time: 0.001 2 Numerator: [950]
[X] Interpret vector parameters as 1-D Denominator: [0.001 1]
[X] Enable zero crossing detection Absolute tolerance: auto
Sum Parameters Scope
1 SumP 1 torque
Icon shape: rectangular 2 rotor_vel
List of signs: +- 3 azimuth_pos
[ ] Show additional parameters
2 SumV
Icon shape: rectangular
List of signs: +-
[ ] Show additional parameters

Setting Simulation Parameters in the Plant Mask

To set the simulation parameters:
1. From the controls block diagram, double-click the adams_sub block.
2. From the new Simulink selection window, double-click the MSC Software block.
The Adams Plant Mask dialog box appears.
22 Getting Started Using Adams Controls
Step Three - Adding Controls to the Adams Block Diagram

Figure 10 Adams Plant Mask

3. In the Output Files Prefix text box, enter ‘mytest’.

 Learning Adams Controls with MATLAB Co-Simulation/Function Evaluation 23
Step Three - Adding Controls to the Adams Block Diagram

Be sure to enclose the name with single quotation marks. Adams Controls will save your simulation
results under this name in the three file types listed in Table 2-1

Note: If no output files are required, then insert empty single quotes ('').

Table 2-1 File Types

File Name File type: What the file contains
mytest.res Results Adams Solver analysis data and Adams View graphics data
mytest.req Requests Adams Solver analysis data
mytest.gra Graphics Adams View graphics data

4. Select the Adams solver type of Fortran.

To run the simulation using Adams Solver (C++), you can change the setting to C++.
5. Select the Interprocess Option of PIPE(DDE).
This option defines the communication method between MATLAB and Adams. You can change this
setting to TCP/IP, if you want to run MATLAB and Adams on separate machines and communicate
using TCP/IP protocol. Using this protocol, Adams_host defines the machine on which Adams runs.
For more information, see TCP/IP Communication Mode in the Adams Controls help.
6. Select a simulation parameter for each text box.
• Set Animation mode to interactive.
Animation mode controls whether you graphically monitor your simulation results in Adams
View (interactive), or you simulate with Adams Solver (batch). See the online help for more details
about animation modes.
• Set Simulation mode to discrete.
This mode specifies that the simulation run in co-simulation -- Adams solves the mechanical
system equations and that the controls application solves the control system equations. The
variables exchanged between Adams and MATLAB are exchanged at "discrete" intervals. See the
online help for more details about simulation modes.
7. Keep the default Communication Interval parameterized, but change the variable value in the
Workspace by executing the following command in the Matlab command window:
ADAMS_communication_interval = 0.001
The communication interval defines how often the communication between Adams and Simulink
occurs. This will affect simulation speed and accuracy.
8. Keep the default Number of communications per output step.
24 Getting Started Using Adams Controls
Step Three - Adding Controls to the Adams Block Diagram

This value controls the size of .res, .req,and gra files. It must be an integer larger than zero. For
example, if the value is n, Adams Controls writes to the output file once for every n communication
steps. This size-control mechanism only works in discrete mode.
9. To save the change, select Apply.
10. Select Cancel to close the plant mask.

Note: For more features in the Adams Controls block, select More parameters, which reveals
the following dialog box. Note that the dialog box will add and remove parameters
depending on the settings.
Learning Adams Controls with MATLAB Co-Simulation/Function Evaluation 25
Step Three - Adding Controls to the Adams Block Diagram
26 Getting Started Using Adams Controls
Step Three - Adding Controls to the Adams Block Diagram

This plant uses the following variables:

ADAMS_sysdir Adams installation directory

ADAMS_inputs Input variables View names vector
ADAMS_outputs Outputs variables View names vector
ADAMS_prefix Adams model files prefix (.adm, .cmd); also doubles as output files
prefix
ADAMS_exec Adams Solver user library or keyword (for example, acar_solver)
ADAMS_static yes|no - initial static before Co-simulation(discrete)/Function
Evaluation (continuous)
ADAMS_init Initialization commands (that is, Adams View or Solver commands,
depending on setting for Animation mode)
ADAMS_cwd Current working directory (for TCP/IP)
ADAMS_host Name of Adams server host (for TCP/IP)
ADAMS_mode Linear or non-linear (that is, co-sim, function eval)
ADAMS_solver_type FORTRAN or C++ (used to set popup menu when first loaded)
ADAMS_communication_ Time step at which Co-simulation exchange information (for
interval example,0.005); also controls output for continuous mode (Function
Evaluation)
ADAMS_communications_ Sets Adams output rate (.res, .req, .gra) integer value (default: 1)
per_output_step
ADAMS_time_offset Adams uses the Simulink simulation time minus
ADAMS_time_offset (default: 0.0).

For example, if ADAMS_time_offset = 2, the Adams simulation

starts (at Adams time = 0s) when the Simulink time = 2s. Make sure
that the Adams block is disabled when the Adams time is <0s. If not
an error will be raised.
 Learning Adams Controls with MATLAB Co-Simulation/Function Evaluation 27
Step Three - Adding Controls to the Adams Block Diagram

The following settings can be chosen:

Adams Solver type FORTRAN or C++ (will also set ADAMS_solver_type)

Interprocess option Pipe (DDE), TCP/IP or DIRECT; TCP/IP can allow different
machines run Adams and MATLAB. In DIRECT mode Adams
runs as a library within MATLAB and no inter-process
communication is involved. This mode requires MATLAB and
Adams to run on the same PC. It works only when "Animation
mode" is set to batch and "Adams Solver type" is set to C++. When
running in Linux, this mode requires the user to be logged in as root.
If the user uses a different login other than root, then the
LD_LIBRARY_PATH environment variable has to be set explicitly
to point to "<Adams install dir>/linux64" before starting MATLAB.

For example, if Adams is installed at /scratch/Adams/20xx, then the

environment variable should be set as below (This example assumes
bash shell. For a different shell, use the appropriate format).

export
LD_LIBRARY_PATH=/scratch/Adams/20xx/linux64:$LD_LIBR
ARY_PATH

In some scenarios on Linux, it has been observed that using

DIRECT mode with MATLAB causes the MATLAB to hang or
crash when the simulation is running or at the end of simulation. In
such scenarios it is recommended to start MATLAB using the -
nojvm option. This should cause the simulations to run properly.
Alternately, the PIPE option could be used instead of DIRECT.
Animation mode batch (Solver, uses .adm) or interactive (View, uses .cmd)
Simulation mode discrete (Co-simulation) or continuous (Function Evaluation)
Discrete Computational Order - For discrete mode, chooses if Simulink leads the integration (yes) or
Simulink Lead Adams lags (no); if set to no, can remove algebraic loop
Plant input interpolation order 0 = zero-order hold; 1 = linear (discrete mode only, where Simulink
leads)
Plant output extrapolation order 0 = zero-order hold; 1 = linear (discrete mode only, where Simulink
leads)
Plant input extrapolation order 0 = zero-order hold; 1 = linear (discrete mode only, where Adams
leads)
Plant output interpolation order 0 = zero-order hold; 1 = linear (discrete mode only, where Adams
leads)
Direct feedthrough yes|no - yes = Input directly effect output (continuous mode-only)
28 Getting Started Using Adams Controls
Step Four - Simulating the Model

Step Four - Simulating the Model

You will simulate your mechanical model and control system by:
 Setting the Simulation Parameters
 Executing the Simulation
 Pausing the Simulation
 Plotting from MATLAB
 Plotting from Adams View

Setting the Simulation Parameters

To set the simulation parameters:
1. From the menus on the Simulink window, select Simulation, and then select Model Configuration
Parameters.
The Simulation Parameters dialog box appears.
2. Enter the following simulation parameters:
• For Start Time, enter 0.0 seconds.
• For Stop Time, enter 0.25 seconds.
3. Select the Type text box for the Solver options:
• Set the first text box to Variable-step.
• Set the second text box to ode15s (stiff/NDF).
• Accept the default values in the remaining text boxes.
4. Select OK to close the Simulation Parameters dialog box.

Executing the Simulation

To start the simulation:
 Select Simulation -- Start.
After a few moments, a new Adams View window opens and graphically displays the simulation.
If you’re using Windows, a DOS window appears with the current simulation data. If you’re using
Linux, the current simulation data scrolls across the MATLAB window.
Adams accepts the control inputs from MATLAB and integrates the Adams model in response to
them. At the same time, Adams provides the azimuthal position and rotor velocity information for
MATLAB to integrate the Simulink model. This simulation process creates a closed loop in which
the control inputs from MATLAB affect the Adams simulation, and the Adams outputs affect the
control input levels. See Figure 2 for an illustration of the closed loop simulation process.
 Learning Adams Controls with MATLAB Co-Simulation/Function Evaluation 29
Step Four - Simulating the Model

Pausing the Simulation

The interactive capabilities of Adams Controls let you pause the simulation in MATLAB and monitor the
graphic results in Adams View. Because MATLAB controls the simulation, you must pause the simulation
from within MATLAB. You can plot simulation results during pause mode. This feature is only available
when animation mode is set to interactive.

To pause the simulation:

1. A time display in the upper left corner of the Adams screen tracks the seconds of the simulation. To
pause the simulation, move your cursor to the Simulink window, point to Simulation, and then select
Pause.
MATLAB suspends the simulation.
2. Now go back to Adams View. While the simulation is paused, you can change the orientation of the
model with the View Orientation tools in the Standard Toolbar. These tools help you to look at the
model from different vantage points.

Figure 11 Standard Toolbar

3. Once you have finished reorienting the model, resume the simulation by selecting Simulation, and
then Continue, from the toolbar on the Simulink window.
Adams View closes automatically after the simulation finishes.

Plotting from MATLAB

You can plot any of the data generated in MATLAB. In this tutorial, you will plot the ADAMS_uout data
that is saved in the adams_sub block. This block is shown in Figure 12.
30 Getting Started Using Adams Controls
Step Four - Simulating the Model

Figure 12 adams_sub Block

To plot from MATLAB:

 At the MATLAB prompt, type in the following command:
>>plot (ADAMS_tout, ADAMS_uout)
The plot window opens and shows the time history of input from MATLAB to Adams. The Figure 13
shows you how the plot should look. Notice that the control torque reaches a peak, and then settles
down as the antenna accelerates. As the antenna gets close to its final position, the torque reverses
direction to slow down the antenna. The antenna moves past its desired position, and then settles
down to the point of zero error. At this point, the torque value is also at zero.

To add labels to your plot:

 At the MATLAB prompt, enter:
 Learning Adams Controls with MATLAB Co-Simulation/Function Evaluation 31
Step Four - Simulating the Model

>>xlabel(‘Time in seconds’)
>>ylabel(‘Control Torque Input, N-mm’)
>>title(‘Adams Controls Torque Input from MATLAB to Adams’)
The labels appear on the plot.

Figure 13 Control Torque Input from MATLAB to Adams

Plotting from Adams View

To plot from Adams View:
1. Start Adams View from your working directory and read in the command file, ant_test.cmd.
2. From the File menu, select Import.
The File Selection dialog box appears.
3. In the File Selection dialog box, select the following:
• For the File Type, select Adams Results File.
• For Files to Read, select Read mytest.res.
32 Getting Started Using Adams Controls
Step Four - Simulating the Model

• For Model, select main_olt. Be sure to include the model name when you read in results files.
Adams View needs to associate the results data with a specific model.
4. Select OK.
The results are loaded. Now, you can plot any data from the cosimulation and play the animation.
5. From the Results tab, select Postprocessor.
Adams View launches Adams PostProcessor, a postprocessing tool that lets you view the results of the
simulations you performed (see the Figure 14). Adams PostProcessor has four modes: animation,
plotting, reports, and 3D plotting (only available with Adams Vibration data). Note that the page in
the plot/animation viewing area can contain up to six viewports to let you compare plots and
animations.

Figure 14 Adams PostProcessor Window

6. From the dashboard, set Source to Result Sets.

7. From the Simulation list, select mytest.
8. From the Result Set, select control_torque.
9. From the Component list, select Q.
10. Select Add Curves.
Adams PostProcessor generates the curve.

To add labels to your plot:

1. In the treeview, navigate to the plot and select it.
2. In the Property Editor that appears, perform the following:
 Learning Adams Controls with MATLAB Co-Simulation/Function Evaluation 33
Step Four - Simulating the Model

• Uncheck Auto Title.

• Set Title to Antenna Azimuth Control Torque in Adams.
• Uncheck Auto Subtitle.
• Set Subtitle to Using Matlab Continuous Controller.
3. Select the vertical axis.
4. In the Property Editor, in the Labels tab, set Label to Control Torque Input (N-mm).
Figure 15 illustrates the torque signal received from the MATLAB controller. The difference between
this curve and the one plotted in Figure 13 is because the number of output steps (Adams has fewer
outputs).

Figure 15 Adams Antenna Joint Peak Torque, Controlled

34 Getting Started Using Adams Controls
Step Four - Simulating the Model
 Learning Adams Controls with Control System Import from MATLAB 33
Overview

Learning Adams Controls with

Control System Import from MATLAB
Overview
This chapter teaches you how to generate external system libraries (ESL) from control systems designed in
MATLAB/Simulink and import them into Adams. It contains the following sections:
 Step Three – Setup MATLAB
 Step Four – Create Adams Target for Code Generation
 Step Five – Create Simulink Model
 Step Six – Code Generation of Control System
 Step Seven – Create GSE from the Simulink Model

About the Tutorial

This chapter provides the procedures to import control systems designed in MATLAB/Simulink into Adams.
It relies on MATLAB/Code Generation to convert the control model to C-code. This tutorial is based on the
files output from Adams View in the previous chapter.
The antenna model is still used in this chapter. The controller used in last chapter will be modified to
represent three different types of controllers: continuous, discrete, and hybrid (continuous/discrete). Those
three simulink files (continuous.mdl, discrete.mdl, and hybrid.mdl) are in the examples
directory. Copy them to the local directory.
If MATLAB/Simulink and Adams cannot be run on the same machine, you will have to perform additional
steps to realize the cross-platform control system import. For more information, refer to the online help.

Step Three – Setup MATLAB

First you will start MATLAB, and then you will create a simulink model for control system design. You will
use the antenna model files from the last section, plus several additional files.

To start MATLAB:
1. Start MATLAB in the same directory as the one the model and Simulink files reside.
2. Set up the MEX utility, if not already set up.
Enter mex -setup from the MATLAB command window, and then select the appropriate compiler.
(see http://www.mscsoftware.com/Support/Platform-Support/Default.aspx under Hardware & Software
Requirements for a list of supported compilers)
3. At the prompt (>>), type ant_test.
MATLAB displays:
34 Getting Started Using Adams Controls
Step Four – Create Adams Target for Code Generation

%%%INFO:Adams plant actuators names:

1 control_torque
%%%INFO:Adams plant sensors names:
1 rotor_velocity
2 azimuth_position.
4. At the prompt, type who to view the list of variables defined in the files.
MATLAB displays the following relevant information:

ADAMS_cwd ADAMS_inputs ADAMS_poutput ADAMS_sysdir

ADAMS_exec ADAMS_mode ADAMS_prefix ADAMS_uy_ids
ADAMS_host ADAMS_outputs ADAMS_solver_type
ADAMS_init ADAMS_pinput ADAMS_static

You can check any of the above variables by entering them at the MATLAB prompt. For example, if
you enter Adams_outputs, MATLAB displays all of the outputs defined for your mechanism. For
example:
ADAMS_outputs = rotor_velocity!azimuth_position

Step Four – Create Adams Target for Code Generation

In order to generate the external system library from the MATLAB/Simulink model, you need to generate
some special files for MATLAB/Code Generation. You will customize the makefile template and source code
template for Adams based on the version of MATLAB your are using. Once this is done, you can use the
customized template files for other Simulink models.

To create the Code Generation files for the Adams Controls model:
1. At the MATLAB prompt (>>), type setup_rtw_for_adams
This will automatically detect the version of Matlab you are using and create the makefile template
and source code template for Adams. This function will also build template for specific versions of
Matlab if desired by entering the desired version token as an argument:
setup_rtw_for_adams('<version')) For help with this, enter setup_rtw_for_adams('h').
You should see the following message for success in this step:
%%% Successfully created files for Adams library export from MATLAB/RTW.
You should also confirm that in your working directory that .tlc and .tmf files were created by
this step.
Alternatively, since the function setup_rtw_for_adams also uses process.py, you can still setup using
the old method:
(Optional method if not using setup_rtw_for_adams function)
1. Set the MATLAB_ROOT environment variable to the MATLAB installation directory. For
example:
 Learning Adams Controls with Control System Import from MATLAB 35
Step Five – Create Simulink Model

• On Windows (DOS shell): set MATLAB_ROOT= C:\ Progra~1\MATLAB\R2016b\

• On Linux (c shell): setenv MATLAB_ROOT /usr/local/MATLAB/R2016b/
• On Linux (korn shell): export MATLAB_ROOT = /usr/local/MATLAB/R2016b/
• Change the directory paths to match your installation.

2. In the directory where your Adams model resides, issue the following command, where $adams_dir
is the directory in which Adams is installed:
• On Linux:
adams2021_3 -c python ($adams_dir)/controls/utils/process.py -v 9.1 exit
• On Windows:
adams2021_3 python ($adams_dir)\controls\utils\process.py -v 9.1
Alternatively, you can copy the process.py file from the <adams_dir>/controls/utils/
directory on Linux or <adams_dir>\controls\utils\ on Windows to the current directory
and issue the following command:
• On Linux:
adams2021_3 -c python process.py -v 9.1 exit
• On Windows:
adams2021_3 python process.py -v 9.1
The argument -v 9.1 stands for MATLAB 9.1 (R2016b).
This command customizes several files from the MATLAB installation for the Adams target and
your computer setup. You should notice several new files in your working directory with a .tlc
extension and two new files with a .tmf extension. These are files required by MATLAB’s Real
Time Workshop in the steps that follow. For help with process.py, use the -h flag (that is,
process.py -h).

Note: The value for MATLAB_ROOT should have no quote, no spaces (on Windows, get short
names with command dir /x), and a final slash on the path.

Step Five – Create Simulink Model

To create the Simulink template for the control system:
1. Enter setio at the MATLAB prompt.
MATLAB creates a template model with the inport(s) and outport(s) defined, as shown in Figure 16.
36 Getting Started Using Adams Controls
Step Five – Create Simulink Model

Figure 16 Simulink Template

Based on this template, you can design continuous, discrete, or hybrid control systems. For this
tutorial, this step is information only. Since you already have these files copied into the local directory,
you can delete this "io" model and use one of the examples.
2. To open hybrid.mdl, from the File menu, select Open. Or, double-click the file in the file browser.
Optionally, you may also open discrete.mdl and/or continuous.mdl and run the rest of the tutorial
with those for comparison.
In the following context, the hybrid control system will be used as the example to illustrate the
process. The Figure 17 shows the hybrid system and Table 1 shows the topology.
 Learning Adams Controls with Control System Import from MATLAB 37
Step Five – Create Simulink Model

Figure 17 Hybrid Control System

Table 1 Hybrid Control System Topology

Quantity Library Block Type

1 Sources Step
2 Continuous Transfer Function
2 Discrete Transfer Function
5 Math Ops Sum
1 Math Ops Gain
2 Ports Import
1 Ports Outport

Step Parameters Continuous Transfer Function Parameters

38 Getting Started Using Adams Controls
Step Six – Code Generation of Control System

Step Time: 0.001 1 Numerator: [1040]

Initial Value: 0 Denominator: [0.001 1]
Final value: 0.3 Absolute tolerance: auto
Sample time: 0.01 2 Numerator: [950]
[X] Interpret vector parameters as 1-D Denominator: [0.001 1]
[X] Enable zero crossing detection (greyed out) Absolute tolerance: auto
Discrete Transfer Function Parameters Sum Parameters
1 Numerator: [657.4] 1 SumP
Denominator: [1 -.3679] Icon shape: rectangular
Sample time: 0.001 List of signs: +-
2 Numerator: [600 5] [ ] Show additional parameters
Denominator: [1 -.3679] 2 SumV
Sample time: 0.001 Icon shape: rectangular
Gain List of signs: +-
Gain: 0.5 [ ] Show additional parameters
Multiplication: Element-wise(K, *u) 3 SumP1
[ ] Show additional parameters Icon shape: rectangular
Import List of signs: +-
Name: rotor_velocity [ ] Show additional parameters
Port number: 1 4 SumV1
Name: azimuth_position Icon shape: rectangular
Port number: 2 List of signs: +-
Outport [ ] Show additional parameters
Name: control_torque 5 Icon shape: Round
Port number: 1 List of signs: ++
[ ] Show additional parameters

Step Six – Code Generation of Control System

First you will configure MATLAB/Code Generation and then you will create the external system library from
the Simulink model.
Given a controller designed with the appropriately designated inports and outports, the following steps are
required to export the model using Code Generation.
1. From the Code menu, point to C/C++ Code, and then select Code Generation Options.
The Configuration Parameters dialog box appears.
 Learning Adams Controls with Control System Import from MATLAB 39
Step Six – Code Generation of Control System

2. Verify that Generate code only is not selected.

3. Complete the Configuration Parameters dialog box for MATLAB, as shown Figure 18.

Figure 18 Configuration Parameters

4. From the treeview on the left side of the window, select Solver.
The dialog box displays the Solver options as shown in Figure 19
40 Getting Started Using Adams Controls
Step Six – Code Generation of Control System

Figure 19 Configuration Parameters - Solver Options

5. Set Solver options Type to Variable-Step. (If selecting Fixed-step solver, Set Mode to
SingleTasking.).
6. Under zero-crossing options, set Zero-crossing control to Disable All.

Note: Zero-crossing support is experimental in Adams Controls, and not available in

Adams Mechatronics. If you have zero-crossing in your model, and you would like
try to use them in Adams Controls, simply select Use local settings or Enable All to
turn them on, and Adams SENSOR's will be created via Controls System Import that
use the zero-crossings functions.

7. From the treeview on the left side of the window, select Optimization → Signals and Parameters.
The dialog box displays the Advanced options as shown in the Figure 20.
8. Set the Default parameter behavior to Inlined. Check the Inline Invariant Signals checkbox.
Enabling Inline parameters has the following effects:
• Code Generation uses the numerical values of model parameters, instead of their symbolic
names, in generated code.
 Learning Adams Controls with Control System Import from MATLAB 41
Step Six – Code Generation of Control System

• Reduces global RAM usage, because parameters are not declared in the global parameters
structure.

Figure 20 Configuration Parameters - Advanced Options

9. Select Apply.
10. Select the Code Generation tab.
11. To begin code generation and build the RTW library, select Code → C/C++ Code → Build Model.
Messages will appear in the MATLAB command window indicating successful code generation and
library creation. You should see messages that end with the following:
Creating library ..\hybrid.lib and object ..\hybrid.exp
*** Created ADAMS dll
C:\adams_controls_getting_started\antenna\hybrid_rsim_rtw>exit /B 0
### Successful completion of Code Generation build procedure for model:
hybrid
The library you created will be in your working directory.
42 Getting Started Using Adams Controls
Step Seven – Create GSE from the Simulink Model

Step Seven – Create GSE from the Simulink Model

First you will start Adams View and import the command file, and then simulate your Adams model
containing the GSE for the control system.

To start Adams View and load the command file:

1. Launch Adams View and import the file ant_test.cmd.
2. Load the Adams Controls plugin, if not already loaded.
3. From the Plugins tab, click on the Controls container, point to Control System, and then select
Import.
The Adams Controls System Import dialog box appears.
4. Select Import I/O Signals from Existing Controls Plant.
5. From the Database Navigator, select ant_test for the plant. The values for the Output Signals and
Input Signals text boxes appear.
6. Complete the dialog box as shown in Figure 21, and then select OK.

Figure 21 Adams Controls System Import Dialog Box

Adams View displays information on the GSE created (See Figure 22). The Database Navigator shown
in Figure 23 shows the GSE and its associated arrays.
 Learning Adams Controls with Control System Import from MATLAB 43
Step Seven – Create GSE from the Simulink Model

Figure 22 Information Window

Figure 23 Database Navigator

To simulate your model:

1. From the Settings menu, point to Solver, and then select Dynamics.
The Solver Setting dialog box displays.
2. Change Formulation to SI2.
3. Set Category to Executable.
4. Set Hold License to No.
44 Getting Started Using Adams Controls
Step Seven – Create GSE from the Simulink Model

This setting is critical to using the RTW dll in repeated simulations in Adams View.
When you rewind/stop a simulation in Adams View, the RTW dll is released and reacquired, thereby
resetting the discrete states and counters to their original state. Changing this behavior by issuing
commands in Adams View causes unexpected simulations after the first one.
5. Select Close.
6. Run a simulation with a step size of .001s and duration of .25s.
During the simulation, the antenna motion behaves the same as the one in the co-simulation.
7. Press F8 to open Adams PostProcessor.
8. Plot and animate, as desired.
Adams PostProcessor displays the plot of azimuth position versus time, as shown in below figure.

Figure 24 Plot of Azimuth Position vs. Time

 Learning Adams Controls with Control System Import from MATLAB 45
Step Seven – Create GSE from the Simulink Model

A comparison of the results of the above simulation, Co-simulation, and Function Evaluation
simulation is conducted (the latter two not performed in this tutorial). In all cases, the output step
(sampling time in discrete simulation) is set to .01 second. The control torque versus time from three
simulations is plotted in Figure 25. As shown, the result from the simulation with imported GSE is
almost the same as that from Function Evaluation simulation. The control torque from the Co-
simulation is slightly larger in magnitude because the one-step delay introduced by the discrete
control system results in a control-mechanical system with less damping.
Your RTW dll can contain discrete states and counters. When performing repeated simulations (for
example, design of experiments or design optimization), these entities need to be reset to their original
values at the beginning of each simulation. When you rewind a simulation in Adams View, the RTW
dll is released and reacquired, thereby resetting the discrete states and counters to their original state.
Changing this behavior by issuing commands in Adams View causes unexpected simulations after the
first one.

Figure 25 Control Torque vs. Time

Optionally, if you repeat the tutorial to create ESL's for discrete and continuous models, and re-run,
you should see a plot like Figure 26. Note that the step excitation is slightly different for each model,
and delays are caused by discrete states, so you should see differences in the responses accordingly.
46 Getting Started Using Adams Controls
Step Seven – Create GSE from the Simulink Model

Figure 26 Re-run Result

 Learning Adams Controls with Control System Import from MATLAB with S-Functions 47
Overview

Learning Adams Controls with

Control System Import from MATLAB
with S-Functions
Overview
This chapter teaches you how to use Adams Controls with Control System Import from MATLAB with S-
Functions. It contains the following sections:
 Step Three - Generate S-Function Using Code Generation
 Step Four - Use S-Function to Create Adams External System Library
 Step Five - Use S-Function without source code to Create ESL
 Step Six - Expose S-Function Parameters to Adams
 Step Seven - Use the S-Function ESL in Adams Control System Import

Step Three - Generate S-Function Using Code

Generation

Setup MATLAB
First you will start MATLAB, and then you will create a Simulink model for control system design. You will
use the antenna model files from the last section, plus several additional files.

To start MATLAB:
1. Start MATLAB in the same directory as the one the model and Simulink files reside.
2. Set up the MEX utility, if not already set up.
Enter mex -setup from the MATLAB command window, and then select the appropriate compiler.
(see http://www.mscsoftware.com/Support/Platform-Support/Default.aspx under Hardware & Software
Requirements for a list of supported compilers)
3. At the prompt (>>), type ant_test.
MATLAB displays:
%%%INFO:Adams plant actuators names:
1 control_torque
%%%INFO:Adams plant sensors names:
1 rotor_velocity
2 azimuth_position.
4. At the prompt, type who to view the list of variables defined in the files.
MATLAB displays the following relevant information:
48 Getting Started Using Adams Controls
Step Three - Generate S-Function Using Code Generation

ADAMS_cwd ADAMS_inputs ADAMS_poutput ADAMS_sysdir

ADAMS_exec ADAMS_mode ADAMS_prefix ADAMS_uy_ids
ADAMS_host ADAMS_outputs ADAMS_solver_type
ADAMS_init ADAMS_pinput ADAMS_static

You can check any of the above variables by entering them at the MATLAB prompt. For example, if
you enter Adams_outputs, MATLAB displays all of the outputs defined for your mechanism. For
example:
ADAMS_outputs = rotor_velocity!azimuth_position

Create Simulink Model

The purpose of these steps is to generate a model that is to be used for creation of the S-Function using the
S-Function target in Code Generation. The models supported by Adams Controls are firstly limited by those
restrictions enforced by MATLAB/Code Generation itself. Please consult the Mathworks documentation for
the official limitations, but a summary of these can be found in the Limitations section. In addition, Adams
Controls has its own limitations for S-Functions support for ESL creation/use, also listed.
For this example, you can simply open the Simulink model discrete.mdl, shown in Figure 27:

Figure 27 Discrete model

 Learning Adams Controls with Control System Import from MATLAB with S-Functions 49
Step Three - Generate S-Function Using Code Generation

To create the Simulink template for the control system:

1. Enter setio at the MATLAB prompt.
MATLAB creates a template model with the inport(s) and outport(s) defined, as shown in Figure 28.

Figure 28 Simulink Template

You can discard this model using the finished discrete.mdl.

Generate S-Function from RTW

Once the Simulink model is created, you will convert this to an S-Function using Code Generation. To do
this, the model must be configured properly.
1. In the model discrete.mdl, select Code → C/C++ Code → Code Generation Options.
2. From the treeview on the left side of the window, select Solver.
The dialog box displays the Solver options as shown in Figure 29.
50 Getting Started Using Adams Controls
Step Three - Generate S-Function Using Code Generation

Figure 29 Configuration Parameters

3. Here, under Solver options, Type, select Variable-Step. Any variable-step solver will be fine at this
point (for example, ode45), as long as you don't choose a discrete solver for a model with continuous
states.

Note: You can choose either Variable-step or Fixed-step solvers in MATLAB/Simulink. The
choice will affect the model code that is generated from RTW, in particular to how
sample times are handled. This is important to Adams since Adams will be integrating
the model, not MATLAB/RTW. In this regard, the Variable-step integrator is
recommended since Adams Solver uses mainly variable-step integrators, and this will
ensure the outputs and states are computed properly. If you would still like to use a
Fixed-step integrator setting, the model should have at least one continuous state to
produce the code for Adams that will handle the sample times properly. For example, if
you have a discrete-only model, add a dummy continuous block (for example, Integrator)
to the model.
 Learning Adams Controls with Control System Import from MATLAB with S-Functions 51
Step Three - Generate S-Function Using Code Generation

Tip: To look for differences in sample times between Fixed-Step and Variable-step integrators
settings, look for the function ssIsSampleHit(), which handles evaluation of code at
sample times.

As a MATLAB requirement, an RTW-generated S-Function must have the same type of integrator
setting as the model that will use it (that is, both Fixed-step, or both Variable-step).
4. Select Code → C/C++ Code → Code Generation Options. Under Target selection, select Browse
and choose the S-Function Target, rtwsfcn.tlc.

Figure 30 Discrete/Configuration

5. Select Apply to apply your changes, and then select Build to build the S-Function.
You should see messaging in the main MATLAB window about the build process, which should
conclude with this message upon a successful build (here, for 32-bit Windows; the extension will
depend on the platform):
### Created MEX-file discrete_sf.mexw32
In your working directory, you should find that RTW has created a directory called discrete_sfcn_rtw
containing the source files for generating your S-Function, discrete_sf.mexw32.
52 Getting Started Using Adams Controls
Step Three - Generate S-Function Using Code Generation

Figure 31 S-Function

6. Furthermore, you should see that RTW created an S-Function block which now supplants your
Simulink model (here discrete.mdl):

Figure 32 Function block

This is the block to be included in the Simulink model for the Adams External System Library.
 Learning Adams Controls with Control System Import from MATLAB with S-Functions 53
Step Four - Use S-Function to Create Adams External System Library

Step Four - Use S-Function to Create Adams External

System Library

Setup MATLAB
If you haven't already done so, open ant_test.m in MATLAB as described in the section Step Three - Generate
S-Function Using Code Generation. This will create variables required and modify the MATLAB path to
pickup setup scripts and functions.

Create Adams Target for RTW

Here you will customize the makefile template and source code template for Adams. Once this is done, you
can use the customized template files for other Simulink models.

To create the Code Generation files for the Adams Controls model:
1. At the MATLAB prompt (>>), type setup_rtw_for_adams
This will automatically detect the version of Matlab you are using and create the makefile template
and source code template for Adams. This function will also build template for specific versions of
Matlab if desired by entering the desired version token as an argument:
setup_rtw_for_adams('version') For help with this, enter
setup_rtw_for_adams('h').
2. You should see the following message for success in this step:
%%% Successfully created files for Adams library export from
MATLAB/RTW.
3. You should also confirm that in your working directory that .tlc and .tmf files were created by this
step.

Create Simulink Model

In this case, since the S-Function block created previously represents the Adams model with the same inputs
and outputs, we can use the setio command to generate the input/output template for this S-Function (which
will use the input/output information provided by ant_test.m).
1. Run setio.
54 Getting Started Using Adams Controls
Step Four - Use S-Function to Create Adams External System Library

2. Copy S-Function block to setio model, and connect the inputs appropriately.
3. Save as discrete_sf_mdl.mdl:

Code Generation of Control System

First you will configure MATLAB/Code Generation and then you will create the External System Library
from the Simulink model.
Given a controller designed with the appropriately designated inports and outports, the following steps are
required to export the model using RTW.
1. From the Code menu, point to C/C++ Code, and then select Code Generation Options.
The Configuration Parameters dialog box appears.
2. Verify that Generate code only is not selected.
3. Complete the Simulink Parameters dialog box for MATLAB by selecting the Rapid Simulation
Target in your working directory, as shown in Figure 33:
 Learning Adams Controls with Control System Import from MATLAB with S-Functions 55
Step Four - Use S-Function to Create Adams External System Library

Figure 33 Rapid Simulation Target

4. From the treeview on the left side of the window, select Solver.
The dialog box displays the Solver options as shown in Figure 34.
56 Getting Started Using Adams Controls
Step Four - Use S-Function to Create Adams External System Library

Figure 34 Configuration Parameters - Solver

5. Set Solver options Type to Variable-Step (it must be the same Type as specified when generating the
S-Function). (If selecting Fixed-step solver, Set Mode to SingleTasking.)
6. Under zero-crossing options, set Zero-crossing control to Disable All.

Note: Zero-crossing support is experimental in Adams Controls, and not available in Adams
Mechatronics. If you have zero-crossing in your model, and you would like try to use
them in Adams Controls, simply select Use local settings or Enable All to turn them on,
and Adams SENSOR's will be created via Controls System Import that use the zero-
crossings functions.

7. From the treeview on the left side of the window, select Optimization → Signals and Parameters.
The dialog box displays the Advanced options as shown in the figure below.
8. Verify that Default parameter behavior is set to Inlined. Check the Inline Invariant Signals
checkbox. Enabling Inline parameters has the following effects:
• Code Generation uses the numerical values of model parameters, instead of their symbolic names,
in generated code.
 Learning Adams Controls with Control System Import from MATLAB with S-Functions 57
Step Four - Use S-Function to Create Adams External System Library

• Reduces global RAM usage, because parameters are not declared in the global parameters
structure.

Figure 35 Configuration Parameters - Optimization

9. Select Apply
10. Select the Code Generation tab.
11. To begin code generation and build the RTW library, select Build.
Messages will appear in the MATLAB command window indicating successful code generation and
RTW library creation. You should see messages that end with the following:
Creating library ..\discrete_sf_mdl.lib and object...\
discrete_sf_mdl.exp
### Created Adams External System Library discrete_sf_mdl.dll

C:\adams_temp\sfunction\discrete_sf_mdl_rsim_rtw>exit /B 0
### Successful completion of Code Generation build procedure for
model: discrete_sf_mdl
The library you created will be in your working directory.
58 Getting Started Using Adams Controls
Step Five - Use S-Function without source code to Create ESL

Step Five - Use S-Function without source code to

Create ESL
Another way to generate an ESL using an S-Function is to exclude the source code for the S-Function to
protect proprietary information. Here, we will copy some main files and generate a duplicate model to show
that this should produce the same results as if the source code is available. These next steps assume that you
have performed the all steps previously. You may omit this portion of the tutorial and skip to parameterization
next, if desired.

Create Simulink Model

1. Create a directory within your working directory called "no_source_code" and copy the following files:
• ant_test.adm
• ant_test.cmd
• ant_test.m
• discrete.mdl

2. Restart MATLAB in this directory.

3. Build the S-Function in RTW from discrete.mdl using S-Function target in the same manner as in
previous Generate S-Function from RTW:
a. Open discrete.mdl
b. Build with RTW using the S-Function target.
 Learning Adams Controls with Control System Import from MATLAB with S-Functions 59
Step Five - Use S-Function without source code to Create ESL

4. Save this model as discrete_sf_mdl.mdl.

Code Generation of Control System

1. As described in the previous section, load ant_test.m in MATLAB and use Adams Controls
setup_rtw_for_adams script to generate Adams Controls-modified RSIM target.
2. Modify model with S-Function to choose RSIM target and build the S-Function again - this will
create an object file that can be used in later steps to build the Adams Controls ESL from RTW.

3. Provide the following when distributing the model to the person who will make the Adams Controls
ESL from RTW:
discrete_sf.mexw32
discrete_sf.h
discrete_sfcn_rtw/discrete_sf.h
discrete_sfcn_rtw/discrete_mid.h
discrete_sfcn_rtw/discrete_sid.h
discrete_sfcn_rtw/discrete_sf_private.h
discrete_sfcn_rtw/discrete_sf_types.h
discrete_sfcn_rtw/discrete.mk
discrete_sfcn_rtw/discrete_sf_data.c (if applicable)
discrete_sf_mdl_rsim_rtw/discrete_sf.obj
discrete_sf_mdl.mdl
4. To mimic what you would see at the receiver's end, first create a new directory called new_model.
Then, using the files from Step 3, retain the directory structure and copy all of these files to
new_model.
5. Also, move the files ant_test.m, ant_test.adm, and ant_test.cmd to the directory new_model.
6. Run ant_test.m in Matlab.
7. Open discrete_sf_mdl.mdl, and run setio to create the inputs and outputs for this model. Copy the
inports and outports to discrete_sf_mdl.mdl so it looks like in Figure 36:
60 Getting Started Using Adams Controls
Step Five - Use S-Function without source code to Create ESL

Figure 36 Discrete S-Fucntion - No Source

8. Rename the model to discrete_sf_no_source.mdl.

9. Run setup_rtw_for_adams to generate the RSIM target files in the folder new_model.
10. Choose Code → C/C++ Code→ Code Generation Options, and select the RSIM target for the
System Target File.
11. Select Generate code only to make the proper directory needed for the build. We will copy the S-
Function object file created previously to the RTW directory created by this process.
 Learning Adams Controls with Control System Import from MATLAB with S-Functions 61
Step Five - Use S-Function without source code to Create ESL

12. Select Apply and then click Generate code. You should see a directory called
discrete_sf_no_source_rsim_rtw in the working directory, as below:

13. Place the S-Function object file created previously ("discrete_sf_mdl_rsim_rtw/discrete_sf.obj") in the
directory of the new model's name ("discrete_sf_no_source_rsim_rtw/discrete_sf.obj").
14. In Configuration Parameters, uncheck the Generate code only option under the Code Generation
tab, and then select Apply:
62 Getting Started Using Adams Controls
Step Five - Use S-Function without source code to Create ESL

15. Select Build to build the ESL using the Adams Controls-modified RSIM target.
You should see the following messaging in the MATLAB window:
### Created Adams External System Library
discrete_sf_no_source.dll

C:\adams_temp\sfunction\no_source_code\new_model\discrete_sf_no_
source_rsim_rtw>exit /B 0

### Successful completion of Code Generation build procedure for

model: discrete_sf_no_source

Note: If you see a RTW message that it is compiling discrete_sf.c, then you have not performed
the steps properly, as it should not have a discrete_sf.c provided.

16. To use this ESL in Adams, See the section Step Seven - Use the S-Function ESL in Adams Control System
Import.
 Learning Adams Controls with Control System Import from MATLAB with S-Functions 63
Step Six - Expose S-Function Parameters to Adams

Note: The main RTW details can be found also written for another example here:

 How do I build my model that contains an RTW generated S-function block if I do

not have the source code?
http://www.mathworks.com/support/solutions/data/1-4JEC1P.html?solution=1-4JEC1P
 How do I build my model containing a C-MEX S-function if I don't have the S-
function C source file using Code Generation?
http://www.mathworks.com/support/solutions/data/1-3JK8LD.html?solution=1-3JK8LD

Step Six - Expose S-Function Parameters to Adams

This section shows how to parameterize your S-Function such that you may be able to automatically create
design variables for these parameters in Adams. This section is optional and may be omitted if you do not
need to parameterize your S-Function.

Select Parameters
To parameterize an S-Function for Adams, when building the S-Function block using an S-Function target,
first create parameters for the Simulink model.
1. Here we will create parameters "Kp1" and "Kp2" to parameterize the gain of the two transfer
functions:
64 Getting Started Using Adams Controls
Step Six - Expose S-Function Parameters to Adams
 Learning Adams Controls with Control System Import from MATLAB with S-Functions 65
Step Six - Expose S-Function Parameters to Adams

2. Note that you must remove the square brackets [ ] to parameterize this field. The model should now
look like the following:
66 Getting Started Using Adams Controls
Step Six - Expose S-Function Parameters to Adams

3. Here, we will set the values of the parameters to what they were originally:
>> Kp1=657.4
Kp1 =
657.4000
>> Kp2 = 600.5
Kp2 =
600.5000

Code Generation of Control System

1. Build the S-Function using the S-Function target in RTW and choose the parameters to be Global
(tunable) Parameters.
2. Select Code → C/C++ Code → Code Generation Options, select the Optimization → Signals and
Parameters tab on the left side, and set the Default parameter behavior to Tunable:

3. Select Configure. This will allow you to select Kp1 and Kp2 add them to the list of Global (tunable)
parameters. Do this as below:
 Learning Adams Controls with Control System Import from MATLAB with S-Functions 67
Step Six - Expose S-Function Parameters to Adams

4. Choose the Code Generation tab in the Configuration parameters:

68 Getting Started Using Adams Controls
Step Six - Expose S-Function Parameters to Adams

5. Under Configuration Parameters, select the Code Generation tab, and select the S-Function Target
for the System Target File.
6. Select Apply and then Build. This should create the file discrete_sf_data.c which will contain the
parameters selected:
/* Block parameters (auto storage) */
Parameters_discrete discrete_DefaultParameters = {
6.574E+002,
/* Kp1 : '<Root>/Discrete Transfer Fcn' */
600.5
/* Kp2 : '<Root>/Discrete Transfer Fcn1' */};
7. As in the section, "Step Four - Use S-Function to Create Adams External System Library", create a
new model based on your S-Function block, which now has the parameter exposed within it.
In the following steps, you will build the ESL using the Adams Controls-modified RSIM target and
again choose the same parameters to be Global (tunable) Parameters.
8. In model with S-Function, select Kp1 and Kp2 as Global (tunable) parameters again:
 Learning Adams Controls with Control System Import from MATLAB with S-Functions 69
Step Six - Expose S-Function Parameters to Adams

9. Under Configuration Parameters, select the Code Generation tab, and select the Adams Controls-
modified RSIM target for the System Target File.
70 Getting Started Using Adams Controls
Step Six - Expose S-Function Parameters to Adams

10. Select Apply and then Build. This should create the file discrete_sf_mdl_data.c which will contain the
parameters selected (as well as their size (here: 1x1):
/* Block parameters (auto storage) */
Parameters rtP = {
/* RTWSFunction_P1_Size : '<Root>/RTW S-Function' */
{ 1.0, 1.0 }, 6.574E+002,
/* Kp1 : '<Root>/RTW S-Function'*/
/* RTWSFunction_P2_Size : '<Root>/RTW S-Function'*/
{ 1.0, 1.0 }, 600.5
/* Kp2 : '<Root>/RTW S-Function'*/
};
Following the steps in the section, Step Seven - Use the S-Function ESL in Adams Control System Import,
you can use Control System Import to load the ESL:
 Learning Adams Controls with Control System Import from MATLAB with S-Functions 71
Step Six - Expose S-Function Parameters to Adams

Create GSE from the Simulink Model

1. After loading the ESL, Adams Controls will show these variables in the Adams Information window:
Object Name : .main_olt.discrete_sf_gse.RTWSFunction_P1_Size_1_1
Object Type : Variable
Parent Type : General_State_Equation
Real Value(s) : 1.0 NO UNITS
Units : no_units

Comment String : None

Object Name : .main_olt.discrete_sf_gse.RTWSFunction_P1_Size_1_2

Object Type : Variable
Parent Type : General_State_Equation
Real Value(s) : 1.0 NO UNITS
Units : no_units

Comment String : None

Object Name : .main_olt.discrete_sf_gse.Kp1

Object Type : Variable
Parent Type : General_State_Equation
Real Value(s) : 657.4 NO UNITS
Units : no_units

Comment String : None

Object Name : .main_olt.discrete_sf_gse.RTWSFunction_P2_Size_1_1

72 Getting Started Using Adams Controls
Step Six - Expose S-Function Parameters to Adams

Object Type : Variable

Parent Type : General_State_Equation
Real Value(s) : 1.0 NO UNITS
Units : no_units

Comment String : None

Object Name : .main_olt.discrete_sf_gse.RTWSFunction_P2_Size_1_2

Object Type : Variable
Parent Type : General_State_Equation
Real Value(s) : 1.0 NO UNITS
Units : no_units

Comment String : None

Object Name : .main_olt.discrete_sf_gse.Kp2

Object Type : Variable
Parent Type : General_State_Equation
Real Value(s) : 600.5 NO UNITS
Units : no_units

Comment String : None

Note: The "size" parameters denote the size of the MATLAB array that stores the parameters.
You may ignore these values.

2. Run a simulation for 0.25 seconds, 250 steps with the default parameter settings.
3. Save this simulation as "baseline".
4. Select Tools → Table Editor to modify the parameters from your ESL.
 Learning Adams Controls with Control System Import from MATLAB with S-Functions 73
Step Six - Expose S-Function Parameters to Adams

5. Set Kp1 = 1000, as below:

6. Run another simulation for 0.25 seconds, 250 steps with the new parameter settings.
7. Save this simulation as "new".
74 Getting Started Using Adams Controls
Step Seven - Use the S-Function ESL in Adams Control System Import

8. Switch to PostProcessor and plot the azimuth position for the baseline vs. new results. You should
see something similar to the plot below:

Step Seven - Use the S-Function ESL in Adams Control

System Import
First you will start Adams View and import the command file, and then simulate your Adams model
containing the GSE for the control system.

To start Adams View and load the command file:

1. Launch Adams View and import the file ant_test.cmd.
2. Load the Adams Controls plugin, if not already loaded.
3. From the Plugins tab, click on Controls container, point to Control System, and then select Import.
The Adams Controls System Import dialog box appears.
4. Select Import I/O Signals from Existing Controls Plant.
5. From the Database Navigator, select ant_test for the plant. The values for the Output Signals and
Input Signals text boxes appear.
 Learning Adams Controls with Control System Import from MATLAB with S-Functions 75
Step Seven - Use the S-Function ESL in Adams Control System Import

6. Complete the dialog box as shown in Figure 37, and then select OK.

Figure 37 System Import

To simulate your model:

1. From the Settings menu, point to Solver, and then select Dynamics.
The Solver Setting dialog box displays.
2. Change Formulation to SI2.
3. Set Category to Executable.
4. Set Hold License to No.
This setting is critical to using the RTW dll in repeated simulations in Adams View.
When you rewind/stop a simulation in Adams View, the RTW dll is released and reacquired, thereby
resetting the discrete states and counters to their original state. Changing this behavior by issuing
commands in Adams View causes unexpected simulations after the first one.
5. Select Close.
6. Run a simulation with a step size of .001s and duration of .25s.
During the simulation, the antenna motion behaves the same as the one in the co-simulation.
7. Press F8 to open Adams PostProcessor.
8. Plot and animate, as desired.
Adams PostProcessor displays the plot of azimuth position versus time, as shown below:
76 Getting Started Using Adams Controls
Step Seven - Use the S-Function ESL in Adams Control System Import
 Learning Adams Controls with Easy5 Co-Simulation/Function Evaluation 77
Overview

Learning Adams Controls with Easy5

Co-Simulation/Function Evaluation
Overview
This chapter teaches you how to use Adams Controls with Easy5 in co-simulation. This chapter does not
include information on the basics of Easy5. For that information, refer to the appropriate Easy5
documentation.
It contains the following sections:
 About the Tutorial
 Step Three - Adding Controls to the Adams Block Diagram
 Step Four - Simulating the Model

Note: Before beginning this tutorial, you should have finished Introducing and Starting the Tutorials, and
have the Adams Extension for Easy5 installed (refer to the online help for more information).

About the Tutorial

This chapter provides procedures for using Adams Controls with Easy5 in co-simulation. It teaches you Steps
Three and Four of the four-step process of adding controls to an Adams model. You’ll learn how to:
 Add an Adams plant to your block diagram in the Easy5 simulation.
 Simulate an Adams model with a complex control system.
 Plot simulation results.

Step Three - Adding Controls to the Adams Block

Diagram
You will add controls to the Adams block diagrams by:
 Starting Easy5
 Creating the Adams Interface Block
 Initializing and Configuring the Adams Interface Block
 Constructing the Controls System Block Diagram
78 Getting Started Using Adams Controls
Step Three - Adding Controls to the Adams Block Diagram

Starting Easy5
To start Easy5:
 Start Easy5 on your system from the directory that contains the file with the antenna example. This
is the working directory that you created in Step One - Build the Adams Model.
The Easy5 main window appears.

Note: The next two sections describe how to create a new Adams Interface block, and how to
configure it to run different analyses. You should review these sections before proceeding to
Constructing the Controls System Block Diagram where you will actually create a model (or
load the existing example).

Creating the Adams Interface Block

You create the Adams interface block by defining its component parts in the Add Components dialog box.
After you define the component parts, you place the block in the work space area of the Easy5 main window.

To create the Adams interface block:

1. On left hand side of the Easy5 window, you should see a list of components (blocks) within Libraries
and Groups.
If it's not already displayed, type Ctrl+A, and the Add Components window appears.
 Learning Adams Controls with Easy5 Co-Simulation/Function Evaluation 79
Step Three - Adding Controls to the Adams Block Diagram

Figure 38 Add Components Window

2. Select a category for each of the component fields in the window.

• Under Library, select Extensions.
• Under Extension Groups, select MSC Software.
• Under MSC Software, select the Adams Mechanism block.
3. Move the cursor to the center of the Easy5 main window and click.
The Adams interface block appears. You build the controls block diagram by adding elements to this
block.

Figure 39 Adams Mechanism Block

80 Getting Started Using Adams Controls
Step Three - Adding Controls to the Adams Block Diagram

Initializing and Configuring the Adams Interface Block

To initialize the Adams interface block:
1. Double-click the Adams interface block.
The Component Data Table appears as shown in Figure 40.

Figure 40 Component Data Table

2. Select Select/Configure Adams model in the lower left corner of the Component Data Table.
The Adams Interface dialog box appears as shown in Figure 41.
 Learning Adams Controls with Easy5 Co-Simulation/Function Evaluation 81
Step Three - Adding Controls to the Adams Block Diagram

Figure 41 Adams Interface Dialog Box

3. Select ant_test.
4. Select Co-Simulation (Discrete).
Notes on the simulation options:
Options for Function Evaluation (1 and 2) are continuous simulation methods, integrating
completely within Easy5. Option for co-simulation (3) is a discrete simulation method where Easy5
integrates the Easy5 model, and Adams integrates the Adams model, exchanging data at a specified
communication interval.
82 Getting Started Using Adams Controls
Step Three - Adding Controls to the Adams Block Diagram

Regarding Feedthrough: Feedthrough refers to whether the inputs directly affect the outputs (for
example, forces directly affect accelerations), or not (for example, forces do not directly affect
positions, velocities). In other words, if you've linearized a nonlinear Adams model and represented
it as A, B, C, and D matrices and the matrix D is zero at all times, then there is no feed-through from
the input variables to the output variables. If the matrix D is not zero at all times, then there is feed-
through from the input variables to the output variables.
Options for Linear State Matrices (4 and 5) are linear methods that are solved completely within
Easy5.
For information on choosing a simulation method, see the online help.
5. Select Done.
The Adams Interface dialog box closes, and the Component Data Table now looks like in Figure 42:

Figure 42 Component Data Table for Cosimulation

Tip: For a description of the component inputs, outputs, and states, select the Info button
 Learning Adams Controls with Easy5 Co-Simulation/Function Evaluation 83
Step Three - Adding Controls to the Adams Block Diagram

Note: You configure the Adams block the first time by reading in an .inf file. This defines
the extension inputs, such as ADAMS_Animation_Mode, ADAMS_Solver, and so on.
Subsequent reconfigurations of the block by reading in a new .inf file do not
overwrite the existing setting. You can change the settings of the extension inputs at any
time by manually resetting them before closing the Adams block CDT using the OK
button.

6. In the Component Data Table, in the Inputs tab, enter a value for the following input modes:
• For ADAMS_Animation_Mode, enter 1 to define interactive mode as the animation mode. For
more details about animation modes, see the Adams Controls online help.
• For ADAMS_Output_Interval (output rate interval), enter .001.
• For Communication_Interval (communication rate interval between Adams and Easy5), enter
0.001. It should not be larger than the ADAMS_Output _Interval.

Note: The ADAMS_Output _Interval in the Component Data Table determines the rate at
which Adams Controls writes its result to file (and updates the animation, if in
interactive mode). It is the interval at which the result is written to file once. It has the
lower limit of Time Increment (see step 5), and works best if ADAMS_Output
_Interval is a multiple of Time Increment for integration. The same rule applies to the
Strip Chart output rate.

• Alternatively, if you select Option 1 in step 4, the Component Data Table appears as follows:
• In function evaluation mode, the communication interval option is not needed because the
integrators determine the communication interval.
• Leave Use_ADAMS_ICs at its default (1).
If the Use_ADAMS_ICs flag is set to 1, the model uses the Adams initial conditions.
If the flag is set to 0, the model relies on Easy5 to provide the initial conditions (for example,
starting a simulation from the end of the last run simulation, which is stored in Easy5).
• Set the parameters as shown in Figure 43.
84 Getting Started Using Adams Controls
Step Three - Adding Controls to the Adams Block Diagram

Figure 43 Component Data Table - Function Evaluation Mode

• Note the following in Figure 42 and Figure 43:

• ADAMS_Solver has a default value of 1, which uses the Adams Solver (FORTRAN) for
cosimulation or function evaluation. Setting this value to 2 allows you to use the Adams Solver
(C++).
• ADAMS_Communication_Mode has a default value of 1, which uses the pipes-based
communication protocol for communication between Easy5 and Adams. Setting this value to 2
specifies that TCP/IP-based communication be used between the two products. For more
information on TCP/IP-based communication, see TCP/IP Communication Mode in the
Adams Controls help. Setting this to 3, enables DIRECT mode communication. Click on
"Info" button in the Component Data Table to know more about this.

Constructing the Controls System Block Diagram

The completed block diagram is in the file, antenna.0.ezmf, in the examples directory. To save time, you
can read in this diagram instead of building it.

Note: Only one Adams block is allowed per Easy5 model.

 Learning Adams Controls with Easy5 Co-Simulation/Function Evaluation 85
Step Three - Adding Controls to the Adams Block Diagram

To construct the controls system block diagram:

1. Review the controls block diagram in Figure 44. Begin recreating the diagram with the blocks from the
Add Components menu.
2. Place the Step Function Generator block in the diagram first.
3. Click on the Step Function Generator block using the middle mouse button.
The Component Data Table appears.
4. Set the step time (TO_SF) to 0.01 and the step value (STP_SF) to 0.3, and then select OK.

Figure 44 Controls Block Diagram

5. Connect the input blocks by clicking once on the First Order Lag block and then on the Adams
Mechanism Block.
Easy5 labels this connection as S_Out_LA11.
6. Connect the output blocks in the diagram by clicking on the Adams Mechanism Block and then on
the Summing Junction block. Be sure to connect the azimuth+position output to the first Summing
Junction block (SJ) and the rotor_velocity output to the second Summing Junction block (SJ11).
7. Connect the Strip Chart to the Adams Mechanism Block.
Be sure to connect only the rotor_velocity output to the Strip Chart.
The rotor_velocity output corresponds to the rotor-velocity signal from the Adams Mechanism
Block.
86 Getting Started Using Adams Controls
Step Four - Simulating the Model

8. Click the Strip Chart using the middle mouse button to display the Component Data Table. Set the
sample period TAU to .001, and then select OK.

Note: You must edit the connection from the Adams Mechanism Block to the Strip Chart
because Easy5 automatically connects the state vector from the Adams block to the
display variable on the Strip Chart.

9. From the File menu, select Save As, and then enter a file name for your controls block diagram.
You have now created the controls block diagram.

Step Four - Simulating the Model

You’ll simulate your mechanical model and controls system by:
 Building the Executable
 Executing the Simulation
 Pausing and Stepping Through the Simulation
 Plotting from Easy5
 Plotting from Adams View

Building the Executable

You must build an executable for your model before you execute a simulation in Easy5.

To build the executable:

 In Easy5, from the Build menu, select Create Executable.
After a few moments, Easy5 displays the message, Executable has been created, at the bottom of the
main window.
You are now ready to execute the simulation.

Executing the Simulation

To execute the simulation from Easy5:
1. From the toolbar at the top of the Easy5 main window, point to Analysis, and then select Simulation.
The Simulation Data Form window appears.
2. Select the Plotting tab.
3. For plot variables, select Selected from the pull-down menu.
A Plot Specification Form appears where you define the variables that you want to plot after the
simulation.
 Learning Adams Controls with Easy5 Co-Simulation/Function Evaluation 87
Step Four - Simulating the Model

Note: If you are using the completed block diagram from the file, antenna.0.ezmf, which
was provided for you in the examples directory, you may find that the Plot
Specification Form opens with information that is unnecessary for this tutorial. After
removing this information, the Plot Specification Form should look like the shown in
Figure 45.
88 Getting Started Using Adams Controls
Step Four - Simulating the Model

Figure 45 Plot Specification Form

4. Select the variables that you want to plot for the simulation.
For this tutorial, you will select three variables: rotor_velocity, azimuth_position, and S_Out_ LA11.
a. Under Dependent Variables, select the Variable #1 field.
Select the icon next to the field. The Select Plot Variables select list appears.
b. Expand the AD component, and then double-click rotor_velocity to select it.
The rotor_velocity component now appears as Variable #1 to be plotted.
• Repeat this procedure for the second and third variable. For the second variable, select
azimuth_position, and for the third, select S_Out_ LA11 (the input to the Adams block
as indicated in Figure 44).
The finished Plot Specification Form should look like the one in Figure 46.

Figure 46 Plot Specification Form

5. Return to the General tab in the Simulation Data Form window, and then specify the following
simulation parameters:
 Learning Adams Controls with Easy5 Co-Simulation/Function Evaluation 89
Step Four - Simulating the Model

• For Start Time, enter 0.0.

• For Stop Time, enter .25.
• For Time Increment, enter .001.
• For Integration Method, enter BCS Gear.

6. Select the Play tool to begin the simulation.

For more information about the simulation settings, see the Easy5 manual.
A new Adams View window appears and the analysis begins on the model specified in the Adams
block. Adams View displays the analysis for you.

To run an interactive simulation:

1. As the simulation begins, arrange the windows so that you have a good vantage point to view the
antenna model.

Note: The Adams model is initialized to the current simulation time in Easy5.

2. Start and pause the simulation by selecting Continue and Break on the interactive plot window.
Adams View accepts the control inputs from Easy5 and integrates the Adams model in response to
them. At the same time, Adams provides the azimuthal position and rotor velocity information for
Easy5 to integrate the Simulink model. The simulation process creates a closed loop in which the
control inputs from Easy5 affect the Adams simulation, and the Adams outputs affect the control
input levels. See Figure 2 for an illustration of the closed-loop simulation process.

Pausing and Stepping Through the Simulation

The interactive capabilities of Adams Controls let you pause the simulation in Easy5 and monitor the graphic
results in Adams View. You can plot simulation results during pause mode.

To pause the simulation:

1. Select Break to pause the simulation at the next sample step.
You can use the interactive plot window (Figure 47) to pause the simulation, or you can single-step
through the simulation. If you select Step, the simulation steps through one sample step (.001
seconds) of the interactive Strip Chart.
90 Getting Started Using Adams Controls
Step Four - Simulating the Model

Figure 47 Interactive Plot Window

2. Now go back to Adams View. While the simulation is paused, you can change the orientation of the
model with the View Manipulation Strip in the Main menu. These tools help you to look at the model
from different vantage points.

Figure 48 View Manipulation Strip

3. Once you have finished reorienting the model, select Continue to continue the simulation.
Adams View closes automatically after the simulation finishes.

Plotting from Easy5

Easy5 automatically displays the Plot window after running a simulation. By default, Easy5 displays the plot
of the first variable you defined in the Plot Specification Form (see Figure 46). You can plot any data generated
 Learning Adams Controls with Easy5 Co-Simulation/Function Evaluation 91
Step Four - Simulating the Model

in Easy5 by selecting a variable from the Plot Selection Menu. In this tutorial, you’ll plot the curve for control
torque.

To plot from Easy5:

 From the Plotter window, point to Displays, and then select the variable, S2 LA11, which is the
control torque input to the Adams block from Easy5.
The Easy5 Plotter window displays the plot for control torque.
The Figure 49 shows how the plot should look. Notice that the control torque reaches a peak, and then
settles down as the antenna accelerates. As the antenna gets close to its final position, the torque
reverses direction to slow down the antenna. The antenna moves past its desired position, and then
settles down to the point of zero error. At this point, the torque value is also zero.

To add labels to the plot:

1. At the bottom of the Plot Selection Menu, select Edit Display.
The Display Specification Form appears.
2. Enter the following labels:
• In the Plot Title text box, enter Adams Controls Torque Input from Easy5 to Adams.
• In the x-axis text box, enter time in seconds.
• In the y-axis text box, enter Control Torque, Newton-mm.
The labels you entered appear on the plot as shown in below.
92 Getting Started Using Adams Controls
Step Four - Simulating the Model

Figure 49 Plot of Control Torque Input

Plotting from Adams View

To plot from Adams View:
1. Display Adams View in a new system window and read in the command file, ant_test.cmd.
2. From the File menu, select Import.
The File Selection dialog box appears.
3. Select the following:
• For File Type, select Adams Results File.
• For Files to Read, select ant_test.res.
• For Model, select main_olt.
When you read in results files, be sure to include the model name because Adams View needs to
associate the results data with a specific model.

Note: You can plot any data from the simulation and rerun the animation from Adams View.
 Learning Adams Controls with Easy5 Co-Simulation/Function Evaluation 93
Step Four - Simulating the Model

4. From the Results tab, select Postprocessor.

Adams View launches Adams PostProcessor, a postprocessing tool that lets you view the results of the
simulations you performed. Take a minute to familiarize yourself with Adams PostProcessor.
Figure 14 shows the Adams PostProcessor window
5. From the dashboard, set Source to Objects.
6. From the Model list, select .main_olt.
7. From the Filter list, select constraint.
8. From the Object list, select antenna_joint.
9. From the Characteristic list, select Element Torque.
10. From the Component list, select Y.
11. Select Add Curves.
Adams PostProcessor generates the curve.

To add labels to the plot:

1. In the treeview, navigate to the plot and select it.
2. In the Property Editor, in the Title text box, enter the name: Antenna Joint Peak Torque,
Controlled.
The plot title appears above the plot.
Figure 41 illustrates how the curve should look. The curve shows the torque in the antenna joint from
the azimuth control loop. You can use the information on the plot to help you determine how to
modify the control system of the antenna model. For example, you can reduce the load in the antenna
joint by decreasing the velocity gain of the azimuth controller at the expense of slowing the overall
response of the controller. This is the type of trade-off between the mechanism design and the control
design that you can analyze using Adams Controls.
94 Getting Started Using Adams Controls
Step Four - Simulating the Model

Figure 50 Adams Antenna Joint Peak Torque, Controlled

 Learning Adams Controls with Control System Import from Easy5 95
Overview

Learning Adams Controls with

Control System Import from Easy5
Overview
This chapter teaches you how to import external system models designed in Easy5 into an Adams model.
Importing an Easy5 model into Adams enables you to build, test, and refine your combined model using the
3D visualization and design features available in Adams View.
This feature is available only with Easy5 version 7.1 and later.
We assume that you:
 Read the previous chapter in this guide
 Know how to export Adams plant files
 Know how to use Adams Mechanism Blocks in Easy5
This chapter contains the following sections:
 Setting Up the Environment
 Step Three - Export Your Easy5 Model
 Step Four - Import the Exported Easy5 Model into Adams
 Step Five - Run a Simulation

This tutorial takes about 1 hour to complete.

About the Tutorial

In this chapter you will continue using the Easy5 model of the antenna controller that you used in the
previous Adams Controls tutorials.
We assume that you have Easy5 and Adams Controls installed on the same machine. For instructions on
using this feature when Adams and Easy5 are not installed on the same machine, see the Adams Knowledge
Base Article KB8015994. We assume that the Adams Controls extension has been installed in your version of
Easy5 (for more information about the Adams product installation, see the Adams Installation and
Operations Guide).

Setting Up the Environment

No setup is required for Easy5 on Linux or Linux platforms. However, on Windows, you need to set the
PATH environment variable or launch Adams from an Easy5 shell. Please see the Controls documentation
Adams Controls Overview → Using Easy5 for more details.
96 Getting Started Using Adams Controls
Step Three - Export Your Easy5 Model

Step Three - Export Your Easy5 Model

This section details the procedure to export an Easy5 model as an Adams External System Library.
An Adams External System Library is a binary file that can be loaded into Adams as a General System
Equation (GSE) element. In this form, the equations in the Easy5 model become equations of the Adams
model just as if you had entered them as run-time function expressions within Adams State Variable or
Differential Equation elements.

To create an Adams External System Library:

1. Launch Easy5, move to the directory where the Adams model files and Easy5 model files reside, and
open the Easy5 antenna controller model.

Figure 51 Antenna Control System

In the previous chapter, you configured the Adams component of the antenna controller model to
run in co-simulation mode. Because you want the controller to execute as a set of equations inside
Adams, you must reconfigure the Adams Mechanism component to be in function-evaluation mode.
Failure to reconfigure the Adams component may result in a model that does not behave correctly in
Adams. If you have already configured your Adams component to be in function-evaluation mode,
you may skip 2.
2. To reconfigure the Adams component:
a. Double-click the Adams Mechanism Block to open the Component Data Table (CDT) shown
in Figure 52.
 Learning Adams Controls with Control System Import from Easy5 97
Step Three - Export Your Easy5 Model

Figure 52 Component Data Table

b. Select Select/Configure Adams Model to open the Configure Adams block panel.
98 Getting Started Using Adams Controls
Step Three - Export Your Easy5 Model

Figure 53 Configure Adams Block Panel

c. Select ant_test as the exported Adams model and choose the first option for execution mode:
Function Evaluation (no feedthrough).
d. Close the panel by selecting Done.
The Component Data Table for the Adams Mechanism Block is updated as shown next.
 Learning Adams Controls with Control System Import from Easy5 99
Step Three - Export Your Easy5 Model

Figure 54 Component Data Table after Re-Configuration

e. Select OK to close the CDT for the Adams Mechanism component.

The updated Adams Mechanism Block now contains all the information necessary to interface
with Adams.

Note: The following Adams block inputs in the CDT are not relevant:
ADAMS_Animation_Mode, ADAMS_Output_Interval, and Use_Adams_ICs.

3. Create the Adams External System Library files:

a. From the Easy5 Build menu, point to Export Model as, and then select Adams External System
Library.
The Export Adams External Systems form appears.
b. Accept the settings in this form, and then select Export to start creating the library.
100 Getting Started Using Adams Controls
Step Four - Import the Exported Easy5 Model into Adams

Messages in the message line at the bottom of the Easy5 window show the progress of the library
build. After a successful build, you will have two new files in your working directory. The first file
is a binary demand-loaded library file (named antenna.dll on Windows, antenna.sl on
HP-UX11 workstations, or antenna.so on other Linux platforms). The second file (named
antenna.esl.ezanl) contains the parameter values and other information the Easy5 model
needs. If you need to move these files to another directory (for example, to make the Easy5 model
available to other Adams users), you must move the two files together or the exported Easy5 model
will not work.
c. Exit Easy5.

Step Four - Import the Exported Easy5 Model into

Adams
In this section, you import the exported Easy5 antenna controller model into the Adams antenna model.
1. Launch Adams View.
2. Import the Adams antenna model, ant_test.cmd: from the Adams View File menu, select Import.
3. From the Plugins tab, click on Controls container, point to Control System, and then select Control
System Import.
The Adams Control system Import Dialog box appears.
a. In the General State Equation Name text box, enter antenna_gse. You may use any name here
that has not already been used as an element name in your Adams model and is not an Adams
keyword.
b. Right-click the External System Library text box, and then select Browse.
c. Select the demand-load library file created in the previous step (named antenna.dll, antenna.sl,
or antenna.so depending on your platform).
d. Select Import I/O Signals from Existing Controls Plant to display the Database Navigator.
e. In the Database Navigator, select ant_test.
The output and input signal text boxes update automatically, as shown in Figure 55.
 Learning Adams Controls with Control System Import from Easy5 101
Step Four - Import the Exported Easy5 Model into Adams

Figure 55 Adams Controls System Import Panel

f. Select OK or Apply to import the model.

If there is a problem in the importing process, the Adams Message window will explain it. Correct
the problem and try importing again. When the import is successful, the Information window
appears as shown in Figure 56, containing details about the GSE element created in the Adams
model.
102 Getting Started Using Adams Controls
Step Four - Import the Exported Easy5 Model into Adams

Figure 56 Message indicating the Creation of GSE

4. When you have finished examining the Information window, select Close.
The Easy5 controls system has now been incorporated into your Adams model. Next you'll run a
simulation to see how it performs.
 Learning Adams Controls with Control System Import from Easy5 103
Step Five - Run a Simulation

Step Five - Run a Simulation

In this section, you will run a simulation of the antenna model containing the Easy5 controller.

To run the simulation:

1. From the Settings menu, point to Solver, and then select Dynamics.
The Solver Settings dialog box appears.
2. Change the Formulation setting to SI2.
This change is necessary because the SI2 formulation is better able to deal with the rapid value change.
In this model, the rapid change is associated with the STEP function in the Easy5 model.
3. Select Close.
4. Run a simulation with step size of 0.001 seconds and duration of 0.25 seconds.
During the simulation, the antenna moves the same as it did during the co-simulation in the
preceding chapter.
5. Switch to Adams PostProcessor and examine the results.
6. From the list of analysis results plot the azimuth_position versus time.
Adams PostProcessor displays the plot of azimuth position versus time, as shown in Figure 57.

Figure 57 Simulation Result: Azimuth Position versus Time

104 Getting Started Using Adams Controls
Step Five - Run a Simulation