MSC.ADAMS interface®
Version 4.2 – summer 2004
Copyright © IMAGINE S.A. 1995-2004
AMESim® is the registered trademark of IMAGINE S.A.
AMESet® is the registered trademark of IMAGINE S.A.
ADAMS, EASY5, MSC, MSC., MSC.ADAMS, MSC.EASY5, and all product names in
the MSC.ADAMS Product Line are trademarks or registered trademarks of
MSC.Software Corporation and/or its subsidiaries.
MATLAB and SIMULINK are registered trademarks of the Math Works, Inc.
Netscape and Netscape Navigator are registered trademarks of Netscape
Communications Corporation in the United States and other countries. Netscape’s logos
and Netscape product and service names are also trademarks of Netscape
Communications Corporation, which may be registered in other countries.
PostScript is a trademark of Adobe Systems Inc.
UNIX is a registered trademark in the United States and other countries exclusively
licensed by X / Open Company Ltd.
Windows, Windows NT, Windows 2000 and Windows XP are registered trademarks of
the Microsoft Corporation.
X windows is a trademark of the Massachusetts Institute of Technology.
All other product names are trademarks or registered trademarks of their respective
companies.
TABLE OF CONTENTS
Using AMESim MSC.ADAMS Interface................................................................2
1
Introduction..................................................................................................................2
2
Preliminaries ................................................................................................................4
3
4
2.1.
License requirements ........................................................................................4
2.2.
Compiler requirements .....................................................................................4
2.3.
Versions of MSC.ADAMS supported ..............................................................4
2.4.
Platforms supported ..........................................................................................5
2.5.
Setting up the environment ...............................................................................5
Importing MSC.ADAMS into AMESim .....................................................................7
3.1.
Antenna example ..............................................................................................9
3.2.
Preparing a MSC.ADAMS model for export to AMESim .............................10
3.3.
Importing the model in AMESim ...................................................................13
3.4.
Analyzing results in both software .................................................................18
Importing AMESim into MSC.ADAMS ...................................................................19
4.1.
Preparing an AMESim model for export to MSC.ADAMS ...........................19
4.2.
Importing the model in MSC.ADAMS...........................................................20
5
Co-simulation or Full Export? ...................................................................................24
6
Advanced use of the interface....................................................................................27
7
6.1.
How to setup interface with template-based MSC.ADAMS products............27
6.2.
Using more than one interface ........................................................................28
Advanced configuration of the interface....................................................................28
7.1.
2004
Configuration file............................................................................................28
Table of Contents
1//39
Using AMESim MSC.ADAMS Interface
1
Introduction
The AMESim MSC.ADAMS interface enables you to link an AMESim model with an
MSC.ADAMS multibody model of a mechanical structure. By coupling motion
simulation and system simulation, this interface improves the accuracy of your full system
simulation.
This interface is useful when hydraulic or pneumatic fluid power systems or other
AMESim systems interact with complex mechanical structures.
The interface is designed so that you can continue to use many of the AMESim facilities
while the model is running in MSC.ADAMS. In particular, you can change the parameters
of the AMESim model within AMESim in the normal way and monitor the results by
creating plots just as if you were producing a regular run.
Normally you will have AMESim and MSC.ADAMS running simultaneously so that you
can use the full facilities of both packages. Process illustration follows:
Construct the AMESim model with
import/export icon from/to MSC.ADAMS
Modify AMESim submodel parameters
Complete the MSC.ADAMS model and link
with AMESim part
Run the simulation
Examine AMESim submodel
results in AMESim
Examine MSC.ADAMS
system results in
MSC.ADAMS
When the process is finished, the user can change the AMESim model parameters within
AMESim, as well as the MSC.ADAMS parameters within MSC.ADAMS.
2004
Using AMESim MSC ADAMS Interface
2//39
Organization of this manual
This manual describes both the two-way full export interface (using MSC.ADAMS or
AMESim integrator exclusively for the full system) and the two-way co-simulation
interface (where both solvers are used, one of them being called by the other).
The main part of the manual deals with the standard interface and section 5 looks at the
differences between export and co-simulation.
The structure of this manual is the following:
• Section 1: Introduction, is the current section.
• Section 2: Preliminaries, describes how you must set your working environment so
that you can use the interface.
• Section 3: Importing MSC.ADAMS into AMESim, describes with a simple
example how to create an AMESim model and configure it to run in cooperation
with MSC.ADAMS.
• Section 4: Importing AMESim into MSC.ADAMS, describes how MSC.ADAMS
imports the AMESim model.
• Section 5: Co-simulation or Full Export? This describes the differences between
co-simulation interface and the export facility.
• Section 6: Tips on using the interface, gives some advice on efficient use of the
interface.
• Section 7: Advanced use of the interface and Section 8: Advanced configuration of
the interface, are useful for customized use of the interface (advanced users).
Sometimes a section of text is only valid for a UNIX or Linux environment, for such text,
the following presentation is used:
Using UNIX:
Description for Unix/Linux based environments.
Similarly, sometimes a section of text is only valid for a Windows environment, for such
text, the following presentation is used:
Using Windows:
Description for Windows based environments.
We assume that either the reader of this manual is already familiar with using AMESim
and MSC.ADAMS or an AMESim user and an MSC.ADAMS user will collaborate in
performing the task.
For new AMESim users we recommend that they at least do the tutorial examples in the
AMESim manual before attempting a combined simulation. Similarly, a new
MSC.ADAMS user should become familiar with using MSC.ADAMS before attempting a
combined simulation.
2004
Using AMESim MSC ADAMS Interface
3//39
2
Preliminaries
2.1.
License requirements
When the user is running coupled simulation from AMESim environment, an Adams
interface license is required in AMESim in combination with a classical AMESim
runtime license. In the MSC.ADAMS side the module Adams/Controls (A/Controls) is
needed.
When running simulation from MSC.ADAMS the user only needs Adams interface and
AMESim runtime licenses, A/Controls is unused.
2.2.
Compiler requirements
Using Unix:
You will need an ANSI C compiler.
Using Windows:
You must have Microsoft Visual C++.
If using the interface from MSC.ADAMS environment, a FORTRAN compiler is also
highly recommended1 in order to compile the AMESim system as an MSC.ADAMS
subroutine.
MSC.ADAMS 2003 software specifications are:
Intel and Intel-compatible PCs with Windows OS
Compaq Visual Fortran 6.6B
Intel and Intel-compatible PCs with Linux OS
Intel Fortran 7, GNU g77
Hewlett-Packard
f90 2.4.13
SGI
7.3.1.2m
IBM
XL Fortran 7.1
Sun Microsystems
6 update 1
2.3.
Versions of MSC.ADAMS supported
This manual applies to MSC.ADAMS 2003. The interface was developed using this
version and when using a mode that requires A/Controls (i.e. importing into AMESim)
we suggest that you use that version with following patches:
A/View 2003 Service Pack 1 APN-130-240
A/Solver 2003 Service Pack APN-130-252
A/Controls 2003 Service Pack APN-130-256
1
In section 7 you will see how to compile the AMESim system without a Fortran compiler.
2004
Using AMESim MSC ADAMS Interface
4//39
2.4.
Platforms supported
Windows, Sun, SGI and IBM.
2.5.
Setting up the environment
In order to use the AMESim MSC.ADAMS interface it is necessary to set an
environment variable that points to the MSC.ADAMS installation directory. If this is not
set, AMESim will not be able to find the files necessary to compile the system.
To find out if this environment variable is set, type the following line in a terminal
window:
Using Unix:
echo $AME_ADAMS_HOME
This should result in something like:
/opt/Adams2003
being printed on screen. If nothing is printed, or the message “AME_ADAMS_HOME:
Undefined variable” is displayed, you must set this variable. To do this you need to know
where MSC.ADAMS is installed. If your working environment is set up properly to run
MSC.ADAMS, type either:
which adams03 (if you are using C shell) or,
whence adams03 (for Korn shell - ksh or Bourne shell - sh) or,
type adams03 (for some versions of Bourne shells).
This will tell you the location of the command to start MSC.ADAMS e.g.
/opt/bin/adams03
Then type:
ls –l /opt/bin/adams03
This finds the link to MSC.ADAMS directory, it may give something like:
/opt/bin/adams03 à /opt/Adams2003/mdi*
Remove the last part from this pathname to get the value to set for
AME_ADAMS_HOME, in this case /opt/Adams2003. If you are using Unix C shell,
you can then set the environment variable as follows:
setenv AME_ADAMS_HOME /opt/Adams2003
This statement can also be added to your .cshrc file so that the environment variable is set
every time you login.
For Bourne or Korn shells the corresponding would be:
AME_ADAMS_HOME=/opt/Adams2003; export AME_ADAMS_HOME
Add these statements to your .profile file so that the environment variable is set every time
you login or add it to a script that launches AMESim.
2004
Using AMESim MSC ADAMS Interface
5//39
Using Windows:
echo %AME_ADAMS_HOME%
This should result in something like:
C:\ADAMS2003
being printed on screen. If the environment variable is not set, %AME_ADAMS_HOME% is
printed and you need to set the environment variable to point to the MSC.ADAMS
installation directory. This can be done from the Windows Control Panel.
If you want to use this interface from MSC.ADAMS side, you will need a Fortran
compiler as stated in section 2.2.
Using Windows:
In this case the file dfvars.bat must be copied in $AME. This file sets up the
environment to use Fortran libraries.
For Compaq Visual Fortran this file can be found here:
C:\Program Files\Microsoft Visual Studio\DF98\BIN
Copy this file in the AMESim installation directory.
Using Unix:
You need access to a Fortran compiler. To be certain that the compiler is installed, type
one of the following command in a terminal window.
For IBM type: xlf, for SGI type f77 and for Sun type f77.
If the command issues an error message, please contact your system administrator.
Finally in AMESim the $AME/libadams directory must be in the current path list.
2004
Using AMESim MSC ADAMS Interface
6//39
3
Importing MSC.ADAMS into AMESim
The recommended way of working is to first create independent sub-system models in
AMESim and MSC.ADAMS that have a very simple model of the other domain subsystem.
Thus if the end result of a simulation study is to investigate how an hydraulic actuator
system will work in a mechanical system it is often best to first model the hydraulic
system separately with a simplified model of the mechanical system using the mechanical
submodels available in AMESim. This would probably be a prescribed velocity and
displacement.
In parallel a separate model of the mechanical system would be built in MSC.ADAMS
with a simplified hydraulic system. This would probably be a prescribed force instead of
an actuator. The two sub-system models should then be verified thoroughly. As much
independent tuning of the sub-systems as possible should be done at this stage. When the
two separate models work properly, they can be integrated.
A good general rule is that the ports where the hydraulic and multi-body sub-systems are
connected will correspond to hydraulic linear actuator rods or the shafts of hydraulic
pumps, motors or rotary actuators.
It is not too difficult to think of exceptions but the overwhelming majority of applications
will satisfy this rule.
You will look at one simple system that uses this way of interfacing. The tutorial case is
the MSC.ADAMS tutorial example of the antenna. It is strongly recommended that you
reproduce this system.
There are four potential problems when using the interface:
•
units,
•
sign conventions,
•
implicit variables (when using AMESim from MSC.ADAMS) and,
•
numerical problems.
With reasonable care these can be avoided.
The problem of different units in MSC.ADAMS and AMESim often leads to the need for
the interfacing variables to be adjusted with some unit conversion factor.
What we mean by a sign convention is the significance of the sign of forces,
displacements and velocities in both AMESim and MSC.ADAMS. It is almost always
necessary to reverse the sign of displacements and velocities when they are imported into
AMESim if hydraulic jacks or hydraulic pumps, motors or rotary actuators are used.
Since the sign convention depends on the interfacing components and variables it is
necessary to use caution regarding the sign. This is another good reason for creating two
separate sub-system models. The single software simulation results will give good insight
into the system behavior and make any sign errors in the combined simulation apparent.
As explained in the AMESim manual, AMESim can solve two kinds of systems of
differential equations: ordinary differential equations (ODEs) and differential algebraic
equations (DAEs). The latter uses implicit variables. The interface between AMESim
and the General State Equation in MSC.ADAMS supports only ODEs. It is therefore
impossible to use any submodel in AMESim that uses implicit variables when exporting
the model into MSC.ADAMS. It may also be necessary to modify the AMESim model to
eliminate any implicit variables that may be created to resolve algebraic loops.
2004
Using AMESim MSC ADAMS Interface
7//39
When working from MSC.ADAMS, numerical problems arise due to the fact that the
interface uses the MSC.ADAMS integrator, which is tuned to work well with the
equations governing multi-body systems. The numerical characteristics of a fluid power
system are different. Another source of numerical problems is that an AMESim model
when run with the AMESim integrators can employ some special tricks to deal with
discontinuities. This is not possible when using the MSC.ADAMS integrator. In fact, the
documentation of the MSC.ADAMS GSE facility, states that the imported system of
ODEs must be continuous. It is therefore recommended to avoid hard discontinuities
completely in the AMESim model. By a hard discontinuity we mean that there are jump
changes in the values of state variables. Fortunately very few AMESim submodels
employ hard discontinuities. Avoid the following hydraulic actuator icons that have an
integral mass as the corresponding submodels employ hard discontinuities.
It is not impossible to use these submodels but if you do, make sure that the jack never
hits its end-stops. However, submodels associated with alternative icons employ elastic
end-stops, which do not have hard discontinuities. Hence it is preferable to use these.
USE THESE ICONS
NOT THESE
Similarly if you use the mechanical icon
, use MAS21 not MAS005.
Looking at the input and output requirements of these preferred submodels and at the
requirements of hydraulic pumps and motors, a second general rule becomes apparent.
The MSC.ADAMS model normally calculates position and velocity, (or angle and angular
velocity) and passes them to the AMESim model, which calculates the corresponding
force (or torque).
Again it is possible to think of exceptions but this rule is very useful.
In the same way when working from AMESim, numerical problems can arise when
importing a large MSC.ADAMS system. AMESim integrator is not designed to solve
such problems, and simulation times may rise significantly.
In these cases the co-simulation interface can be a solution if no workaround is found to
make the full import facility efficient.
2004
Using AMESim MSC ADAMS Interface
8//39
3.1.
Antenna example
As an example, you will use the MSC.ADAMS tutorial of the antenna controlled within
AMESim.
The final sketch in AMESim will look like:
Figure 1: Antenna sketch in AMESim
The example comes from A/Controls tutorials; you should copy the A/View command file
antenna.cmd from {ADAMS_DIR}/controls/examples/antenna into a working directory.
Then, open the file within A/view environment. Select the Edit 4 Deactivate entry. In
the window Database Navigator select azimuth_motion_csd.
Figure 2: Deactivate a motion in A/View
2004
Using AMESim MSC ADAMS Interface
9//39
3.2.
Preparing a MSC.ADAMS model for export to AMESim
In this case, AMESim is the master software, you will launch simulation from AMESim
and this one controls MSC.ADAMS simulation. There are two ways for exporting
MSC.ADAMS to AMESim:
•
Discrete export, or co-simulation mode, AMESim tells MSC.ADAMS to
supply its outputs at fixed intervals, MSC.ADAMS solves its system,
•
Continuous mode, AMESim get the complete system from MSC.ADAMS
and tries to integrate all equations, MSC.ADAMS acts then as a function
evaluator.
These modes require that you have a valid license for A/Controls.
The MSC.ADAMS side of the procedure is unchanged which ever mode you want to use.
It is only in AMESim that you make your choice.
Step 1: Create/Check exchanged variables.
In this step, you will check the definition of some state variables2. You will use them as
exchanged variables between the both software, for example for a hydraulic actuator
modeled in AMESim and acting on an MSC.ADAMS mechanical structure, these
variables should be something like a force, a position and a velocity. Indeed AMESim
needs position and velocity and computes a force.
Outputs from MSC.ADAMS, often velocity and position, are defined with
MSC.ADAMS intrinsic functions; AZ( ) for an angle measurement, WZ( ) for a rotational
velocity, DM( ) for a displacement magnitude.
2
Be careful the meaning of states variables is not the same in AMESim and in MSC.ADAMS. For the latter
these are simple variables defined by an algebraic equation whereas in AMESim these are the variables
integrated by the solver.
2004
Using AMESim MSC ADAMS Interface
10//39
Figure 3: Creating outputs in ADAMS
Be careful with units (accessible from Settings/Units… menu in A/View). It should be
compatible with what AMESim expects, if you do not want to change it in
MSC.ADAMS, do not forget to place a gain (conversion factor) in AMESim sketch
before inputting the signals into AMESim submodels.
Inputs to MSC.ADAMS, mainly forces/torques, are used in standard elements like single
component force/torque or general force (6 components). At creation, these variables are
set to zero value because the other software (AMESim) will compute their values.
In our example, the unique input variable is referenced in a torque single component using
the function VARVAL.
The element azimuth_actuator can be accessed from the Tools4Database Navigator…
menu in A/View. The control_torque state variable is accessible from Build4System
Elements4State Variables4Modify… menu.
Figure 4: Creating input variable in ADAMS
Once you have created input and outputs variables, in the next section you will learn how
to define the interface in MSC.ADAMS.
Step 2: Create the Interface.
Using the variables you have just created in the step before, use the existing Plant Input
and Plant Output.
Plant Input: {control_torque}, where the torque is used in a single component torque as
VARVAL(control_torque)
and,
2004
Using AMESim MSC ADAMS Interface
11//39
Plant Output: {rotor_velocity, azimuth_position}, where these variables are computed with
MSC.ADAMS functions.
Look at the screenshot below, you can access these windows by using the Database
Navigator… from Tools menu and by selecting the existing plants
Figure 5: Creating Interface component in MSC.ADAMS
The MSC.ADAMS model is now ready for export; in the next section, you will see how to
generate the files necessary to AMESim.
Step 3: Export the system.
You will export the coupled system; if A/Controls plugin is loaded (refer to
MSC.ADAMS documentation to do so), you have access to the Controls menu. There you
can do a Plant Export:
Figure 6: Exporting the coupled system from ADAMS
In this dialog box, you have to fill in:
2004
•
the name (File prefix) that MSC.ADAMS will use to store results files,
•
plant input and plant output created in step two,
•
Control package, choose EASY5_and_MATRIXx,
•
the Type of export, choose between linear and non_linear,
•
if you want MSC.ADAMS to compute an initial static analysis before
running the coupled system choose yes, otherwise choose no,
•
if needed a user defined library name.
Using AMESim MSC ADAMS Interface
12//39
This manipulation creates three files in your working directory, adams2amesim.inf ...adm
and …cmd. You will only focus on the adams2amesim.inf file, but here is a brief
description of the three files:
•
The inf file contains generic information for coupling with other software: the
path of MSC.ADAMS, names of files that MSC.ADAMS will write to, some
information needed by the solver, identities of exchanged variables, and
number of states3.
•
The adm file contains the MSC.ADAMS system readable by the
ADAMS/Solver, that one will be inputted to the solver when running the
simulation.
•
The cmd file also contains all the relevant system information but suitable for
ADAMS/View.
The MSC.ADAMS part of the process is now finished, in the next part you will focus on
AMESim.
3.3.
Importing the model in AMESim
In AMESim construct the simple sketch that will control the antenna model. Necessary
information is given on the sketch.
Save this system in the directory where you have exported MSC.ADAMS files (inf adm
and cmd).
Step 1: Import file generated by MSC.ADAMS.
Once you have created the main part of AMESim system, use the Interface menu to
import MSC.ADAMS model:
Figure 7: Importing MSC.ADAMS model in AMESim
3
The inf file also contains information that is not directly accessible under MSC.ADAMS: interactive or batch
simulation, discrete or continuous interface, step time for discrete mode, solver commands, initial conditions
analysis. These are defined by default in MSC.ADAMS settings (easily accessible under UNIX), most of them
will be accessible under AMESim but if you are an experienced user you can always edit this file.
2004
Using AMESim MSC ADAMS Interface
13//39
This opens a dialog box window in which you select the inf file generated during
MSC.ADAMS export.
Then the inf file is analyzed and you get following tabbed window:
Figure 8: MSC.ADAMS model import window in AMESim
The tabs are used as follows:
•
In the Common tab, number and names of inputs and outputs are
automatically set up following the content of MSC.ADAMS file. Check the
names of variables and give a title to the icon.
•
In the MSC.ADAMS tab, several settings are available:
o
Output prefix name: it is the name of output files of MSC.ADAMS,
o
User executable: eventually add there your user defined library path
needed by MSC.ADAMS model, it usually contains some
subroutines,
o
Simulation mode: Continuous stands for complete import of
MSC.ADAMS system into AMESim and Discrete for co-simulation
mode,
o
Animation mode: specify here if you want to launch A/View while
you run a simulation; namely the Interactive mode that is much
slower than the Batch one, in the last one you can always look the
animation of your model at the end of simulation,
o
MSC.ADAMS output step size: give here the period at which
MSC.ADAMS writes its results,
o
Initialization mode: an MSC.ADAMS option to say that you will do
an initial condition analysis if needed, this option is disabled,
o
Static analysis: same as previous but for an equilibrium analysis
before dynamic run,
o
Initialization commands: it contains ADAMS/Solver commands that
are in the inf file and should work only in Batch mode (Interactive
mode requires A/View commands) this field is not customizable, if
needed modify the inf file directly.
Upon completion of the sketch, you switch to Submodel mode and then Parameter mode.
AMESim compiles the system and you can now focus on parameters available for the
interface submodel.
2004
Using AMESim MSC ADAMS Interface
14//39
Step 2: Parameterization of the interface block.
Depending on the mode you selected in previous step, you have two possibilities. For the
discrete mode you get following parameters:
Figure 9: AMESim parameters for discrete MSC.ADAMS block
You have access to the communication interval; indeed, it is useful to test several values
for this parameter. We will return to this parameter in a later section concerning problems
of co-simulation.
If the block were a continuous one, you would get the following parameters:
Figure 10: AMESim parameters for continuous MSC.ADAMS block
2004
Using AMESim MSC ADAMS Interface
15//39
In this case, since AMESim imports the complete MSC.ADAMS system, it integrates all
states variables coming from MSC.ADAMS4. All these states become AMESim states
variables. Contrarily to other classical submodels you do not have access to initial values
of these states since MSC.ADAMS will compute these ones.
Step 3: Running a simulation.
Change to Simulation mode. Set normally the parameters of the simulation bearing in
mind that if you are using a discrete block and have a sample time step you should use at
most this value for the AMESim communication step.
When you run the simulation depending on the platform you are using, you will notice
that A/Solver is running:
Using Windows:
MSC.ADAMS opens a Command DOS Prompt and you see messages coming from
A/Solver. All the messages are saved in a text file (msg)
Figure 11: MSC.ADAMS command window
4
Actually, MSC.ADAMS converts its algebraic/differential system into a purely differential one and sends the
derivatives of its states to AMESim whenever we ask for it. The conversion methodology introduces
supplementary states and as a result, the states have no physical meaning.
2004
Using AMESim MSC ADAMS Interface
16//39
Using UNIX:
The output messages from A/Solver appear on the AMESim message window.
When running a co-simulation in discrete mode in AMESim the simulation gives an error
message concerning the standard output in Warning/Error tab. On Sun station:
dofio: [-1] end of file
logical unit 6, named ‘stdout’
lately: writing sequential formatted external IO
On Silicon Graphics station:
sfe: Resource temporarily unavailable
apparent state: unit 6 named
last format:
unit 6 is a (null) formatted external file
*** Execution terminated (11) ***
On IBM station:
1525-013: The sequential or stream WRITE statement
cannot be completed because an errno value of 11
(Resource temporarily unavailable) was received while
writing the file (standard output). The program will
stop
This is because MSC.ADAMS sends many messages to the standard output while
AMESim does some treatments on it and it seems that there is no way to avoid all these
messages. The workaround is to launch the simulation from a terminal window, e.g. if
your model is called model.ame in /home/usr/ametest do the following:
cd /home/usr/ametest
./model_
This will execute the model, output messages will appear in the terminal window.
2004
Using AMESim MSC ADAMS Interface
17//39
3.4.
Analyzing results in both software
Upon completion of the simulation, you can analyze the results in both packages. In
AMESim, you can get the variables values exchanged with MSC.ADAMS by clicking the
MSC.ADAMS block. You get the following results:
Figure 12: Results from the co-simulation in AMESim
In MSC.ADAMS, you have to load the results files into the model. To do so, in the File
menu, choose Import and select ADAMS/Solver Analysis (req, gra, res), select one on the
three files created during the simulation and do not forget to fill in the model name so as
to associate results with the model you are working with. You can then look at the
animation or plot any variable as usual within the A/Postprocessor:
Figure 13: MSC.ADAMS results for the co-simulation
2004
Using AMESim MSC ADAMS Interface
18//39
4
Importing AMESim into MSC.ADAMS
In this section you will focus on the other interface method i.e. importing the AMESim
model into MSC.ADAMS. We designed the facility for multiple reasons:
An MSC.ADAMS user needs to integrate a validated AMESim component into its
mechanical system; he can still work with MSC.ADAMS facilities while taking advantage
of AMESim ability to design multi-disciplinary control systems.
•
AMESim may sometimes encounter difficulties in solving a complex
MSC.ADAMS mechanical structure; in this case, we suggest that user tries
the other way for coupling the systems, especially if the AMESim system is
simple.
•
This methodology requires no supplementary license for A/controls product.
In this case, you will use AMESim subsystem in MSC.ADAMS as a general state
equation (GSE) block. MSC.ADAMS executable will communicate with AMESim using
a library. Actually, AMESim will not generate an executable as usual but rather a
dynamic link library (dll) on Windows platforms or a library (so) on UNIX platforms.
One advantage of this methodology is that you do not need to have AMESim installed on
the MSC.ADAMS machine; you will just need an AMESim runtime license.
4.1.
Preparing an AMESim model for export to MSC.ADAMS
In this section, you will see how to export an AMESim system into MSC.ADAMS.
In Sketch mode, construct your AMESim system with non-connected ports corresponding
to MSC.ADAMS inputs and outputs. Then, in the Interface menu, select Create export
icon…, refer to the screen capture below:
Figure 14: Creating export icon in AMESim
It opens a dialog box window named Interface Icon Creation, you select there a Type of
interface it should be Adams or AdamsCosim depending if you want to run discrete
coupling or continuous export.
2004
Using AMESim MSC ADAMS Interface
19//39
Set the number of input variables to MSC.ADAMS and output variables from
MSC.ADAMS and give them a name.
In the antenna case it should be one input and two outputs and the created icon looks like
this:
Figure 15: AMESim subsystem containing MSC.ADAMS block
It is also possible to change the interface status without having to re-do the export, just go
in the Interface menu and select Display interface status. There you can switch from
Adams to AdamsCosim.
Switch then to Submodel mode and Parameters mode, after the compilation of the system
AMESim creates the library. Switch to Simulation mode to generate all necessary files.
You are now ready to work under MSC.ADAMS and import the AMESim system; it is
the subject of next section.
4.2.
Importing the model in MSC.ADAMS
Step 1: Create the arrays for inputs outputs and states.
In A/View go into the Build4Controls Toolkit menu.
First, choose U input array. There you create inputs to AMESim subsystem, so it will be
a 2-dimensionnal array containing MSC.ADAMS variables for velocity and position.
Then, choose X states array. Depending on discrete or continuous export, you
respectively specify 1 (a dummy state variable) or AMESim number of states for the size
of the array (this number is accessible in Simulation mode when you press State Count
button
).
Finally, choose Y output array. It represents the outputs from AMESim so in our case it
will be a 1-dimension array for the control torque.
The figure presents a summary of these operations:
2004
Using AMESim MSC ADAMS Interface
20//39
Figure 16: MSC.ADAMS arrays for import of AMESim subsystems.
Step 2: Association of array output value to the model.
The control torque computed by AMESim needs to be associated to the MSC.ADAMS
model. You do it in the single component torque using ARYVAL MSC.ADAMS function.
This one permits you to get an array value.
Note that, as a first argument to this function you use the array of outputs and the second
argument is the position of wanted value; 1 in our case.
Figure 16: Associate AMESim output to the ADAMS model
2004
Using AMESim MSC ADAMS Interface
21//39
Step 3: Creating the GSE and linking with AMESim library.
In the Build4System Elements4General State Equation menu, choose New… this
opens the following dialog box window:
Figure 17: Creating a GSE in ADAMS; discrete or continuous
Fill in the window according to the previous figure. The States line corresponds to the
coupling method you have chosen previously under AMESim, choose discrete for a cosimulation and continuous for an export. User Function Parameters needs always three
parameters and corresponds respectively to the ID of U Array, Y Array and X Array.
AMESim will need them to be able to get correct values from MSC.ADAMS during
simulation. Once completed, you have to indicate to A/Solver to use the AMESim library.
Go in the Settings4Solver4Solver executable… menu, in the dialog box window for
Solver Library supply the AMESim library path as the below figure shows it:
Figure 18: A/Solver settings when using AMESim library
Step 4: Running a simulation.
Since A/Solver will use an external library only scripted simulation are available.
Follows an example of a simple script:
file/model=Adams
simulate/dynamics, end=0.250000, dtout=0.001
stop
Run the simulation within MSC.ADAMS, in the same time, the AMESim library writes a
result file.
2004
Using AMESim MSC ADAMS Interface
22//39
Figure 20: AMESim as a GSE in MSC.ADAMS
The AMESim model is executed in the background. The communication with
MSC.ADAMS takes place at the library level (dll on Windows and so on Unix platforms).
In the aside figure you can notice that AMESim outputs some messages during the
simulation.
Step 5: Checking the results.
If you have AMESim installed on the same machine, you can look at the results within
AMESim. Otherwise, you can focus on MSC.ADAMS results only.
Check the plots Figure 12: Results from the co-simulation in AMESim at page 18 and
Figure 13: MSC.ADAMS results for the co-simulation page 18.
2004
Using AMESim MSC ADAMS Interface
23//39
5
Co-simulation or Full Export?
When a full export is feasible it is always better than a co-simulation. Indeed having all
the system integrated by one solver makes the analysis of the system easier. For example
using the linear analysis facility in AMESim is more accurate if AMESim knows all
states of the system.
During a full export to MSC.ADAMS, AMESim is used as a function evaluator by
MSC.ADAMS. All derivatives and outputs are passed to MSC.ADAMS whenever it asks
for them. The AMESim solver is not used and values in MSC.ADAMS may be
discontinuous and may make the solver fail.
In the opposite case, during export to AMESim, MSC.ADAMS is used as a function
evaluator. MCS.ADAMS passes derivatives and outputs whenever AMESim needs it.
The precision of MSC.ADAMS values is essential for the success of AMESim integrator.
That is why it is necessary to set a special MSC.ADAMS parameter. In the inf file you
will have to add a command:
NUMBER OF COMMANDS
1
CPAPAR/ALA=1e-10, ALR=1e-10
If necessary you can raise these values to 1e-8.
This controls the coordinate partitioning algorithm for the ABAM (Adams-Bashforth and
Adams-Moulton) integrator. Coordinate partitioning is the action done in order to remove
the constraints of MSC.ADAMS system; from a set of DAEs it gets a set of ODEs that
AMESim can integrate.
A co-simulation can be easier to set-up, especially if the models are complex. During a
co-simulation both solvers exchange information at fixed interval. When MSC.ADAMS
receives a signal, this will stay constant during the whole sample interval, until a new
value is received. The same thing happens in AMESim. You will have to set this
communication interval with care since different values can lead to different results.
We want to use as large an interval as possible to get a quick run and as small as possible
for accurate values! Sampled environments are a difficult subject and there are books
written on the stability of them. How do we set up efficiently a communication interval
for discrete mode?
Keeping in mind that introducing a communication interval is more or less equivalent to
introducing a delay in the system, the following study can be done.
We consider a linear actuator modeled within AMESim and coupled with an
MSC.ADAMS model. In the figure you will notice that some variables are exchanged.
The torque is here always zero.
2004
Using AMESim MSC ADAMS Interface
24//39
Figure 21: AMESim sketch of a linear actuator coupled with MSC.ADAMS
An equivalent system is given above. A simple calculation will give the global inertia
which must be the one of the MSC.ADAMS structure on which AMESim force acts. You
can also include some friction if there is any in the MSC.ADAMS model.
In order to test the validity of a chosen communication interval we want to construct a
similar system in AMESim only.
Figure 22: AMESim sketch with a delay loop.
The sample period of the discrete delay blocks are set to the communication interval we
are testing.
Construct also in the same sketch the same system without the discrete blocks.
2004
Using AMESim MSC ADAMS Interface
25//39
With this sketch you can compare results of both systems, with and without discrete
blocks depending on the delay=communication interval you have chosen.
Figure 19: AMESim sketch without discrete blocks.
Run simulations with different delays (communication interval) and check that results on
both systems are equivalent. Choose the highest communication interval that preserves the
quality of the results.
With this methodology you are able to establish an optimal communication interval.
6
Tips on using the interface
6.1.
How to stop a simulation
Using Windows:
If you use AMESim to run the simulation and stop it for any reason, MSC.ADAMS
continues to run in the command window.
To stop the MSC.ADAMS simulation, click on this command window and type:
Ctrl C
2004
Using AMESim MSC ADAMS Interface
26//39
6.2.
How to execute MSC.ADAMS commands before a cosimulation?
You can edit the inf file and change the following lines:
NUMBER OF COMMANDS
0
Add any A/Solver command at this location, all these commands are executed in
MSC.ADAMS before launching the co-simulation, it can look like:
NUMBER OF COMMANDS
2
SIMULATE/STATICS
SIMULATE/INITIAL_CONDITIONS
7
Advanced use of the interface
7.1.
How
to setup interface
MSC.ADAMS products
with
template-based
Your MSC.ADAMS model may use functionalities of an MSC.ADAMS template-based
product. These products are:
•
ADAMS/Aircraft, ADAMS/Car, ADAMS/Car
ADAMS/Engine and ADAMS/Rail.
Ride,
ADAMS/Driveline,
If your model effectively uses one of these libraries, the import into AMESim requires an
additional step: editing the .inf file.
You always need A/Controls to setup the export in Adams (cf. Figure 6: Exporting the
coupled system from ADAMS, page 9). Once you have selected OK in the Plant export
dialog box, this will create the inf file. Then submit the analysis in a normal way, but
make sure that you choose files_only.
When you set Mode of Simulation to files_only, your template-based product only outputs
the analysis files, .adm and .acf, but it does not perform an analysis. In A/Car, you can use
this option to prepare files for use with A/Controls.
If you have loaded A/Controls (Tools4Plugins4Controls4Load), and your model has
a plant input and a plant output, A/Car will prepare a special _controls.acf file. It supports
a single plant input and output. If you have more than one plant input and output, A/Car
prompts you to select which one you want to see.
The next step to run a co-simulation is to edit the inf file, and make the following changes:
NUMBER OF COMMANDS
1
FILE/COMMAND= _controls.acf
Then MSC.ADAMS will execute the commands that are in the _controls.acf file before
running the co-simulation with AMESim.
2004
Using AMESim MSC ADAMS Interface
27//39
7.2.
Using more than one interface
If your AMESim model and your MSC.ADAMS models are coupled at different
locations, unify all exchanges variables and use only one Plant Input and one Plant Output
in MSC.ADAMS and one interface block in AMESim.
8
Advanced configuration of the interface
This section is useful only for advanced users; it permits you to customize the interface.
8.1.
Configuration file
This section applies only when exporting AMESim system to MSC.ADAMS.
It should be possible to do the tutorial example without any further changes to the
configuration of the interface.
The configuration files for the AMESim export to MSC.ADAMS supplied with a
standard AMESim installation assumes that all functions are written in C and that no
extra libraries with user written functions are needed. If you write your submodels in
Fortran or you use non-standard libraries in your model, some changes to the standard
distribution files are needed. Refer to the standard AMESim manual for these changes.
In a similar way it is possible to customize the AMESim MSC.ADAMS interface. The
files that involved are adams.conf and amesim_adams_gsec.make. They are stored in the
$AME/lib directory. For global customization, they should be edited there. If you do this,
the new configuration becomes the default for all users of the interface. Your system
administrator should normally do this.
It is also possible to alter the configuration locally so that the changes apply only to you
working in a particular directory. To do this copy these files (adams.conf and
amesim_adams_gsec.make) to your project directory and make the necessary changes to
these files.
AMESim looks in the current directory before looking in the standard area ($AME/lib),
any changes made to the local files will therefore override the global configuration.
The file adams.conf contains instructions specifying which files are to be used when
creating the AMESim part of the simulation model. This means that if you decide to
make any local configurations this file must be edited, otherwise the global configuration
will be used. Below the standard adams.conf is shown.
#########################################################
# This file specifies the AMESim export facility to
#
# ADAMS. The entries are as follows:
#
#
#
# 1. the template to use for an explicit system.
#
# 2. the template to use for an implicit system.
#
# 3. the makefile to use.
#
# 4. the button title.
#
# 5. the script file to launch the companion software. #
#########################################################
$AME/lib/adams_cont.etemp
2004
Using AMESim MSC ADAMS Interface
28//39
NULL
$AME/lib/amesim_adams_gsec.make
Adams
NULL
hp:so,ibm:so,lnx:so,sgi:so,sun:so,win32:dll
The lines beginning with # are comments. The line that all local configurations need to
change is the 3rd non-commented line (currently $AME/lib/amesim_adams_gsec.make).
This is the name of a file with instructions on how to create the AMESim simulation
model. If you want AMESim to use a local configuration this line should point to this,
change this line to, for instance, ./adams.make.
In the standard distribution the file $AME/lib/amesim_adams_gsec.make contains the
following lines:
Using Windows:
$(CC) -c -I$(AME)/lib -DAMEADAMS
$(CC) -LD
dformd.lib asutility_imp.lib
Using Unix:
$(CC) -c -I$(AME)/lib -DAMEADAMS
$(AME)/lib/makeadamsso.sh
-L$(AME_ADAMS_HOME)/ADAMS_NOT_DEFINED_FOR_THIS_COMPUTER_TYPE
–lAsUtility
sun:-L$(AME_ADAMS_HOME)/ultra –lAsUtility
sgi:-L$(AME_ADAMS_HOME)/irix32 –lAsUtility
ibm:-L$(AME_ADAMS_HOME)/ibmrs –lAsUtility
The first line is the command for doing some pre-processing of the AMESim generated C
file and to compile it. If your compiler needs any special flags this is where to add them.
For further customization it is possible, under Unix to modify the makeadamsso.sh file or
under Windows to add some specific library. This is for advanced users only.
Using Windows:
The 2nd line specifies the command used for linking the AMESim simulation executable;
this is normally the C compiler.
Using Unix:
The 2nd line specifies the path to the script (makeadams.sh) that will effectively command
the compilation depending on the platform used.
Using Windows:
The 3rd line specifies the required libraries to compile the system. In our case we need the
Fortran library dformd.lib and an MSC.ADAMS library asutility_imp.lib.
You can add here specific libraries if needed, but these ones must be accessible to the
system. To do so, you will have to append your library path to an environment variable
called %lib%. This can be done in a command file (bat), whether when you start
AMESim or in a local copy of the file %AME%/AMEcompile42.bat.
The line should be:
set lib=%lib%;path_to_your_library
Using Unix:
2004
Using AMESim MSC ADAMS Interface
29//39
The 3rd line should never be used. It is only used if the platform is not recognized. The
following lines (4th, 5th and 6th line) are platform dependant.
If your model includes Fortran code amesim_adams_gsec.make probably needs to be
altered by modifying the 4th line (if working with Sun) specifying the additional libraries
needed. An example on such a line is:
sun:-L$(AME_ADAMS_HOME)/ultra –lAsUtility L/opt/SUNWspro/SC3.0.1/lib -lF77 –lsunmath
This is highly system dependent and you probably need to ask your system administrator
for the libraries used on your computer. If many users are using Fortran it is probably a
good idea to let your system administrator change the amesim_adams_gsec.make in the
standard area ($AME/lib/amesim_adams_gsec.make). Another possibility is to use the
Fortran compiler for the link step, that is change the 2nd line to $(F77).
Another reason to modify the 3rd and following lines is if your submodels use user written
utilities or other non-standard files or libraries; this would typically be a change that you
would do locally. For instance, if you would like to include a library called libmyfuncs.a
which is stored in /home/usr/library modify the 4th line:
sun:-L$(AME_ADAMS_HOME)/ultra –lAsUtility L/home/usr/library -lmyfuncs -L/opt/SUNWspro/SC3.0.1/lib lF77 –lsunmath
Note that for a particular simulation, the state of adams.conf when the system is created
and the corresponding amesim_adams_gsec.make are remembered. It will be necessary to
recreate the interface blocks if you wish to change to a different
amesim_adams_gsec.make.
Note that for using AMESim export facility without Fortran compiler you should modify
amesim_adams_gsec.make in the following way.
Using Windows:
$(CC) -c -I$(AME)/lib -DAMEADAMS
$(CC) -LD
ws2_32.lib kernel32.lib asutility_imp.lib
2004
Using AMESim MSC ADAMS Interface
30//39
2004
Using AMESim MSC ADAMS Interface
31//39
Reporting Bugs and using the Hotline Service
AMESim® is a large piece of software containing many hundreds of thousands of lines of
code. With software of this size it is inevitable that it contains some bugs. Naturally we
hope you do not encounter any of these but if you use AMESim® extensively at some
stage, sooner or later, you may find a problem.
Bugs may occur in the pre- and post-processing facilities of AMESim®, AMESet® or in
one of the interfaces with other software. Usually it is quite clear when you have
encountered a bug of this type.
Bugs can also occur when running a simulation of a model. Unfortunately it is not
possible to say that, for any model, it is always possible to run a simulation. The
integrators used in AMESim® are robust but no integrator can claim to be perfectly
reliable. From the view point of an integrator, models vary enormously in their difficulty.
Usually when there is a problem it is because the equations being solved are badly
conditioned. This means that the solution is ill-defined. It is possible to write down sets of
equations that have no solution. It such circumstances it is not surprising that the
integrator is unsuccessful. Other sets of equations have very clearly defined solutions.
Between these extremes there is a whole spectrum of problems. Some of these will be the
marginal problems for the integrator.
If computers were able to do exact arithmetic with real numbers, these marginal problems
would not create any difficulties. Unfortunately computers do real arithmetic to a limited
accuracy and hence there will be times when the integrator will be forced to give up.
Simulation is a skill which has to be learnt slowly. An experienced person will be aware
that certain situations can create difficulties. Thus very small hydraulic volumes and very
small masses subject to large forces can cause problems. The State count facility can be
useful in identifying the cause of a slow simulation. An eigenvalue analysis can also be
useful.
The author remembers spending many hours trying to understand why a simulation failed.
Eventually he discovered that he had mistyped a parameter. A hydraulic motor size had
been entered making the unit about as big as an ocean liner! When this parameter was
corrected, the simulation ran fine.
In follows that you must spend some time investigating why a simulation runs slowly or
fails completely. However, it is possible that you have discovered a bug in an AMESim®
submodel or utility. If this is the case, we would like to know about it. By reporting
problems you can help us make the product better.
On the next page is a form. When you wish to report a bug, please photocopy this form
and fill the copy. Even if you telephone us, having the filled form in front of you means
you have the information we need.
-
To report the bug you have three options:
-
reproduce the information as an email
-
telephone the details
-
fax the form
Use the email address, telephone number or fax number of your local distributor.
HOTLINE REPORT
Creation date:
Created by:
Company:
Contact:
Keywords (at least one):
Problem type:
£ Bug
£ Improvement
£ Other
Summary:
Description:
Involved operating system(s):
£ All
£ Unix (all)
£ PC (all)
£ HP
£ Windows 2000
£ IBM
£ Windows NT
£ SGI
£ Windows XP
£ SUN
£ Linux
£ Other:
£ Other:
Involved software version(s):
£ All
£ AMESim (all)
£ AMERun (all)
£ AMESet (all)
£ AMECustom (all)
£ AMESim 4.0
£ AMERun 4.0
£ AMESet 4.0
£ AMECustom 4.0
£ AMESim 4.0.1 £ AMERun 4.0.1 £ AMESet 4.0.1
£ AMECustom 4.0.1
£ AMESim 4.0.2 £ AMERun 4.0.2 £ AMESet 4.0.2
£ AMECustom 4.0.2
£ AMESim 4.0.3 £ AMERun 4.0.3 £ AMESet 4.0.3
£ AMECustom 4.0.3
£ AMESim 4.1
£ AMECustom 4.1
£ AMERun 4.1
£ AMESet 4.1
£ AMESim 4.1.1 £ AMERun 4.1.1 £ AMESet 4.1.1
£ AMECustom 4.1.1
£ AMESim 4.1.2 £ AMERun 4.1.2 £ AMESet 4.1.2
£ AMECustom 4.1.2
£ AMESim 4.1.3 £ AMERun 4.1.3 £ AMESet 4.1.3
£ AMECustom 4.1.3
£ AMESim 4.2
£ AMECustom 4.2
£ AMERun 4.2
£ AMESet 4.2
Web Site
http://www.amesim.com
FRANCE - ITALY - SPAIN –
PORTUGAL - BENELUX SCANDINAVIA
S.A.
5, rue Brison
42300 ROANNE - FRANCE
Tel. : 04-77-23-60-30
Tel. : (33) 4-77-23-60-37
Fax : (33) 4-77-23-60-31
E.Mail : hotline@amesim.com
UK
U.K.
Park Farm Technology Centre
Kirtlington, Oxfordshire
OX5 3JQ
ENGLAND
Tel: +44 (0) 1869 351 994
Fax: +44 (0) 1869 351 302
E-mail: support.uk@amesim.com
USA - CANADA - MEXICO
Software, Inc.
44191 Plymouth Oak Blvd – Suite 900
PLYMOUTH (MI) 48170 - USA
Tel. : (1) 734-207-5557
Fax : (1) 734-207-0117
Email : support-us@amesim.com
GERMANY – AUSTRIA SWITZERLAND
Software GmbH
Elsenheimerstr. 15
D - 80687 München - DEUTSCHLAND
Tel: +49 89 / 548495-35
Fax: +49 89 / 548495-11
E.Mail : hotline.germany@amesim.com
JAPAN
Japan KK
SATOKURA AKEBONOBASHI Bldg. 2F
SHINJUKU KU, SUMIYOSHI MACHI, 1-19
TOKYO 162-0065 - JAPAN
Tel. : 81 (0) 3 3351 9691
Fax : 81 (0) 3 3351 9692
Email : hotline-japan@amesim.com
CHINA
China
Room. 109
Jinyan Building (Business), N. 3800 Chunshen Road,
Shanghai 201100
CHINA (PRC)
Tél.: +86 21 34 12 34 58
Fax: +86 21 34 12 84 58
E-mail: qing@amesim.com
United Right Technology
Room 716-717
North Office Tower Beijing, New World Center
No.3-B Chong Wen MenWai dajie,
Postal Code: 100062, BEIJING, P.R CHINA
Tel: (86) 10-67082450(52)(53)(54)
Fax: (86) 10-67082449
Email: urt@urtgroup.com
SOUTH KOREA
SHINHO Systems Co., Ltd.
#702
Ssyongyong IT Twin Tower
442-5, Sangdaewon-dong
Jungwon-gu
Seongnam-si
Gyeonggi
South Korea <462-723 >
Tel. : 82-31-608-0434
Fax : 82-31-608-0439
E.Mail : iclee@shinho-systems.co.kr
BRAZIL
KEOHPS
CELTA – Parc Tec ALFA
Rod. SC 401-km 01 – CEP 88030-000
FLORIANOPOLIS – SC BRAZIL
Tel. : (55) 48 239 – 2281
Fax : (55) 48 239 – 2282
Email : info@keohps.com
HUNGARY
Budapest University of
Technology & Economics
Department of Fluid Mechanics
H-1111 BUDAPEST, Bertalan L. U. 4- 6 HUNGARY
Tel. : (36) 1 463 4072 / 463 2464
Fax : (36) 1 463 3464
Email : vad@simba.ara.bme.hu