Anda di halaman 1dari 320

AutoSim Reference

Manual

Version 2.5+

1993 - Original Publication


1997 - Chapters 2 & 3 Revised

Notice
This manual describes the AUTOSIM software, which is furnished under a license
agreement and may be used or copied only in accordance with the terms of such
agreement.
1987-1995, the Regents of The University of Michigan. All Rights Reserved.
1996-1997, Mechanical Simulation COrporation. All Rights Reserved.
AUTOSIM is a trademark of the Regents of The University of Michigan.
Last revised June 1997.

Macintosh versions of this Program may include Macintosh Allegro Common Lisp
object code from Apple Computer, Inc. The following notices apply to such object code:
APPLE COMPUTER, INC. ("APPLE") MAKES NO WARRANTIES, EXPRESS OR IMPLIED,
INCLUDING WITHOUT LIMITATION THE IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS FOR A PARTICULAR PURPOSE, REGARDING MACINTOSH ALLEGRO COMMON
LISP. APPLE DOES NOT WARRANT, GUARANTEE OR MAKE ANY REPRESENTATIONS
REGARDING THE USE OR THE RESULTS OF THE USE OF MACINTOSH ALLEGRO COMMON
LISP IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY, CURRENTNESS OR
OTHERWISE. THE ENTIRE RISK AS TO THE RESULTS AND PERFORMANCE OF MACINTOSH
ALLEGRO COMMON LISP IS ASSUMED BY YOU. THE EXCLUSION OF IMPLIED
WARRANTIES IS NOT PERMITTED BY SOME STATES. THE ABOVE EXCLUSION MAY NOT
APPLY TO YOU.
IN NO EVENT WILL APPLE, ITS DIRECTORS, OFFICERS, EMPLOYEES OR AGENTS BE
LIABLE TO YOU FOR ANY CONSEQUENTIAL, INCIDENTAL OR INDIRECT DAMAGES
(INCLUDING DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS
OF BUSINESS INFORMATION, AND THE LIKE) ARISING OUT OF THE USE OR INABILITY TO
USE MACINTOSH ALLEGRO COMMON LISP EVEN IF APPLE HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.
BECAUSE SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF
LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES, THE ABOVE LIMITATIONS
MAY NOT APPLY TO YOU. Apple's liability to you for actual damages for any cause whatsoever, and
regardless of the form of the action (whether in contract, tort (including negligence), product liability or
otherwise), will be limited to $50.

TABLE OF CONTENTS
What is AUTOSIM?

xiii

Documentation Guide xv
How to Get Started

xvi

Part 1 Numerical Analysis


Chapter 1: Analysis Options
1.1 Summary 1 2
1.2 Units 1 3
1.3 Points and Vectors 1 3
Vectors 1 3
The Vector Dot Product 1 5
The Vector Cross Product 1 6
1.4 Three Example Models 1 6
1.5 State Variables 1 8
1.6 Continuous Simulation Analysis 1 10
Types of Simulation Analyses 1 10
Kinematics 1 10
Dynamics 1 10
Static Equilibrium 1 13
Design of an AUTOSIM Multibody Simulation Program 1 14
Types of Simulation Software 1 15
Numerical Multibody Simulation Programs 1 16
Continuous Simulation Languages 1 17
Hand-Written Programs 1 17
Programs Completely Written by AUTOSIM 1 18
1.7 Linear Analysis 1 18
1.8 Typeset Equations 1 19

CHAPTER 2: Independent Simulation Programs


2.1 Using the Simulation Program 23
The Parameter File (PARSFILE)
24
How PARSFILEs are used 24
PARSFILE Reference26
Indexed Keywords 29

The Output Data File (ERD File)


210
Batch Operation
211
2.2 Calculation Methods
212
Solution of Simultaneous Algebraic Equations
213
Linear Algebra
213
Nonlinear Algebraic Equations
214
Integration of Ordinary Differential Equations (ODEs)
216
Variable Step Methods
216
Order of the Integrator
217
Stiff Integrators
218
Integration Options with AUTOSIM 220
Differential Algebraic Equations (DAEs)
221
2.3 Design of the Stand-Alone Simulation Program 222
Which Language: Fortran or C?
222
State Variables
223
Program Flow and Organization
223
Set Default Values 225
Read Parameter Values from Input Files
225
Initialize the Simulation
226
Simulate the System 227
Kinematical Simulation Programs 229
Dynamical Simulation Programs
230
Equilibrium Simulation Programs 233
Operations Performed after each Run235
Batch Operation
235
2.4 C Details 236
Language Version and Style 236
Compiling and Linking a C Program 236
Data Storage in Arrays and Global Structures
237
2.5 Fortran Details 239
Language Version and Style 239
Compiling and Linking a Fortran Program 239
Data Storage in Arrays and Common Blocks 240
2.6 Changing the Simulation Program From Within AUTOSIM
242
AUTOSIM Variables Affecting the Program Appearance 242
Breaking Up DIFEQN
244
Include Files 245
Output Files 246

iii

Chapter 3: Continuous Simulation Languages


Chapter 4: Matrix Analysis Languages
4.1 Summary of Linear System Representation 4 2
4.2 MATLAB Code 4 2

Part 2 Symbolic Analysis


Chapter 5: Building a Model
5.1 Introduction 5 3
5.2 Multibody Terminology and Definitions 5 4
Geometric Definitions 5 5
Points 5 5
Vectors 5 5
Reference Frames 5 6
Coordinate Systems and Unit-Vectors 5 6
Distinctions Between Coordinates, Points, and Vectors 5 7
Dyadics 5 7
AUTOSIM Bodies 5 8
Point Masses and Rigid Bodies 5 9
Massless Reference Frames 5 9
Parent Bodies and the Nominal Configuration 5 9
Standard Body Points 5 9
Joints and Constraints 5 10
Body Degrees Of Freedom (DOF) 5 10
Tree Topologies 5 10
Closed Kinematical Loops 5 11
Additional Constraints 5 11
Holonomic and Nonholonomic Constraints 5 12
Forces 5 12
Moments, Couples, and Torques 5 13
Angular Orientation of a Rigid Body 5 14
Angular Velocity of a Moving Reference Frame 5 14
Mass and the Inertia Tensor (Dyadic) 5 14
5.3 Overview of an AUTOSIM Analysis 5 15
Syntax of Commands 5 15
Interactive Computer Algebra 5 17
5.4 Defining the Bodies and Joints 5 18
The Add-Body Command 5 18
State Variables 5 20
The Motion Command 5 21
The No-Movement Command 5 22

Generic Constraint Commands 5 22


Guidelines for Defining Joints 5 23
Controlling the Definitions of the State Variables 5 24
5.5 Adding Forces and Moments 5 26
Gravity 5 27
Working Forces and Moments 5 27
The Add-Line-Force Command 5 27
The Add-Strut Command 5 28
The Add-Moment Command 5 29
Non-working Constraint Forces and Moments 5 29
5.6 Defining Auxiliary Variables 5 31
The Add-Variables and Add-Equations Commands 5 31
Simulation Languages 5 32
Linear Analysis 5 32
Circular Dependencies in Force Definitions 5 32
Fortran Output Variables 5 33
5.7 Installing Nonlinear Tablular Functions 5 34
5.8 Specifying the Analysis 5 35
5.9 Viewing Results of the Analysis 5 36
Commands for Printing 5 36
Recommended Debugging Checks 5 36
5.10 Customizing the AUTOSIM-Generated Program 5 38
Properties of AUTOSIM Symbols 5 38
AUTOSIM Units Expressions 5 39
5.11 Generating the Numerical Analysis Program 5 40

Chapter 6: Using External Code


6.1 Why Use External Code? 6 2
6.2 Single-Valued Functions 6 3
6.3 Subroutines and Multiple-Valued Functions 6 3
The Add-Subroutine Command 6 4
The Add-Variables Command 6 5
Adding Parameters for External Fortran Code 6 5
Example 6 6
6.4 Equations 6 7
6.5 Adding State Variables 6 7
6.6 Installing Differentials 6 8

Chapter 7: Advanced Topics


7.1. Modeling Issues 7 2
Friction 7 2
Lash, Intermittent Contact, and Collisions 7 4
Flexible Bodies 7 5
Circular Dependencies 7 6
7.2. Computation Speed 7 7
Type of Formulation 7 7
The Mass Matrix 7 8
The Order-N Option 7 9
Combining Masses 7 10
Constraints 7 10
Computer Algebra Settings 7 11
7.3. Programming New Commands 7 12
Sources of Lisp Information 7 12
Lisp Basics 7 12
Example New Command 7 14
Lisp Forms Used 7 17
Summary of Example Command 7 19
Restrictions of AUTOSIM Commands in Lisp Functions 7 19
AUTOSIM Data Types 7 20

Part 3 Reference
Chapter 8: AUTOSIM Reference
8.1 Commands 8 3
? 87
add-body 8 8
add-equation 8 12
add-gravity 8 14
add-line-force 8 15
add-moment 8 17
add-out 8 18
add-point 8 20
add-position-constraint 8 21
add-speed-constraint 8 22
add-standard-output 8 23
add-strut 8 24
add-subroutine 8 26
add-variables 8 30
dynamics 8 31
equilibrium 8 34
finish 8 34

in-lb 8 36
install-differential 8 37
install-table 8 38
install-units 8 40
linear 8 42
motion 8 45
no-movement 8 46
print-coordinates 8 49
print-default-directions 8 49
print-default-positions 8 50
print-parameters 8 53
print-speeds 8 56
reset 8 59
set-defaults 8 61
set-names 8 62
setsym 8 62
set-units 8 63

si 8 64
write-acsl 8 66
write-adsim 8 66
write-c 8 67
8.2 Functions 8 79
! 8 81
angle 8 85
cross 8 90
default 8 91
dir 8 91
dot 8 91
dplane 8 92
dxdt 8 92
fm 8 96
ke 8 97
mag 8 98
nominal 8 99

write-matlab 8 73
write-sim 8 77
write-to-file 8 78

partial 8 99
pos 8 101
relvel 8 102
rfvect 8 102
rmvect 8 103
rot 8 104
rq 8 104
ru 8 104
tq 8 107
tu 8 107
vel 8 108
z 8 108

8.3 Globals 8 109


*compiler* 8 114
*double-precision* 8 116
*fortran-implicit* 8 121
*include-path* 8 122
*int-vars* 8 122
*multibody-system-name* 8 126

*no-zees* 8 127
*pre-comp* 8 128
*stiff-integrator* 8 132
*target-language* 8 133
*time-eqs* 8 134

8.4 Data Types 8 139


body 8 141
expression 8 144
force 8 145

moment 8 147
point 8 148

Index

vii

WHAT IS AUTOSIM?
AUTOSIM is a software package that automatically derives equations of motion for
models of mechanical systems composed of multiple rigid bodies. The equations derived
by AUTOSIM are automatically written for each model in the form of a computer
program. Parameters are represented by symbols in the equations, so that the same
equations can be applied many times, using different numerical values of the parameters.
With the AUTOSIM software, you can now tackle simulation and analysis projects
that would not be otherwise affordable. Some of the novel features of AUTOSIM are:

Stand-Alone, Executable Programs AUTOSIM generates complete, readyto-compile Fortran programs that require no other software to run. (Not even
AUTOSIM is needed.) These programs can be freely distributed within your
company.

Simulation Users Do Not Have to Be Simulation Experts Simulation


programs generated by AUTOSIM are easy to use, requiring no experience in
modeling or simulation.

Real-Time Simulation AUTOSIM generates highly efficient equations that


can support real-time, hardware-in-the-loop simulations.

Full Integration with Other Simulation Software AUTOSIM generates


ready-to-run code in several simulation languages: ACSL, ADSIM, and
MATLAB. No programming is required to make the first run in those languages.

Full Integration with Old Libraries AUTOSIM can generate new programs
that work with existing Fortran or C subroutines. Dont re-write your software:
instead, describe the subroutine arguments so AUTOSIM will call them correctly
and appropriately in code it generates.

Full Integration with Pre- and Post-Processors You can modify the source
code generated by AUTOSIM to change the way inputs are read and outputs are
written, to work with your existing pre- and post-processing software.

Interactive Computer Algebra AUTOSIM includes all of the computer


algebra capabilities needed for multibody analyses. You can use these
capabilities to explore alternative modeling options and to help debug models.

Hierarchical Models for Design You can generate a fleet of models, all with
compatible input parameters and output variables. Use simple models for early
concept work and design optimization, and complex models for detailed analysis
of the more developed design.

ix

The approach taken by AUTOSIM for simulating a multibody system involves


splitting the job into the two activities shown in Figure 1:

Modeler (symbolic)

End Users (numerical)

Model Description

Parameter values

Parameter values

AUTOSIM

MATLAB,
ACSL, etc.

Simulation
program

Custom source
code for system

Compiler

Plots, animations,
statistics

Simulation
results

Post-processors

New simulation
Plots, animations,
program
statistics
Figure 1. Analysis strategy with AUTOSIM.

1.

A modeler uses AUTOSIM to generate equations and write computer software


for a specific system model. This step mainly involves symbolic computation.

2.

End users employ the program generated by AUTOSIM to compute the behavior
of the system for sets of design parameters and operating conditions of interest.
This step involves only numerical computation.

DOCUMENTATION GUIDE
This manual is a reference for building models with AUTOSIM and also for using
AUTOSIM-generated programs. It is divided into three parts:
Part 1 Numerical Analysis
The first chapter summarizes the types of analysis that AUTOSIM supports. The
other chapters in Part 1 describe the types of software that AUTOSIM generates.
If you are an end user, you should look through Chapter 1 and the chapter that
describes the type of AUTOSIM-generated software you are using. This is
probably the only part of the manual you will need to read.
If you are a modeler, you should read Chapter 1 and also the chapter that
describes the type of software you will be generating with AUTOSIM.
Part 2 Symbolic Analysis
If you are a modeler, you should study the chapters in this section. They explain
the general strategy for building models with AUTOSIM, and summarize the
many options that are available.
Part 3 Reference
The chapter in this section contains an alphabetical listing of all AUTOSIM
commands, functions, and global variables. If you are a modeler, you will refer
to this part as needed to use specific AUTOSIM commands to their full extent.
Table 1 lists all documentation that is provided with AUTOSIM. Also, the command
? generates a summary of any command or function on-line when using AUTOSIM.
Table 1. AUTOSIM Documentation
Document
Description
AUTOSIM Reference this manual: complete reference for building models with
Manual
AUTOSIM and using AUTOSIM-generated programs
Introductory Guide to 90-page overview of how AUTOSIM is used; includes five
AUTOSIM
complete examples
AUTOSIM Quick
two-sided sheet of cardboard listing the major commands and
Reference
their arguments
Installation Instructions instructions for installing AUTOSIM on a specific platform
ERD File Format
7-page summary of formatted plot files that can be made with
AUTOSIM-generated Fortran programs

xi

HOW TO GET STARTED


First, you must install AUTOSIM on your hardware, according to the Installation
Instructions for your particular computer platform.
After you have installed AUTOSIM, you are probably eager to build your first model.
However, you will make the most rapid progress if you first thoroughly study the 1-mass
example in the Introductory Guide and run it through AUTOSIM. The input file for this
example is provided with AUTOSIM, so you do not have to type in the description. (All
of the examples in the Introductory Guide are also provided.) Please read the machinespecific notes for your machine (Macintosh, Sun, etc.) in the Installation Instructions.
Global variables are given default settings in a file named _config.lsp. You should print a
copy of this file for reference, and possibly edit this file as described in the installation
notes provided with AUTOSIM.
You will see that AUTOSIM can write equations in the form of computer source code
written in several languages, including Fortran, C, MATLAB, ACSL, and ADSIM.
If you are using MATLAB, ACSL, or ADSIM, then generate AUTOSIM outputs in
the language you are using. Otherwise, to get started most easily, generate Fortran source
code as shown in the examples.
If you generate Fortran code, be sure that (1) you have access to a Fortran compiler,
and (2) you know how to use it. If you will be using your Fortran compiler for the first
time, start by compiling the Fortran source code provided for the 1-mass example.
Be sure to thoroughly read page 38 in Chapter 2 before generating Fortran code with
AUTOSIM. In particular, read the discussion of the *include-path* and
*compiler* global variables. These two global variables must be set properly to
generate code that will compile without error with your specific Fortran compiler.

PART 1

NUMERICAL ANALYSIS

This part of the manual describes the software written by AUTOSIM to numerically
compute responses and properties of multibody systems.
Chapter 1 Analysis Options
This chapter introduces concepts and methods that are fundamental to using
AUTOSIM. It summarizes the AUTOSIM analysis options. Three example
multibody systems are shown that will be used as illustrations throughout the
manual. The chapter briefly reviews the underlying engineering principles for the
various types of analysis that are performed by AUTOSIM-generated software.
The review introduces concepts that reoccur throughout the manual.
Chapter 2 Independent Simulation Programs
AUTOSIM can write a complete, ready-to-compile-and-run simulation program
that includes the describing equations for a specific multibody system model, as
well as routines for numerically integrating differential equations, solving
simultaneous algebraic equations, reading input files, generating output plot files,
etc. This chapter includes reference material for both users and programmers
who may be interested in the design of AUTOSIM-generated programs. Sections
2.1 through 2.4 describe AUTOSIM-generated Fortran code, and Section 2.5
describes AUTOSIM-generated C code.
Chapter 3 Continuous Simulation Languages
This chapter explains how to use software generated by AUTOSIM to run with a
simulation language. Section 3.2 describes the use of the Advanced Continuous
Simulation Language (ACSL), sold by Mitchell and Gauthier Associates (MGA).
Section 3.3 describes the use of ADSIM, the simulation language used on realtime computer systems from Applied Dynamics International (ADI).
Chapter 4 Matrix Analysis Languages
This chapter explains how to use code generated by AUTOSIM for linear
analysis in matrix analysis languages such as MATLAB.

CHAPTER 1

ANALYSIS OPTIONS
1.1 Summary 2
1.2 Units 3
1.3 Points and Vectors 3
Vectors 3
The Vector Dot Product 5
The Vector Cross Product 6
1.4 Three Example Models 6
1.5 State Variables 8
1.6 Continuous Simulation Analysis 10
Types of Simulation Analyses 10
Kinematics 10
Dynamics 10
Static Equilibrium 13
Design of an AUTOSIM Multibody Simulation Program 14
Types of Simulation Software 15
Numerical Multibody Simulation Programs 16
Continuous Simulation Languages 17
Hand-Written Programs 17
Programs Completely Written by AUTOSIM 18
1.7 Linear Analysis 18
1.8 Typeset Equations 19

This chapter introduces concepts and methods that are fundamental to using
AUTOSIM. It summarizes the AUTOSIM analysis options. Three example multibody
systems are shown that will be used as illustrations throughout the manual. The chapter
briefly reviews the underlying engineering principles for the various types of analysis that
are performed by AUTOSIM-generated software. The review introduces concepts that
reoccur throughout the manual.

11

AUTOSIM 2.0

1.1 Summary
Kinematical and dynamical equations are an integral part of many engineering
analyses of mechanical systems. Mechanical dynamics, simulation, vibration, control,
and mechanism design are areas in which describing equations are needed. AUTOSIM
derives nonlinear kinematical and dynamical equations of motion for multibody systems.
Those equations can be further manipulated as needed for several types of analysis.
A given type of analysis can be applied using a variety of tools. With just a compiler,
a complete computer program must be written that includes the equations for the system
model, plus all numerical analysis algorithms, plus routines needed to read parameter
values, write output files, and perform the many mundane required tasks. With a compiler
and a library of standard numerical analysis routines, only the subroutines that are based
on the unique equations of the multibody system must be generated. With an interactive
simulation language or high-level numerical analysis language, only the describing
equations are needed.
AUTOSIM can perform several types of analysis, and can generate computer source
code to work with a variety of tools. Table 1.1.1 summarizes options covering three
broad categories of analyses: simulation, linear analysis, and inspection of equations.
These are described in Sections 1.6, 1.7, and 1.8.

Analysis
Continuous
Simulation

Kinematics
Dynamics
Inverse
Dynamics
Equilibrium
Linear

Inspect
Equations

Table 1.1.1. Analysis options in AUTOSIM.


Language
Description
Fortran
custom code for self-contained simulation
program that reads input files, generates output
files, and performs numerical analyses.
ACSL, ADSIM interface to interactive simulation language with
numerical analyses, plotting, etc.
Fortran, C,
custom code to compute positions based on
ACSL
kinematical constraints
Fortran, C,
custom code to compute motions resulting from
ACSL, ADSIM forces and kinematical relations
Fortran, C,
custom code to compute forces and torques
ACSL, ADSIM needed to produce specified motions
Fortran
custom code to compute equilibrium positions
MATLAB
custom code to generate describing matrices for
linearized system
Fortran
custom code to numerically linearize system
Rich text
typeset equations for model documentation,
format (RTF)
technical papers, reports, etc.
12

AUTOSIM 2.0

1.2 Units
AUTOSIM keeps track of units for all parameters and variables associated with a
model. The units system can involves any combination of conventions. For example,
some lengths could have units of millimeters, others inches, and others miles. Angles can
be in degrees or radians, acceleration may be in gs or length/sec 2, and so on. The units
seen by the user are called user units. They are not necessarily those used internally in the
equations of motion. All equations derived by AUTOSIM are written assuming a
consistent dynamical units system that requires no scale factors within the equations of
motion. All angular measures have units of radians. Force, mass, and length units are
assumed to be defined such that the basic dynamics equation F=ma requires no scale
factors. For example, the SI units system has this consistency, with force in Newtons,
mass in kilograms, and length in meters. An English equivalent might be force in pounds,
mass in slugs, and length in feet. (This type of units system is sometimes called a
dynamics units system, or a kinetics units system.)
Tables and summaries showing units for parameters and variables usually indicate
user units, even though the equations generated by AUTOSIM are always in dynamics
units. AUTOSIM manages all necessary units conversions when generating code.
Software generated by AUTOSIM always converts units between user units and
dynamics units whenever variables or parameters are read as inputs or written as outputs.

1.3 Points and Vectors


In all of the AUTOSIM documentation, geometric properties of a multibody system
are described with points and vectors. We use a point as a means to identify a position in
space that is of interest. The point may represent a physical spot on a mechanical object;
it may represent a spot on a mechanical object that can move; or it can represent a
position in space that is not a part of any physical part, but which is of interest when we
describe a multibody system. For example, Figure 1.3.1 shows a moving body, A, and an
inertial reference called N1. There are also four points of interest, shown with small
circles. One, point O, is fixed in N. Points P1, P 2, and P3 are fixed at three of the corners
of the moving body A.
Vectors
In Figure 1.3.1, reference N and body A each have a set of three unit vectors that
define mutually perpendicular directions. Two such sets are shown for the X and Y
directions. A third direction (Z), not shown, exists perpendicular to the paper on which
this figure is printed. The unit-vectors nx and ny are fixed relative to the reference N (the

An inertial reference is a concept basic to Newtonian mechanics, and is often called a Newtonian
reference. It defines a frame of reference that, for all practical purposes, is not moving. For systems
involving ground vehicles, mechanisms, and robots, it is common to define the ground as an inertial
reference.

1 3

paper) and define the


directions shown,
A
O
regardless of where
ay
P3 body A might be
located. The unit- N
vectors ax and ay are
ax
n
P
y
1
fixed relative to body
A. Regardless of how
w
body A is rotated, the
line
connecting
h
nx
points P2 and P3 is in
the direction of a x ,
P2
and
the
line
connecting points P2
and P1 is in the Figure 1.3.1. Points and unit-vectors in direction of ay.
moving bodies.
You use the unitvectors to describe
the location of one point relative to another. For example, to get from point P 1 to point
P2, you go a distance h in the direction ay. The information that describes how to get
from point P1 to P2 is contained in the position vector rP1 P 2 . This information can be
written in equation form:
rP1 P 2 = h ay

(1.3.1)

When written algebraically, a position vector describes a path for getting to one point
(P2) from another (P 1). When defining a vector, there are many paths that can be taken.
For this example, we might instead describe the path from point P1 to P2 using the
directions nx and ny:
rP1 P 2 = h sin nx h cos ny

(1.3.2)

where is the rotation angle of body A counterclockwise from an orientation in which ax


is aligned with nx.
The notational convention used throughout the AUTOSIM documentation is that a
position vector connecting two points, say, P and Q, is written as rPQ. An exception is
when the first point is point O in the inertial reference. In that case, the position vector is
to point P is written simply rP (= rOP) and is called the absolute position of point P.
When using AUTOSIM, you will be mainly concerned with describing the locations
of points in a body relative to a reference point. For example, you might need to describe
the location of point P3 relative to point P 1 . Hopefully it is clear that the simplest
description possible, given the information in the figure, is
rP1 P 3 = w ax h ay

(1.3.3)

The example vectors shown so far have all involved position. However, other
kinematical quantities are also described by vectors. A vector is simply an entity that has
a magnitude and a direction. The magnitude of a vector is indicated mathematically with
the absolute value operator, e.g., the magnitude of vector r is |r|. The direction of a vector
r
is obtained by dividing the vector by its magnitude, e.g., the direction of vector r is |r| .
The derivative of a vector is also a vector. Because the position of a point is defined
by a vector, the velocity and acceleration of a point are also necessarily vector quantities.
Forces and moments applied to bodies are also vector quantities. A unit vector is the

1.3 Points and Vectors

AUTOSIM 2.0

special case of a vector whose magnitude is dimensionless, with an amplitude of unity.


Usually, the direction of a unit-vector is fixed relative to a part of a multibody model.
When using AUTOSIM to build models, you will not have to derive any vector
expressions. However, you will need to understand conceptually the nature of vector
quantities, and how they are used to describe the motions of moving objects. Although
the examples so far have been planar, vectors for multibody systems can be threedimensional.
There are two algebraic operations involving vectors that will appear throughout this
manual: the dot product and the cross product.
The Vector Dot Product
Suppose there are two arbitrary vectors a and
b. The dot product between a and b is written a
b and is defined as the scalar quantity
a b = |a| |b| cos

(1.3.4)

where is the angle between the vectors, as


shown in Figure 1.3.2. If vector b has a magnitude
of unity, as shown in the figure, then the dot
product operation yields the length of vector a
that is projected in the direction of b. For
example, consider the vector r P1 P 2 defined in
Figure 1.3.1 and eqs. 1.3.1 and 1.3.2. The
dimension for the distance between points P1 and
P2 in the direction ay can be defined with the dot
product
rP1 P 2 ay = h

b
ab
unity
Figure 1.3.2. Dot product when
one of the vectors is a unit-vector.

(1.3.5)

The dimension in the direction nx can be defined


rP1 P 2 nx = h sin

(1.3.6)

When using AUTOSIM, you will never have to work out a dot product by hand.
However, you might use the dot-product operator to define certain quantities. For
example, if you were interested in the distance between points O and P2 in the direction
nx, you could specify that distance as rP2 n x and let AUTOSIM work out the details of
defining the position vector and the dot product. As another example, suppose you were
interested in the X-component of the velocity of point P2. You could define it as vP 2 nx,
where vP2 is the (vector) velocity of the point. (AUTOSIM will work out the details of
determining the velocity vector and the dot product.)

15

The Vector Cross Product


Again, suppose there are two vectors a and b. The cross product between them,
written a b, defines a vector with the properties that:
1.

ab

its magnitude is
|a b| = |a| |b| sin

(1.3.7)

2.

its direction is perpendicular to


both a and b

3.

the arrow of the vector is defined


by the right hand rule as shown
in Figure 1.3.3. If you point the
fingers of your right hand in the
direction of a and fold your hand
to point them in the direction of
b, your thumb will point
approximately in the direction of
a b.

You may never need to use the cross


Figure 1.3.3. Cross Product.
product operation when building
AUTOSIM models. However, it is handy for defining directions of moving reference
frames.

1.4 Three Example Models


Three example multibody systems will be to illustrate methods throughout this
manual. The first, described in Appendix A of the Introductory Guide to AUTOSIM, is

sy

sx
s

FDR

FSR

AR

FDF

FSF

AF
FTF

FTR

ny

nx
nz

Figure 1.4.1. Simple vehicle ride model.

1.4 Three Example Models

AUTOSIM 2.0

the planar vehicle ride model shown in Figure 1.4.1. The model includes three rigid
bodies, identified by the symbols S, AF, and AR. Two sets of directions are shown. One
is fixed in the inertial reference, N, and is defined by the unit-vectors nx, ny, and nz. The
other is fixed in S, and is defined by the unit-vectors sx , s y , and s z . Note from the
directions shown in the figure that both bodies AF and AR can translate only in the
direction of the unit-vector sz. Thus, their coordinate systems employ the same directions
as S, namely the unit-vectors sx, sy, and sz.
The second model is the four-bar
linkage described in Appendix D of the
Introductory Guide. Figure 1.4.2 shows
that this system includes three rigid
bodies identified as A, B, and C. Points
of interest are numbered. Bodies A and
B are massless links, connected to
ground (N) by pin joints at points 1 and
6. Body C is connected to A by a pin
joint at point 3, and to B by a pin joint
at point 8.

N
A

3
g

ny

C
4

nx
8

7
The third model is a spacecraft
B
6
shown in Figure 1.4.3 and described
Figure 1.4.2. Four-bar linkage.
fully in Appendix C of the Introductory
Guide. The spacecraft is composed of three rigid bodies and one flexible body. The rigid
bodies are (1) the main body of the craft, called the bus and designated body B, (2) a
camera (body D), and (3) a supporting shaft called a clock (body C). The flexible
member, called the boom (body E), is modeled with a two-degree of freedom hinge.
Camera

Clock
Bus

ny
nx

Bus DOF

Boom

nz
Figure 1.4.3. Spacecraft vehicle.
These three multibody systems are presented here to serve as examples for numerical
and symbolic analysis methods described in the remainder of this manual. The pitchplane model is the primary example system. The 4-bar linkage will be used to illustrate
methods and commands used for constrained mechanism systems. The spacecraft system
will be used to illustrate methods required for three-dimensional systems.

17

AUTOSIM 2.0

1.5 State Variables


The state of the multibody system is described mathematically at an instant in time by
a set of state variables. When all of the state variables of a multibody system have known
values, then it is possible to reconstruct the position and velocity of any point on any
moving part in the system. AUTOSIM introduces the state variables, and uses them as
needed to develop mathematical expressions of variables that are of interest to the
modeler. The state variables for a multibody system are divided into two sets: generalized
coordinates and generalized speeds.
The generalized coordinates are variables involving angular rotation and translational
displacement. The set of generalized coordinates is defined such that it is possible to
reconstruct the position of any point in any mechanical part in the system. By convention,
the coordinates are written as q 1, q2, ... qn, or, more simply, as the array q. AUTOSIM
can derive expressions for the absolute coordinates of any point located on any
mechanical part using the generalized coordinates and dimensional parameters. For
example, the generalized coordinates introduced by AUTOSIM for the vehicle ride model
are listed in Table 1.5.1. With the coordinates shown in the table (and dimensional
parameters) it is possible to define the position of any point in the system. For example,
the absolute vector position of point AR0, rAR0, fixed in body AR, could be written
rAR0 = q1 nx + q2 nz L sx + q5 sz

(1.5.1)

Table 1.5.1. State variables for the simple vehicle ride model.
Variable
Description
q1
Abs. nx trans. of S0 (m)
q2
Abs. nz trans. of S0 (m)
q3
Abs. ny rot. of S (rad)
q4
sz trans. of AF0 rel. to S0 (m)
q5
sz trans. of AR0 rel. to ARJ (m)
u1
Abs. sz trans. speed of SCMC (m/s)
u2
Abs. ny rot. speed of S (rad/s)
u3
sz trans. speed of AF0 rel. to S (m/s)
u4
sz trans. speed of AR0 rel. to S (m/s)
The set of generalized speeds complements the set of generalized coordinates, by
adding the capability for AUTOSIM to establish the velocity vector of any point located
on any part in the multibody system. By convention, the speeds are written as u1, u2, ...
up, or, more simply, as the array u. For example, the velocity of point AR0 in the simple
ride model is written in terms of the state variables as
(V + q5 u2) sx + (u1 + u4 + p4 u2) sz

18

(1.5.2)

1.5 State Variables

AUTOSIM 2.0

(V is the constant forward speed of the vehicle and p4 is a constant involving dimensions
of the system.)
In many cases, the generalized speeds are simply the time derivatives of the
generalized coordinates. However, this is not always the case. For example, in the
example ride model, the coordinate q 2 defines translation in the direction nz, whereas the
speed u1 defines a translational speed component in the sz direction. In some systems,
such as the example one, the number of coordinates does not equal the number of speeds.
(In the example, it is because the forward speed is a constant, V, not a variable.)
AUTOSIM always maintains a minimal number of generalized speeds that is equal to
the number of dynamical degrees of freedom (DOF) of the system. When the forward
speed of the ride model is fixed, the system has four DOF, and there are four generalized
speeds. The four-bar linkage has, at most, a single DOF. (If a force is applied to body C,
as shown in Figure 1.5.2, and the system moves in response, then it is said to have one
DOF. On the other hand, if the vertical position of body C were to be constrained, then
the system would have zero DOF. ) Table 1.5.2 shows that AUTOSIM introduces four
state variables for this system: one speed, and three coordinates. However, only one of
the generalized coordinates is independent. The others are dependent, and are called
computed coordinates because they can be computed from the value of the independent
coordinate.
Table 1.5.2. State variables for the four-bar linkage.
Variable
Description
q1
(comp.) Abs. nz rot. of A (rad)
q2
(comp.) nz rot. of C rel. to B (rad)
q3
Abs. nz rot. of B (rad)
u1
Abs. nz rot. speed of B (rad/s)

Using the state variables in Table 1.5.2, AUTOSIM can express the position and
velocity of any point in the system. For example, the vertical velocity component of the
mass center of body C, ny vCCM, is written in terms of the single speed, u1, as
ny vCCM = -u1 (p1 c3 -p2 s3 + (-p3 (c3 c2 -s3 s2) + p4 (c3 s2 + c2 s3)) (1.0 + (p1 s3 -p7
(c3 s2 + c 2 s3) -p8 (c2 c3 -s2 s3) + p2 (c3 + s3 (p6 c1 + p5 s1)/(p5 c1 -p6 s1)) -(c3
(p9 c1 + p10 s1) + c1 (-c3 (p13 c2 -p14 s2) + s3 (p14 c2 + p13 s2)) + s1 (-c3 (p11 c2 p12 s2) + s3 (p12 c2 + p11 s2)))/(p5 c1 -p6 s1))/(c3 (c2 (p8 -(p13 c1 + p11 s1)/(p5 c1
-p6 s1)) + s2 (p7 + (p14 c1 + p12 s1)/(p5 c1 -p6 s1))) + s3 (c2 (p7 + (p14 c1 + p12
s1)/(p5 c1 -p6 s1)) + s2 (-p8 + (p13 c1 + p11 s1)/(p5 c1 -p6 s1))))))
where s1, s2 , c1, and c2 are sines and cosines of q1 and q2, and p1, p2, etc. are constants
involving system dimensions.

19

AUTOSIM 2.0

1.6 Continuous Simulation AnalysisA continuous simulation program performs a


sequence of computations for input conditions that might vary continuously. The
simulation is run over a period of time to provide histories of variables that describe the
system. The end user of a simulation program can specify values for model parameters,
and also parameters related to running the simulation, such as a start time, stop time, and
time step. The end user may also be able to provide inputs as functions of time. These
might include applied forces or specified motions of bodies in the system model.
Types of Simulation Analyses
AUTOSIM generates software to perform three types of analyses in the category of
continuous simulation: kinematics, dynamics, and equilibrium. In all three cases, the
simulation software computes values of the state variables as functions of time and inputs
to the system. Additional variables are also computed if they were defined by the
modeler.
In software generated by AUTOSIM, time is the independent variable used for
defining motions. In a dynamical simulation, time is indeed the independent variable
upon which the differential equations are based. However, for a kinematical or
equilibrium simulation, the computed responses are dependent on time only to the extent
that input motions are defined as functions of time.
Kinematics
In a purely kinematical model, there are no dynamical DOF, and therefore, no
generalized speeds. For example, the four-bar linkage becomes a kinematical model if the
vertical position of point 5 is specified as a function of time (see Figure 1.4.2). Except in
certain special cases, a purely kinematical simulation does not involve differential
equations. Although AUTOSIM usually maintains a set of generalized coordinates to
describe positions of points, they are all either explicit functions of time or dependent
computed coordinates that are computed numerically with a process called NewtonRaphson iteration to maintain the geometric constraints imposed on the moving parts of
the system (see Section 2.2.).
In a kinematical or equilibrium simulation, the computed coordinates are always
calculated each time step with the Newton-Raphson process. In a dynamical simulation,
the computed coordinates are calculated either by Newton-Raphson or by a highly
efficient approximation. (The choice of which method to use is made when you model
the system.) A dynamical simulation involves differential equations, as described in the
next sub-section.
Dynamics
When the motions of the parts in a multibody system are not completely constrained
by kinematic elements such as rigid joints and specified motions, then the system
responds dynamically to specified inputs. For a given multibody system model, the
minimal number of independent generalized speeds needed to define the absolute

1 10

1.6 Continuous Simulation Analysis

AUTOSIM 2.0

velocity vector of any point on any body in the system is the number of degrees of
freedom (DOF) of the system.
There are also likely to be independent generalized coordinates introduced by
AUTOSIM. During the simulation, the generalized coordinates are computed by
numerically integrating a set of differential equations with the form:
.
q =s

(1.6.1)

.
where q is an array of the derivatives of the generalized coordinates, and s is an array of
speeds defined in terms of the current values of the state variables and known functions
of time. The above equations are called the kinematical equations. They define the
geometric relationships between the generalized coordinates and generalized speeds. For
example, in the simple vehicle ride model, the kinematical equations derived by
AUTOSIM are:
.
q 1 = Vc3 + (u1 -p1 u2) s3
.
q 2 = -(-(u1 -p1 u2) c3 + v s3)
.
q 3 = u2
.
q 4 = u3
.
q 5 = u4

(1.6.2)

Computed coordinates must be given initial values that maintain proper relations
between the bodies in the system. For example, with the four-bar linkage, the angles of
bodies A and C (q1 and q2) must be given values consistent with the angle of body B in
order for the parts to stay connected properly. The computed coordinates must also be
calculated at each time step. Two methods are available for a dynamical simulation,
based on input commands to AUTOSIM when the model is developed. They are either
computed with the Newton-Raphson method, or by a computationally efficient
approximation (see Section 2.3.).
The generalized speeds are computed by integrating ordinary differential equations of
the form
.
u =f

(1.6.3)

.
where u is an array of the derivatives of the generalized speeds, and f is an array whose
elements are computed from the current values of the state variables and time. These
equations are called the dynamical equations of the multibody system.
The dynamical equations are developed by AUTOSIM such that they (1) are
independent and (2) satisfy Newtons second law and Eulers equations. In vector form,
Newtons second law for a rigid body is

1 11

dp
f = dt = m a

(1.6.4)

where f is the vector sum of all forces acting on the body, p is the vector momentum of
the body, m is the body mass, and a is the vector acceleration of the mass center of the
body. The vector form of Eulers Equations for a rigid body is
dh
t = dt = I + I

(1.6.5)

where t is the vector sum of all torques and moments acting on the body about its mass
center, h is the vector angular momentum of the body about its mass center, I is the
inertia dyadic of the body relative to its mass center, is the vector angular acceleration
of the body, and is the vector angular velocity of the body.
Consider the vehicle ride model. The kinematical equations were presented earlier in
eq. 1.6.2. The dynamical equations derived by AUTOSIM are
.
u 2 = (u2 (p54 + p55 + p58 -p60 -u2 ((p16 -p44) q4 -(p18 -p45) q5)) -q4 (u2 (p15 u1 -p29
u2 + p30 u3) + p22 s3) -q5 (u2 (p17 u1 + p31 u2 + p32 u4) + p24 s3) + c3 (p56 + p57
+ p59 -p61 -p3 f5 + p4 f6) -p48 (-f1 + f2 -f3 + f4) + p40 (f1 -f2 + c3 f5) -p42 (f3 -f4 +
c3 f6) -s3 (q4 f5 + q5 f6))/(p53 + p15 q42 + p17 q52)
.
.
u 1 = -(p62 u2 + p63 c3 -p47 (-f1 + f2 -f3 + f4) + p64 u 2)
.
.
.
u 4 = u2 (p66 + p65 q5 u2) + p67 c3 + p41 (f3 -f4 + c3 f6) -p42 u 2 -p65 u 1
.
.
.
u 3 = u2 (p69 + p68 q4 u2) + p70 c3 + p39 (f1 -f2 + c3 f5) + p40 u 2 -p68 u 1

(1.6.6)

where f1, ... f6 are forces from the tires, springs, and dampers, and p1, ... p70 are constants
calculated from parameters.
(Note: AUTOSIM normally introduces intermediate variables to improve the
efficiency of the equations of motion. This capability was disabled to generate eqs. 1.6.2
and 1.6.6. The amount of computation is reduced considerably when AUTOSIM is run
with the normal settings, but the equations are not easy to read.)
A dynamics simulation program computes state variablesgeneralized coordinates
and generalized speedsby numerically integrating kinematical equations and dynamical
equations. The two sets of equations are combined into a set of first-order ordinary
differential equations (ODEs)
.
x=

(1.6.7)

where
.
. q
x = .
u

s
=
f

(1.6.8)

1.6 Continuous Simulation Analysis

AUTOSIM 2.0

Numerical solution of equations sets in the form of eq. 1.6.7 is a well-developed area
of applied mathematics, called integration of ordinary differential equations, or,
sometimes, the initial value problem.
Static Equilibrium
If all of the forces and moments applied to a multibody system are held constant, it
may settle into an equilibrium position. Or, it may not. Consider a body unsupported in a
gravity field with no other forces acting on it. The body will accelerate due to gravity,
and never reach an equilibrium state with respect to position. On the other hand, a
constrained system such as the four-bar linkage generally has a static equilibrium position
that depends on the magnitude and directions of applied forces.
When a system is in static equilibrium, the speeds and their derivatives are zero. Eq.
1.6.3 therefore reduces to
0=f

(1.6.9)

where 0 is an array of zeros. The form of eq. 1.6.9 is deceptively simple. The actual
equations for most models of mechanical systems usually are complicated. For example,
in the case of the four-bar linkage, the equation for the force-balance error (with no
intermediate variables) is
e1 = c3 (c2 (p73 -p74 c2) -s2 (p75 + p74 s2)) -s3 (c2 (p75 -p76 c2) + s2 (p73 -p76 s2)) (p 71 c 3 -p72 s3) f1/max(1.0e-20, (p39 -p110 c3 -p111 s3)0.5 ) -(p90 ((c2 c3)2 + (s2
s3)2) -p105 ((c3 s2)2 + (c2 s3)2) + s3 (p77 s2 s3 -c3 (p77 c2 -(p80 -p89 c2) s2) + p92
(c3 s2 + c2 s3) + p91 (c3 c22 -s2 (c3 s2 + c2 s3))) -c3 (c3 (p80 c2 -(p95 + p91 c2) s2)
+ c2 (p104 c3 s2 -s3 (p95 -(p103 c1 + p102 s1)/(p5 c1 -p6 s1))) -s3 (p104 s22 -c2 (p106
s2 + c2 (p104 -p101 s1/(p5 c1 -p6 s1))))) + s2 (p104 c2 s32 -(c2 s1 s3 (p100 c3 + p101
s3) + c3 (c3 (p103 c1 + p102 s1) -p101 s1 (c2 c3 -s2 s3)))/(p5 c1 -p6 s1)) + (s1 (-p86
((c2 c3)2 + (s2 s3)2) -p99 ((c3 s2)2 + (c2 s3)2) + s3 (p78 s2 s3 + p93 (c3 s2 + c2 s3) c2 (p78 c3 -p84 (c2 c3 -s2 s3))) + c3 (p87 (c2 c3 -s2 s3) -s2 (p84 s2 s3 -c2 (p84 c3 +
p85 s3)))) + c1 (-p83 ((c2 c3)2 + (s2 s3)2) -p96 ((c3 s2)2 + (c2 s3)2) -s3 (-p79 s2 s3 +
c2 (p97 c3 s2 -p94 s3) + c3 (p79 c2 + s2 (p107 + p81 s2))) + c2 (p81 s2 (c32 -s32) +
c 3 (p 88 c 3 + s3 (p 81 c 2 + p 82 s2 ))) + p 98 (c 2 c 3 2 s2 -s3 (c 3 s2 2 -c 2 (c 2 c 3 -s2
s3)))))/(p5 c1 -p6 s1))/(c3 (p8 c2 + p7 s2) + s3 (p7 c2 -p8 s2) -(c1 (p13 (c2 c3 -s2 s3)
-p14 (c3 s2 + c2 s3)) + s1 (p11 (c2 c3 -s2 s3) -p12 (c3 s2 + c2 s3)))/(p5 c1 -p6 s1)) +
f2 (-(p42 (c2 s3 + c3 s2) -p41 (c2 c3 -s2 s3)) (1.0 + (p1 s3 -p7 (c3 s2 + c2 s3) -p8 (c2
c3 -s2 s3) + p2 (c3 + s3 (p6 c1 + p5 s1)/(p5 c1 -p6 s1)) + (-c3 (p9 c1 + p10 s1) + c1
(c3 (p13 c2 -p14 s2) -s3 (p14 c2 + p13 s2)) + s1 (c3 (p11 c2 -p12 s2) -s3 (p12 c2 + p11
s2)))/(p5 c1 -p6 s1))/(c3 (c2 (p8 -(p13 c1 + p11 s1)/(p5 c1 -p6 s1)) + s2 (p7 + (p14 c1
+ p12 s1)/(p5 c1 -p6 s1))) + s3 (c2 (p7 + (p14 c1 + p12 s1)/(p5 c1 -p6 s1)) + s2 (-p8 +
(p13 c1 + p11 s1)/(p5 c1 -p6 s1))))) + (c3 c2 -s3 s2) (p1 c2 + p2 s2 -p3 (1.0 + (p1 s3 p7 (c3 s2 + c2 s3) -p8 (c2 c3 -s2 s3) + p2 (c3 + s3 (p6 c1 + p5 s1)/(p5 c1 -p6 s1)) + (c3 (p9 c1 + p10 s1) + c1 (c3 (p13 c2 -p14 s2) -s3 (p14 c2 + p13 s2)) + s1 (c3 (p11 c2 p12 s2) -s3 (p12 c2 + p11 s2)))/(p5 c1 -p6 s1))/(c3 (c2 (p8 -(p13 c1 + p11 s1)/(p5 c1 p 6 s1)) + s2 (p7 + (p14 c 1 + p12 s1)/(p5 c1 -p 6 s1))) + s3 (c2 (p 7 + (p14 c 1 + p12
1 13

s1)/(p5 c1 -p6 s1)) + s2 (-p8 + (p13 c1 + p11 s1)/(p5 c1 -p6 s1)))))) + (c3 s2 + c2 s3)
(-p2 c2 + p1 s2 + p4 (1.0 + (p1 s3 -p7 (c3 s2 + c2 s3) -p8 (c2 c3 -s2 s3) + p2 (c3 + s3
(p6 c1 + p5 s1)/(p5 c1 -p6 s1)) + (-c3 (p9 c1 + p10 s1) + c1 (c3 (p13 c2 -p14 s2) -s3
(p 14 c 2 + p 13 s2 )) + s1 (c 3 (p 11 c 2 -p 12 s2 ) -s3 (p 12 c 2 + p 11 s2)))/(p5 c 1 -p6
s1))/(c3 (c2 (p8 -(p13 c1 + p11 s1)/(p5 c1 -p6 s1)) + s2 (p7 + (p14 c1 + p12 s1)/(p5 c1
-p6 s1))) + s3 (c2 (p7 + (p14 c1 + p12 s1)/(p5 c1 -p6 s1)) + s2 (-p8 + (p13 c1 + p11
s1)/(p5 c1 -p6 s1)))))))
For this type of problem, the numerical Newton-Raphson iteration method is used to
solve for the independent generalized coordinate(s). A quasi-static equilibrium simulation
program numerically calculates a solution to eq. 1.6.9 in response to applied forces and
moments specified as functions of an independent variables. A physical interpretation is
that the responses generated are what would happen if all inertias and masses for the
system were zero, enabling an instantaneous response.
Design of an AUTOSIM Multibody Simulation Program
Whether an AUTOSIM simulation program computes kinematical, dynamical, or
equilibrium responses, it generally follows the flowchart shown in Figure 1.6.2. (The
design of AUTOSIM-generated simulation programs will be described in full detail in
Section 2.3. The following material is a preview, presented just to give an idea of how the
AUTOSIM-generated programs are designed.) There are five basic tasks that are
performed:
1.

SET DEFAULTS after starting, all simulation parameters and multibody


parameters of the multibody system are set to default values. At the end of this
task, all variables in the program have been assigned reasonable values, in case
the user does not specify alternate values.

2.

INPUT new parameter values from the user are assigned to change some of
the program parameters. At the end of this task, all parameters needed to run the
simulation have been set.

3.

INITIALIZE calculations involving parameters are made to initialize


variables used in the simulation. In this task, units conversions are made, tables
are initialized, and constant expressions involving parameters are calculated. For
some multibody models, the initial positions of some parts must be calculated to
obtain a valid starting configuration. A file may be created that echoes the
parameter values used for the run. Output files that will contain simulated
response variables are created and initialized.

4.

SIMULATE response variables are computed repeatedly as time is varied in


steps from a starting time to a stopping time. Values of variables are written into
an output file for plotting and post-processing.

5.

FINISH when the simulation reaches the stopping condition, output files are
closed. Summary statistics may be computed and printed. A final output file may
be created with summary information.

1.6 Continuous Simulation Analysis

AUTOSIM 2.0

START

SET DEFAULTS

INPUT

Set default parameters values

Read files with parameter values and


known functions of time

INITIALIZE

Set initial conditions, start output


file, and write parameters and
initial conditions into an echo file

SIMULATE

Step through simulated time,


compute response variables, write
variables into output file

FINISH

Close files, write final conditions in


echo file

QUIT
Figure 1.6.2. Flowchart of a simulation program.
The differences between kinematics, dynamics, and equilibrium simulations are
mainly in the type of calculation performed in the SIMULATE block. In a dynamics
simulation, ordinary differential equations are numerically integrated over small time
steps. In the other types of simulation, algebraic equations are solved at each time step.
Figure 1.6.3 shows a generic flowchart for the SIMULATE task. The equations for the
multibody system formulated by AUTOSIM are written in subroutines represented by the
blocks in the figure labeled FCT, UPDATE, and OUTPUT.
The simulation steps through time, using two nested loops. The main loop is run
when the time variable T is incremented by DT. Each cycle, the subroutines FCT and
UPDATE are executed once. In the outer loop, variables of interest are written into an
output file at some multiple of DT.
Types of Simulation Software
The basic simulation program design is implemented in several ways, depending on
the type of analysis conducted with AUTOSIM.

1 15

INTEQS

D: Integrate differential equations


E, K: do nothing

T T + DT
FCT
(DIFEQN)

D: Calculate derivatives
E: Calculate equilibrium conditions
K: Calculate computed coordinates and auxiliary terms

UPDATE

D,E,K: Update auxiliary variables,


D: Calculate computed coordinates

Write?
no
yes
OUTPUT

Done?
no
yes

Write variables to file for time T

NOTES: D = dynamics simulation


E = equilibrium simulation
K = kinematics simulation

Figure 1.6.3. Flow chart for SIMULATE block.

Numerical Multibody Simulation Programs


There are a number of commercial software packages for performing continuous
simulations of multibody systems. The most comprehensive are numerical multibody
simulation programs, such as the ADAMS program from Mechanical Dynamics Inc.
(MDI) in Ann Arbor, MI. Numerical multibody programs take as input a description of
the multibody systemthe number of bodies, the types of joints connecting them,
connecting force elements, etc.together with numerical values for all dimensions,
masses, and simulation run parameters. The programs contain a structure for the
equations of motion expressed in a generalized matrix form that is embedded in the
software. Based on the inputs, predefined program variables are set to numerical values
to describe the particular system of interest. As the simulation runs, coefficients in the
matrices are updated and matrix manipulation routines are applied.
The user of a generalized numerical multibody program does not have to provide any
equations. The blocks shown as FCT, UPDATE, and OUTPUT in Figure 1.6.3 are

1.6 Continuous Simulation Analysis

AUTOSIM 2.0

already an integral part of the program and cannot be modified by the user. For better or
worse, there is no real use for equations generated by another means, such as AUTOSIM.
Although there are occasions where usage of a generalized multibody simulation program
would be improved by using additional code generated by AUTOSIM, in general you
would not use AUTOSIM to complement a numerical multibody program. Rather, a
specialized program generated by AUTOSIM would be used instead of a numerical
multibody program.
Continuous Simulation Languages
A continuous simulation language provides a variety of computational tools needed to
perform simulation computations. Examples of simulation languages are ACSL, from
Mitchell and Gauthier Associates (MGA), and ADSIM, from Applied Dynamics
International (ADI). A simulation language is less automated and more generalized than a
multibody program. In order to run a simulation, you must provide describing equations.
There is no limit to the type of dynamic system that can be simulated, so long as you are
able to come up with the correct equations. (It might be mechanical, electrical, chemical,
etc.) The simulation software automatically processes the equations to compute responses
to specified inputs, using built-in routines for numerical integration, linear algebra,
nonlinear equation solving, etc. The user specifies values for simulation run parameters
and any parameters appearing in the equations. Parameter values can be changed between
runs, and response variables can usually be viewed graphically.
In terms of the flowcharts shown in Figures 1.6.2 and 1.6.3, most of the blocks are
built into the simulation languages. Only the blocks such as FCT, UPDATE, and
OUTPUT in Figure 1.6.3 need to be provided when you use these languages.
Although much of the programming needed to generate a simulation is already built
into a simulation language, the process of deriving the correct describing equations for a
system model can be a serious bottleneck. AUTOSIM removes this bottleneck for
mechanical system models. With AUTOSIM, a modeler can obtain the describing
equations for once and for all in terms of parameters that are of interest to the end user.
The end user has all the numerical analysis and graphics capabilities of the simulation
language, together with code generated by AUTOSIM for the specific multibody model.
AUTOSIM generates code that is ready to run in the ACSL and ADSIM languages.
For the ACSL language, it generates a few Fortran subroutines (FCT, UPDATE, etc.) and
the ACSL code that invokes them. For ADI computers, with ADSIM compilers,
AUTOSIM can generate an entire simulation code directly in native ADSIM. Chapter 3
describes how code generated by AUTOSIM is used with these simulation languages.
Hand-Written Programs
A specialized simulation program can be written for a specific multibody system.
Libraries are available, commercially and in the public domain, with canned subroutines
that perform the generic computations needed to simulate multibody systems. The canned
routines perform such functions as numerical integration and Newton-Raphson iteration.
By combining the canned routines with a few custom subroutines that contain the

1 17

describing equations of a multibody system, a custom program can be written to simulate


a particular multibody system. AUTOSIM generates custom routines in a form that works
with little or no modification with most numerical integration subroutines and equation
solving codes. The routines can be generated in either the Fortran or C programming
languages, as described in Chapter 2.
Programs Completely Written by AUTOSIM
AUTOSIM includes a Fortran library of necessary analysis routines that it uses to
generate complete, ready-to-run simulation programs. A Fortran compiler is all that you
need to use a program generated by AUTOSIM. A complete program consists of a MAIN
section and up to 28 subroutines and functions. A few are standard library functions, but
most are written from scratch for a particular multibody model.
Chapter 2 describes the design of a complete Fortran program written by AUTOSIM.

1.7 Linear Analysis


The equations of motion of a multibody system can be linearized and put into the
form
.
x = A x + B u

(1.7.1)

where x is an array of linear perturbations of the state variables about a set of reference
values, u is an array of input variables, and A and B are matrices with dimensions sized
to match x and u. Also, a set of output variables y can be defined as
y = C x + D u

(1.7.2)

where C and D are matrices with dimensions sized to match y, x, and u.


If computer code is generated to set up these matrices, then a matrix analysis
language such as MATLAB, CONTROL-C, or MATRIX-X can be used to compute
properties of the linearized system such as eigenvalues, eigenvectors, transfer functions,
etc.
The differential equations that describe a multibody system are the kinematical and
dynamical equations. Both sets are nonlinear for most systems with rotating parts, so the
equations must be linearized to obtain the forms shown in eqs. (1.7.1) and (1.7.2). One
method for obtaining linearized equations using AUTOSIM is to derive the elements in
the matrices A, B , C , and D symbolically. AUTOSIM does this by taking partial
derivatives of the coefficients in the arrays s and f from eq. 1.6.7. For example, the
elements of the A matrix are
i
Aij = x
j

(1.7.3)

1.7 Linear Analysis

AUTOSIM 2.0

Equations linearized in this way are valid for any set point. To change the set point,
just change the numerical values of the state variables before computing the matrices.
AUTOSIM includes an option to automatically compute the A matrix, and write the
elements into a file in the form of MATLAB code. The design of MATLAB code
generated by AUTOSIM is described in Chapter 4.
It is sometimes better to obtain the matrices numerically. For complex models, the
linear equations, can much more complicated than the nonlinear equations. (Although
linear matrices are obtained, the nonlinearities of the system are still left in to
accommodate an arbitrary set-point.) Another consideration is that if the model includes
components whose properties are not symbolically differentiable, then AUTOSIM may
not be able to derive the matrices symbolically. The matrices can be obtained numerically
with the subroutine FCT, written for time-simulation runs. By calling this subroutine
repeatedly with perturbations in x and u, the partial derivatives needed for A and B can
be computed.

1.8 Typeset Equations


AUTOSIM can generate a typeset description of a multibody model by printing
documentation and the equations of motion in the Rich Text Format (RTF) format. The
text includes formatting commands for boldface, italics, subscripts, and various margin
styles. For example, equations 1.6.8 and 1.6.10 were generated directly by AUTOSIM
and pasted into this manual, which was prepared with Microsoft Word.

1 19

CHAPTER 2

STAND-ALONE SIMULATION PROGRAMS


2.1 Using the Simulation Program 3
The Parameter File (PARSFILE)
4
The Output Data File (ERD File)
10
Batch Operation
11
2.2 Calculation Methods
12
Solution of Simultaneous Algebraic Equations
13
Integration of Ordinary Differential Equations (ODEs)
2.3 Design of the Stand-Alone Simulation Program 22
Which Language: Fortran or C?
22
State Variables
23
Program Flow and Organization
23
Set Default Values 25
Read Parameter Values from Input Files
25
Initialize the Simulation
26
Simulate the System 27
Operations Performed after each Run35
Batch Operation
35
2.4 C Details 36
Language Version and Style 36
Compiling and Linking a C Program 36
Data Storage in Arrays and Global Structures
37
2.5 Fortran Details 39
Language Version and Style 39
Compiling and Linking a Fortran Program 39
Data Storage in Arrays and Common Blocks 40
2.6 Changing the Simulation Program From Within AUTOSIM
AUTOSIM Variables Affecting the Program Appearance
Breaking Up DIFEQN
44
Include Files 45
Output Files 46

16

42
42

This chapter describes the design of stand-alone programs written by AUTOSIM.

21

AUTOSIM 3
Section 2.1 describes how to use an AUTOSIM-generated simulation program and
Section 2.2 covers the theory of the calculations. If you will be using a simulation
program generated by AUTOSIM, but are not using AUTOSIM itself, you should read
Section 2.1 and perhaps skim Section 2.2.
Section 2.3 covers the design of an AUTOSIM-generated program (in either C or
Fortran). Sections 2.4 and 2.5 cover details that are specific to C and Fortran,
respectively. Section 2.6 describes how the programs can be customized from within
AUTOSIM.
If you are using AUTOSIM to create programs in C or Fortran, at least skim Sections
2.2 and 2.3, and read the subsections on compiling and linking a program in your
language of choice (Section 2.4 or 2.5).
If you are using AUTOSIM to develop models that incorporate external subroutines,
then you should look over the entire chapter, with emphasis on Section 2.3. The final
section is intended for AUTOSIM users who wish to fine-tune the appearance or function
of generated programs. For example, you might wish to change the format of the output
simulation files to work with a plotting or statistics program that has specific input
requirements.

22

AUTOSIM 3

2.1 Using the Simulation Program


Stand-alone simulation programs generated with AUTOSIM are very easy to use. An
AUTOSIM-generated program is basic in operation: it reads input files, performs
numerical calculations, and produces one or more output files. There is little user
interface and there are no graphics. The function of the program is solely to compute the
simulated response of the system to conditions specified in input files, and write the
results into an output file. (See the Introductory Guide to AUTOSIM for a step-by-step
illustration of how the program is run.)
Stand-alone programs can also be combined with the simulation graphical user
interface (SGUI), in which case almost no training is needed to make runs. For example,
see the CarSim Student package (for Windows) that is provided with AUTOSIM and
which can be downloaded from the Internet. (Start with the WWW home page of the
University of Michigan Transportation Research Institute (UMTRI), where AUTOSIM
was developed: http://www.umtri.edu)
The AUTOSIM-generated program is designed to be used in both an interactive and a
batch mode. When used interactively, input and output file names are typed in by the
user. In batch mode, input and output file names are obtained from a single text file. The
batch mode allows a large number of runs to be made at once. It also provides an easy
way to link the program to a graphical preprocessor, such as the SGUI.
First, consider the interactive mode. When you start the program, it prompts you four
times for file names:
1.

an optional file with parameter values and initial conditions is read to override
default values,

2.

an optional file is written to echo all parameter values and initial conditions,

3.

a file is written with the simulated time histories of the output variables, and

4.

an optional file is written to echo all parameter values and the final conditions.

Files 1, 2, and 4 all share the same standard format, and are called PARSFILEs. File 3
either (1) is a plain text file with columns of numbers, or (2) is in a standard format called
an ERD file1. Data in the plain ASCII text files can be viewed with spreadsheet programs
and generic plotting software. ERD files contain labeling information to support
automated plotting and post-processing. (See Section 2.6 for instructions on making the
programs generate other kinds of output files.)
Use a text editor to prepare input files, and post-processing plotting software to view
the data in the output files. Practically speaking, using an AUTOSIM-generated
simulation program is mainly a matter of setting up a proper input text file.

ERD is the Engineering Research Division at UMTRI.

23

2.1 Using the Simulation Program

AUTOSIM 3

The easiest way to start using an AUTOSIM-generated program is to first run it with
no input, just to generate an echo file. The echo file then serves as documentation for the
parameters that define the model, and also as a prototype input file that can be modified
and used for future runs. (The input and echo files are described below.)
The Parameter File (PARSFILE)
The input files read by the simulation program and the echo files written by it are
both in the format called a PARSFILE.
How PARSFILEs are used
Two example PARSFILEs are shown in Listings 2.1.1 and 2.1.2.
Listing 2.1.1. Example input PARSFILE for a vehicle model.
PARSFILE
* Vehicle Description: Baseline Car
a 1.054
apc 1.3
hpc .3
h .53
ix 516
iy 2219
iz 2666
l 2.525
m 1425
ms 1262
PARSFILE Mike:AUTOSIM:10DOFcar:Tire1
id 1
PARSFILE Mike:AUTOSIM:10DOFcar:Suspension2
id 2
PARSFILE Mike:AUTOSIM:10DOFcar:Suspension4
END

The PARSFILE shown in Listing 2.1.1 is typical of an input that you might prepare
for a complex model such as a 3D vehicle handling model. (The example is from the
Macintosh, where folders are delimited by the colon character.) Parameters for
components are contained in separate PARSFILEs: the file Mike:AUTOSIM:
1 0 D O F c a r : S u s p e n s i o n 2 has axle data applied to the front axle, the file
Mike:AUTOSIM:10DOFcar:Suspension4 has axle data to the rear axle, the file
Mike:AUTOSIM:10DOFcar:Tire1 has tire data used for both axles, and so on. This
design allows you to switch to a different component description by changing a single
line. For example, to switch to a different data set for the front suspension, just change
one line to identify a different PARSFILE, e.g., Mike:AUTOSIM:10DOFcar:
Suspension1.

24

2.1 Using the Simulation Program

AUTOSIM 3

Listing 2.1.2. Example echo PARSFILE for the four-bar linkage.


PARSFILE
* Echo file created by:
* Simulation of 4-bar linkage.
* Version created by AUTOSIM 2.0 B7 on May 12, 1992.
* (c) The Regents of The University of Michigan, 1989 - 1992. All right
TITLE Default values
* Input File:
* Run was made 21:14 on Oct
FORMAT binary
IPRINT
STARTT
STEP
STOPT

1
,
0.000000
,
0.500000E-02,
0.500000
,

8, 1992

number of time steps between output printing


simulation start time (s)
simulation time step (s)
simulation stop time (s)

* PARAMETER VALUES
D
500.000
, coefficient in term in negative strut force (?)
F spindle force (N) as function of time (s)
0.000000
, 0.000000
, point in table: (s, m)
0.100000
, 1000.000
, point in table: (s, m)
ENDTABLE
IC
K
MC
XP1
XP2
XP3
XP4
XP5
XP6
XP7
XP8
YP1
YP2
YP3
YP4
YP5
YP6
YP7
YP8

1.00000
60000.0
10.0000
0.100000
0.300000
0.400000
0.450000
0.500000
0.000000
0.300000
0.400000
0.300000
0.500000
0.300000
0.200000
0.210000
0.000000
0.000000
0.000000

,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,

moment of inertia of C (kg-m2)


stiffness coefficient in term in negative stru
mass of C (kg)
X coordinate of pin between A and N (m)
X coordinate of pin between strut and N (m)
X coordinate of pin between A and C (m)
X coordinate of mass center of C (m)
X coordinate of point of force application (m)
X coordinate of pin between B and N (m)
X coordinate of pin between strut and B (m)
X coordinate of pin between B and C (m)
Y coordinate of pin between A and N (m)
Y coordinate of pin between strut and N (m)
Y coordinate of pin between A and C (m)
Y coordinate of mass center of C (m)
Y coordinate of point of force application (m)
Y coordinate of pin between B and N (m)
Y coordinate of pin between strut and B (m)
Y coordinate of pin between B and C (m)

,
,
,
,

(comp.) Abs. Z rot. of A (rad)


(comp.) Z rot. of C rel. to B (rad)
Abs. Z rot. of B (rad)
Abs. Z rot. speed of B (rad/s)

* INITIAL CONDITIONS
Q(1)
Q(2)
Q(3)
U(1)

0.000000
0.000000
0.000000
0.000000

END

25

2.1 Using the Simulation Program

AUTOSIM 3

Listing 2.1.2 shows the PARSFILE made by a simulation program based on the fourbar linkage example. Compare the appearance of the simple input file from Listing 2.1.1
to the computer-generated file of Listing 2.1.2. The similarity is that both are
PARSFILEs, sharing the same syntax. Some of the differences are: (1) the computergenerated echo file lists all parameters for the system, (2) the computer-generated file
includes extra comment lines, (3) the computer-generated file includes a definition for
each parameter, including the engineering units, and (4) the file in Listing 2.1.1 is
deceiving in its simplicity: the three lines beginning with the word PARSFILE refer to
data contained in other PARSFILEs.
The programs generated by AUTSOSIM routinely write a PARSFILE with all
parameter values used in a simulation run. These files serve two main purposes. First,
they echo all of the parameter values used in a simulation run. The listing is a convenient
record of the conditions simulated in a particular run. Documentation of this sort is
important for ensuring that the inputs to the simulation program were as intended. Also,
the documentation can be archived with output results for future reference. The second
purpose of an echo file is to provide an example input file. The echo file in Listing 2.1.2
describes each and every parameter in the model and the simulation code. Because the
echo file has the same PARSFILE format as an input file, it can be used directly as an
input file to the simulation, to repeat the run. More typically, you would edit the echo file
to change some of the parameters, and then use the modified file as an input.
As noted earlier, the easiest way to start using an AUTOSIM-generated program is to
first run it with no input, just to generate an echo file. The echo file then serves as
documentation for the parameters that define the model, and also as a prototype input file
that can be modified and used for future runs.
PARSFILE Reference
Table 2.1.1 summarizes the format of a PARSFILE. When the simulation program
reads a PARSFILE, the first line is checked to see if it begins with the word PARSFILE.
Upper and lower case are ignored (the symbols are converted to upper case by the
simulation program). If the file does not begin this way, an error message is printed, the
file is closed, and you are prompted again for the name of a valid PARSFILE. If the file
does begin with the word PARSFILE, processing continues. Each line in the file is read,
and the first word on each line is checked to see if it matches a keyword programmed in
the simulation program.

26

2.1 Using the Simulation Program

AUTOSIM 3

Table 2.1.1. PARSFILE Format.


Line
Contents
Instruction to Program
1
PARSFILE
Identify this file as a PARSFILE.
.
keyword value
Assign value to a parameter or variable identified
by keyword, or start a table block.
.
PARSFILE filename Open the file named filename and continue
reading from it. When through with filename,
close it and continue with the first file.
PARSFILEs can be nested.
.
miscellaneous
Ignore lines that do not begin with a recognized
keyword unless they are part of a table.
.
ENDTABLE
Stop reading tabular data in a table block.
.
* comment
Ignore lines beginning with asterisks.
last line read END
Stop reading data.
.
miscellaneous
ignore all lines after END.

A keyword is a word consisting of 1 to 32 alphanumeric characters. The end of the


symbol is indicated by white space (spaces and tabs). In the example shown in Listing
2.1.1, TITLE, TESTID, SPEED, STOPT, PARSFILE, and END are keywords. Numbers
following a keyword can be written in free format. The exact position is not critical, nor
is the decimal point for numbers with integer values (even if the number represents a
floating point parameter). Comments can be placed on the same line as the keyword by
putting a comma after the numerical value, as is seen for most of the data in Listing 2.1.2.
Special lines in a PARSFILE are described in more detail below:

END If the keyword is END, no further lines of input are read. The file is
closed, and the simulation is started. The END line is optional, but recommended
for clarity.

Parameters If the keyword is the name of a parameter, then the numerical


value following the keyword is used to replace the current value of that
parameter. If the same keyword appears several times in the file, the most
recently read value is used.

Variables If the keyword is the name of a state variable, then the numerical
value following the keyword is used to set an initial condition. [In Listing 2.1.2,
the state variables are Q(1), Q(2), Q(3), and U(1).] As with parameter values,
multiple occurrences of the same keyword are allowed.
Some systems have computed coordinates, identified as (comp.) in the echo file.
These are given values that satisfy constraint conditions. However, reasonable
starting values are required for the computation procedure to work. If the value
used (either a default or a value from a PARSFILE) is off by too much, you may
get an error message. If this happens, make a better guess and try again.

27

2.1 Using the Simulation Program

AUTOSIM 3

Tables Functions specified in tabular form begin with a keyword associated


with the function, and continue over following lines until the keyword
ENDTABLE is encountered. This way, you dont have to enter the number of
points in the table. The lines that start with a table-related keyword and end with
ENDTABLE make up a table block. Unlike the rest of a PARSFILE, the lines in
a table block must be in the correct order, and there must be no extraneous lines
such as comments or blanks.

ENDTABLE the keyword ENDTABLE indicates the end of a table block.

PARSFILE If the keyword is PARSFILE, the name following the keyword is


interpreted as the name of a second PARSFILE. The second file is opened, and
the simulation program continues to read input data from the second file. When
the END line is encountered in the second file, the simulation program continues
reading from the first file. The effect is the same as if the contents of the second
file were inserted (minus the first and last lines) into the first file, replacing the
line with the PARSFILE keyword.
It is permissible for several levels of nesting to occur. A PARSFILE included
with a PARSFILE keyword can itself contain the PARSFILE keyword, thereby
referencing a third file. There is no built-in limit to the level of nesting allowed.
However, some Fortran compilers limit the number of files that can be open at
once. Even with complex data sets, it is uncommon to have more than three
levels of nested PARSFILEs, so problems with too many open files are not
likely.

Comments Lines beginning with an asterisk * are ignored by the


simulation program and can be safely used to insert comments into the file. Also,
any lines (outside a table block) that begin with a word not recognized as a
keyword are treated as comments.

ID Variables may exist to identify an index that is associated with certain


keywords, as will be described shortly below. The convention is to use the
keyword ID, but other names can be specified by the modeler.

The PARSFILE format is intended to provide a great deal of flexibility in setting up


input files. Multiple files can be linked using the PARSFILE keyword. The files can be of
any length. Keywords can be omitted if values are not known (default values are used
when the simulation starts). The lines in the PARSFILE can be arranged in any order.
The same keyword can appear several times with no adverse effects. Thus, you can
modify an input file by adding data to the end. Later, you return to the original data set by
deleting the lines at the end.
The PARSFILE format is used not only for input, but also for the echo files created
by the simulation program. Regardless of how many PARSFILEs were nested together as
input, the complete data set is written into each PARSFILE produced by the simulation
program.
The simulation program will optionally create a file at the start of the simulation, with
initial values. It will optionally create a file at the end, with final values. The file created

28

2.1 Using the Simulation Program

AUTOSIM 3

at the end of a simulation run can be used as an input for a later run, to restart the
simulation at the point where the first run ended.
Indexed Keywords
Parameters in the multibody model can be identified by simple symbolic names or by
array elements. For example, dimensions in a vehicle suspension model might be
assigned keyword symbols such as DS1 and DS2 (damping rates, front and rear), KS1
and KS2 (stiffness values, front and rear), etc. Alternatively, the front and rear values
might be associated with indexed keywords such as DS(1) and DS(2), KS(1) and KS(2),
etc. As will be seen, indexed parameters and keywords can make it easy for you to
organize your parametric data into files, with each file being associated with one part of
the whole system.
Indexed keywords appear as array elements in an echo file generated by the
simulation program. For example, Listing 2.1.3 shows an excerpt from the echo file
generated from the simulation program that was given the input shown in Listing 2.1.1.
Listing 2.1.3. Excerpt of echo file.

HRC(1)
HRC(2)
IX
IY
IZ
KS(1)
KS(2)
KSWAY(1)
KSWAY(2)

0.860000E-01, height of front suspension roll center (m)


0.685000E-01, height of rear suspension roll center (m)
516.000
, moment of inertia of S (kg-m2)
2219.00
, moment of inertia of S (kg-m2)
2666.00
, moment of inertia of S (kg-m2)
26000.0
, front suspension vertical stiffness (1 wheel) (
26000.0
, rear suspension vertical stiffness (1 wheel) (N
600.000
, auxiliary anti-roll stiffness for front (m-N/r
50.0000
, auxiliary anti-roll stiffness for rear (m-N/ra

There are two ways the value of an indexed parameter can be changed in an input
PARSFILE. First, an indexed keyword can be used. For example, the front anti-roll
stiffness parameter can be set to 100 m-N/rad with the following input line:
ksway(1) 100

The second way of specifying the value is with an auxiliary index variable, nominally ID.
For example, the same effect is obtained with the following:
id 1
ksway 100

The rules are simple for interpreting inputs. If the index is not included in the keyword,
e.g., ksway, then the current value of the auxiliary variable ID is used. However, if the
index is included, e.g., ksway(1), then that index is used, regardless of the current value
of the ID variable.
Consider the file shown in Listing 2.1.4. All of the keywords must be indexed to
indicate whether they apply to the front or rear suspensions of a vehicle model. Since the

29

2.1 Using the Simulation Program

AUTOSIM 3

file contains no index, the values are applied to axle 1 if the current value of ID is 1, or to
axle 2 if the current value of ID is 2. Thus, the suspension data can be applied at either
axle of the vehicle without changing a line in the file. Now, look again at listing 2.1.1.
See how the data in the file suspension2 are applied to axle 1, and the data in file
suspension4 are applied to axle 2. Both of those files have the same keywords as
shown in Listing 2.1.4. The value of the ID variable is reassigned in the file shown in
Listing 2.1.1, to determine how the data in the files suspension2 and suspension4
are interpreted in the context of the vehicle model.
Listing 2.1.4. PARSFILE with no index.
PARSFILE
* suspension data
cs 400
hrc .086
ks 26000
ksway 600
rr .3
b 1.465
END

The Output Data File (ERD File)


There are several formats available for output files containing the predicted time
histories of the simulated system. Table 2.1.2 summarizes these formats. The format is
specified in the input file with the FORMAT keyword.
Two of the output file options follow a format called the ERD file format, developed
within the Engineering Research Division (ERD) at the University of Michigan
Transportation Research Institute. The files are essentially self-documenting and provide
all information needed for labeling plots, determining scale factors, etc. Data in these
files can be viewed with the plotter EP that is provided with AUTOSIM. A plain text
format is also available, to facilitate the use of spreadsheets and generic plotting software.

2 10

2.1 Using the Simulation Program

Option
plain text

text ERD
(Fortran)

text ERD
(C)

binary
ERD

AUTOSIM 3

Table 2.1.2. Summary of output file formats.


FORMAT value Description
When to Use
TEXT
single text file, 1-line
spreadsheets or generic
header followed by table
plotting software will be
of numbers
used to process data
Fortran format,
single text file
data are to be
e.g.,
with full
transferred between
(100G13.6)
labeling, followed computers or
by numbers. NOTE: converted to
the format value
another plotting
must include the
format.
enclosing
parentheses
C format
single test file
data are to be
string,
with full
transferred between
e.g., %f10.4 labeling, followed computers or
by numbers; NOTE: converted to
the format value
another plotting
must start with
format.
the character %
BINARY (or
2 files: text file with
Results will be viewed
none of the labels, binary file with
using Engineering Plotter
above)
data

In addition to the formats summarized in Table 2.1.2, other formats can be specified
for the output files made by AUTOSIM-generated programs. Consider changing the
format if you commonly want to produce files that work better with a different plotter or
analysis package. See section 2.6 for more information.
Batch Operation
AUTOSIM-generated programs can be operated in batch mode. When the program
starts, it looks for a file called SIMFILE. If no such file exists, the program runs
interactively as described above, prompting the user for file names as needed. However,
if the file SIMFILE is found, the program executes automatically, using information from
the file. The SIMFILE is similar to a PARSFILE, but has a limited set of keywords that
are recognized. The keywords are defined in Table 2.1.3 and an example SIMFILE is
shown in Listing 2.1.5. (The line numbers are shown for convenience but do not appear
in the actual file.) The SIMFILE in Listing 2.1.5 causes the simulation program to make
three runs.

2 11

2.1 Using the Simulation Program

Keyword
SIMFILE
INPUT
ECHO
FINAL
ERDFILE
RUN
END

AUTOSIM 3

Table 2.1.3. Keywords in a SIMFILE.


Definition
mandatory first line of SIMFILE, used for verification
name of existing PARSFILE used as input parameter file
name of new echo PARSFILE to be written at the start of the run
name of new final PARSFILE to be written at the end of the run
name of new output file with time histories of output variables
command to start a simulation run, using current file names
command to close SIMFILE and start a simulation run

Line 1 must read SIMFILE (the keywords are all insensitive to case). Line 2 specifies
that the file in is to be used as in input file for the first run. Lines 3 and 4 indicate that an
echo file should be created with the name echo30, and that the output file should be
named out30. Line 5 returns control to the simulation program, which then makes a run.
Because no name was specified for the final echo file, it is omitted. Lines 6 and 7 specify
names for the input file and output file for a second run. Because no file names are
specified for the optional echo files, none will be written. (However, if a file name is not
specified for the mandatory output file, the simulation program prompts the user for a
name.) Lines 9 and 10 indicate file names used for the third run. Again, names are not
specified for the optional echo files, indicating that the files are not to be written.
Listing 2.1.5. Example SIMFILE.
1.
2.
3.
4.
5.

simfile
input in
echo echo30
erdfile out30
run

6.
7.
8.

input in40
erdfile out40
run

9. input in50
10. erdfile out50
11. end

2.2 Calculation Methods


AUTOSIM-generated programs mainly perform two types of numerical calculations:
(1) solution of simultaneous algebraic equations, and (2) integration of ordinary
differential equations (ODEs). The program design is determined in part by the form the
these calculations. This section reviews the methods used to perform the calculations, as
background for the description of the program design in Section 2.3.

2 12

2.2 Calculation Methods

AUTOSIM 3

Solution of Simultaneous Algebraic Equations


Suppose there is a set of n equations with the form
g1 (x1 , x2 , ... xn ) = 0
g2 (x1 , x2 , ... xn ) = 0
...
gn (x1 , x2 , ... xn ) = 0

(2.2.1)

which can be written in matrix form as


g(x, t) = 0

(2.2.2)

If the equations are independent, then there may be enough information to solve for
the variables x if the number of equations equals the number of variables. There are two
solution methods used in AUTOSIM-generated simulation programs, depending on
whether the equations are linear or nonlinear.
Linear Algebra
Linear equations can be put into the form
Ax=b

(2.2.3)

where A is an nn matrix and b is an array of length n. the elements of A and b can be


very complex to calculate, and can include nonlinear functions such as sines and cosines.
However, if they do not involve any of the elements of x, then the equations are linear
with x. An obvious solution is
x = A-1 b

(2.2.4)

A more efficient solution is called lower-upper triangular decomposition (LUD). The


matrix A is written as a product of two matrices, L and U, such that L has a lowertriangular form (all elements above the diagonal are zero), and U has an upper-triangular
form (all elements below the diagonal are zero). The original equation set can be written
in the form:
A x = (L U) x = L (U x) = b

(2.2.5)

and eq. 2.2.5 can be broken into two equation sets:


Ly=b

(2.2.6)

Ux=y

(2.2.7)

The advantage of the above form is that triangular sets of equations can be solved by
sequential substitution. For example, the top row of L is all zeros except for the diagonal
element. Thus, the first equation in eq. 2.2.6 involves just the unknown variable y1,
which can be determined easily. The next row involves y1 and y2. Because y1 now has a
known value, it is easy to solve for y2. By sequential substitution, each equation can be
expressed in terms of a single unknown, which is then computed. A similar strategy is

2 13

2.2 Calculation Methods

AUTOSIM 3

applied to eq. 2.2.7, except that we start from the bottom, where all elements of U are
zeros except the diagonal.
Solution of linear equations by LUD involves two steps: first, the original A matrix is
decomposed into L-U form. This is normally done such that the values of the L and U
matrices occupy the computer storage space originally used to hold the elements of the A
matrix. (Values that are zero or 1 are not stored.) In the second step, eqs. (2.2.6) and
(2.2.7) are solved by forward and backward substitution.
If the equations are formed such that the sequence of the variables in x is arbitrary,
then some ordering is usually performed, so that the diagonal elements of A are, as a
minimum, non-zero. Better yet, the variables in x are ordered such that the diagonals of A
are numerically large relative to the off-diagonal elements. (If the variables cannot be
ordered such that the diagonals of A are non-zero, the equations may be unsolvable.) The
process of ordering the equations is called pivoting.
With AUTOSIM-generated programs, there are two pairs of routines. The
decomposition is performed by routines named LUD and LUD1, and the forwardbackward substitution is done by routines named BKSUB and BKSUB1. The routines
LUD and BKSUB include pivoting. (Pivoting is the searching for numerically large
elements to divide by in the solution process.) The routines LUD1 and BKSUB1 are used
for equations in which the elements of x have been put in a sequence such that pivoting is
unnecessary.
Copies of LUD and BKSUB are needed in some Fortran simulation programs,
because nested sets of equations must be solved and Fortran subroutines are not
recursive. (It is not possible with most Fortran compilers to handle code where subroutine
LUD calls a subroutine that in turn calls LUD.) C functions are recursive, so copies of
LUD and BKSUB are not needed for C programs.
The linear equation solving subroutines are used in AUTOSIM-generated programs
for two reasons. First, the LUD1 and BKSUB1 routines are used to uncouple the
equations of motion if the modeler chose to do this numerically rather than symbolically
with an optional keyword argument in the dynamics command. The other reason is that
the general LUD and BKSUB routines (with pivoting) are used as part of the process of
solving nonlinear algebraic equations, as described in the next subsection.
Nonlinear Algebraic Equations
Nonlinear algebraic equations, expressed as
g(x, t) = 0

(2.2.8)

can often be solved iteratively if (1) a solution exists, and (2) an initial guess is provided
for x that is reasonably close to the right answer. The Newton-Raphson method is used in
AUTOSIM-generated programs. This method is described below. The subscript index i
indicates the iteration number (initially, i=0).
1.

guess values for [x1, x2 , ... xn ] = xi for i=0

2.

compute -gi
2 14

2.2 Calculation Methods

3.

AUTOSIM 3

a.

If all |gj | < (j=1,n), where is an error threshold, then STOP. The
solution is xi.

b.

Otherwise, continue...

compute the Jacobian matrix Ji, where each element is defined as


(Jj,k)i =

4.

g j
x k i

solve for xi using the LUD method and the equation set:
Ji xi = gi

5.

(2.2.9)

(2.2.10)

update the best guess of solution:


xi+1 xi + xi

6.

increment i (i i+1), then GO TO step 2.

There are three sets of nonlinear algebraic equations that can be generated by
AUTOSIM for a multibody system. First, there may be nonlinear constraint equations
that implicitly define some of the generalized coordinates for the system as dependent
functions of the independent coordinates. The variables are called computed coordinates
in this manual, and they can be computed using the Newton-Raphson method. Second,
when AUTOSIM generates an equilibrium simulation, the describing equations are a set
of simultaneous algebraic equations that are satisfied when the system is in equilibrium.
Third, the stiff integration method described in the next section requires that a set of
simultaneous equations be generated and solved each time step.
It is possible that the Newton-Raphson subroutines will fail to find a solution. There
are two reasons that this might happen: (1) there might not be a physically possible
solution, or (2) the initial guess may be too far away from the solution, and the iteration
will not converge.
When might there not be a solution? In the case of the geometric constraint equations,
it might be that the parameter values specified for dimensions would make it impossible
to assemble the system. For example, it is not possible to assemble a four-bar linkage
with four bars if one of them is longer than the sum of the lengths of the other three. In
the case of an equilibrium calculation, the system may not have an equilibrium solution.
If a solution exists, but is not found, the problem usually occurs right away when the
program tries to establish the condition at the start of the simulation run. The geometric
constraint equations often involve sines and cosines of computed coordinates that are
angles. If the initial estimates of the angles are off significantly, the Jacobians (see eq.
2.2.9) can send the correction in the wrong direction. When modeling systems,
problems with initial configurations can be reduced by describing the system such that
the nominal configuration (when all coordinates are zero) is one in which the parts are
assembled.

2 15

2.2 Calculation Methods

AUTOSIM 3

Integration of Ordinary Differential Equations (ODEs)


The equations of motion derived by AUTOSIM for a multibody system are in the
form of a set of first-order, ordinary differential equations (ODEs):
.
x = (x, t)

(2.2.11)

where x is an array of state variables, and (x, t) is an array of expressions used to


compute the derivatives of x as functions of parameters, time, the state variables, and
auxiliary variables that are specific to a particular model. The equations are linear with
respect to the derivatives but may be nonlinear with respect to the state variables. The
method used to compute the state variables over time is called numerical integration. The
numerical integration is started with known values of x at time t=t1 . Therefore, the
process is called the initial value solution of ODEs. Using numerical methods, the
derivatives are integrated over small intervals of time as needed to compute the values at
time t 1+ t, given values at time t1. The concept is shown in Figure 2.2.1 for the simplest
method, called Euler integration.
x(time)
.
slope = x(t1)
.
x(t1) + tx(t 1)

True function
x(t)

x(t1+ t)
x(t1)

t1

t1+ t

time
Figure 2.2.1. Numerical integration with Eulers method.
A discussion of the many types of integration methods that can be used to
numerically solve ODEs with initial values is well beyond the scope of this manual.
However, the important features of the integrators provided with AUTOSIM will be
described below.
Variable Step Methods
Each integration algorithm assumes a behavior of the variables being computed. For
example, the Euler integration assumes that the function x(t) is a straight line. Other
methods assume the function is a polynomial. The deviation of the true function x(t) from

2 16

2.2 Calculation Methods

AUTOSIM 3

the assumed shape leads to an error, as can be seen in Figure 2.2.1. The error is reduced
by making the time step t smaller.
There is a fundamental trade-off in selecting the integration step size. The
computation time is inversely proportional to t. Obviously, the simulation runs faster
with larger values of t. However, the accuracy suffers if t is too large. When the value
for t is much too large, the integration algorithm may be unstable, causing the
simulation program to generate huge numbers that cause numerical overflow. When this
happens, users typically say the simulation blew up.
There is often not a single optimal value of t for an entire run. If the system is
subjected to step input, a short time step is needed at the start of the run, but a longer step
could be used at the end of the run when things have settled.
Variable-step integrators change t to maintain some predetermined accuracy level.
They monitor the integration error, usually by performing the integration with two
different methods and comparing the results. If the integration error is unacceptable, the
step size is cut and the integrator tries again. However, if the integration error is
negligible, the integrator may increase the time step to speed up the run. Figure 2.2.2
shows how the time step might be changed during a run in which a system responds to a
step input. Each vertical dotted line in the figure indicates one integration interval.
X(t)
t

t
Figure 2.2.2. Numerical integration with a variable time step t.
There is an overhead associated with checking the integration accuracy. If the
integration parameters will be set such that the integrator seldom changes the step size,
then better performance may be possible with a fixed-step method.
Order of the Integrator
The exact relationship between t and the integration error depends on the nature of
the equations. Integration algorithms are conventionally analyzed for a sinusoid to
develop a relationship between t and the integration error. If the error is roughly
proportional to ( t)n, then the method is considered to be of order n-1. For example, the
integration error for the Euler integration shown in Figure 2.2.1 is approximately
proportional to ( t)2. Thus, the Euler method is described as being of order 1 .

2 17

2.2 Calculation Methods

AUTOSIM 3

Higher-order methods require that the derivatives of the state variables be calculated
more than once per time step, in order to account for the curvature of the function over
the time step. Some use values computed at previous times to predict where the function
will be; other require multiple calculations within the interval. In general, a higher-order
method requires more computation for a given step size than would a lower-order
method. The benefit of the higher-order method is that the simulation can be run with a
much larger step size, requiring fewer integration steps per simulation run.
Higher-order methods are well suited for systems with smooth ODEs that are well
approximated by the smooth polynomials implicitly assumed in the integration methods.
They obtain a given level of accuracy with a much larger step size than would be required
with a low-order method. Systems whose ODEs are not smooth are not approximated
well by high-order polynomials, and the integrators often cut the step size to about the
same interval that would be used for a low-order system. For these systems, a low-order
method runs faster. Note that the ODEs for a multibody system include the system
dynamics and the excitation to the system. The responses of systems with discontinuous
behavior, due to friction, lash, or other mechanical elements, or, systems subjected to
discontinuous inputs, are often handled better with low-order integrators.
Some variable-step integration algorithms are also variable order. They change their
order on the fly, based on a monitoring of how the integration error changes with step
size. When the system is behaving smoothly, they use a high-order approximation to
permit the use of a relatively large step size. When discontinuities are significant, they cut
the step size and switch to a low-order formulation that reduces the computation per step.
Stiff Integrators
If a dynamic system has a large spread in frequency between its eigenvalues, say,
several orders of magnitude, then it is numerically stiff. For example, a model of an
automobile used to simulate handling performance might have resonance frequencies of
several hundred cycles/sec if the model includes links in the suspensions and compliant
bushings that connect them to the main body. The time step for an integrator such as
Euler must be set to handle the highest significant eigenvalue in the system. A step size
as small as 0.0001 sec might be needed for the automotive example. However, the
handling performance is dominated by response characteristics with much longer
response times, typically of several seconds. Thus, we would be using a step size of
0.0001 sec to study response properties involving less than one cycle/sec. If the high
frequencies were not present, a step size of 0.02 would be more typical, and the
simulation would run 200 times faster.
Figure 2.2.3 shows the problem posed by a stiff system. In the figure, it is the lowfrequency response that we are interested in. Given the initial values at time t 1, the initial
slope might be numerically very large due to the presence of the stiff elements in the
model. In the automotive example, a small amount of numerical error in the state
variables might imply a large force being generated by a stiff spring. As the figure shows,
the high-frequency response lasts only a short time. After the initial transient decays, the
response is dominated by the low-frequency behavior of interest.

2 18

2.2 Calculation Methods

X(t)

AUTOSIM 3
large time step
OK for low-frequency
response

small time step


needed for highfrequency
transient

high-frequency
transient response to
numerical round-off,
integration error, etc.
. t
.
explicit integrator uses x 1
implicit integrator uses x
at start of interval
at end of interval
Figure 2.2.3. Time history of a state variable in a stiff system.
If the integration method uses the derivatives at the start of the integration interval to
project forward, a very small step size is needed to properly integrate the high-frequency
transient. Alternatively, suppose we use the derivatives at the end of the interval. By then,
any high-frequency transient has decayed, and the derivative is dominated by the lowfrequency trend of interest. The problem is, we cant calculate the derivatives at the end
of the interval unless we know the values of the state variables at the end of the interval.
However, the values of the state variables are the result of projecting an average
derivative over the step. We have a problem that has a solution that must be obtained
implicitly. In contrast, integrators that always compute derivatives from known values of
the state variables are called explicit.
With an implicit integrator, the derivatives and the state variables at the end of the
time step are obtained through iteration. The integration approximation is used to replace
the ODEs with algebraic equations, which are solved with the Newton-Raphson method
or an equivalent. The Jacobian is defined theoretically as:
(Jj,k)i =

j
.
x ki

(2.2.12)

In practice, it is usually computed numerically through perturbation.


The success of the integration is determined when the integration rule is satisfied by
the computed values of the state variables and their derivatives at the end of the time step.
Implicit integrators can drastically speed up the run times for simulations of models
that are stiff, by permitting the user to run with time steps appropriate for the lowfrequency behavior of interest, rather than high-frequency modes that may be in the
model. However, be aware that the implicit methods are only valid if the high-frequency
transients decay as was shown in Figure 2.2.3. If the high-frequency eigenvalues are
undamped, then incorrect results can be obtained. Figure 2.2.4 illustrates approximately
the types of eigenvalues that can and cannot be handled with implicit integrators.

2 19

2.2 Calculation Methods

AUTOSIM 3

Stiff integrator doesn't work for


undamped, high frequencies

Im

Stiff integrator
handles damped high
frequencies

Eigenvalues
of interest
Re
Figure 2.2.4. Effect of high-frequency damping on implicit integrators.
One warning about implicit integrators: if the system does include high-frequency,
undamped eigenvalues, the integrator may converge to an incorrect solution. In general,
the integration is stable, but not necessarily accurate.
If a system has high-frequency eigenvalues that are undamped (or lightly damped),
then they cannot be legitimately left out of the simulation. It may be necessary to handle
this kind of system model by brute force: use a sufficiently small integration time step.
Integration Options with AUTOSIM
When creating a stand-alone simulation program with AUTOSIM, you have a choice
of two integration subroutines. One uses only a simple second-order Runge-Kutta
integrator (RK2) that is particularly good for non-stiff vehicle models and for real-time
simulation applications. The other subroutine1 is capable of employing four different
integration algorithms that are summarized in Table 2.2.1.
The choice of which integrator to use is made at run-time, based on an input
parameter (INTOPT) set by the user. Note that the RK2 method is an option under the
comprehensive integrator. Thus, one might wonder why the comprehensive integrator is
not used exclusively. The reason is that the more complex integration methods may be
unsuited for some models. For example, if the modeler has added external subroutines
that assume a constant time interval between calls, the multi-step methods can give
incorrect results. By sticking with the simpler RK2 option, a modeler can prevent the end
user from choosing a multi-step method.
Hundreds of numerical integration algorithms exist (Euler, Runge-Kutta, PredictorCorrector, Gear, etc.). The choice of which to use depends on the characteristics of the
system being simulated, the uses to be made of the results, and personal preferences of
the engineers developing the software. Specialized integration routines are available from

Gear, C.W. Numerical Initial Value Problems in Ordinary Differential Equations. 1971, PrenticeHall. Englewood Cliffs, N.J.

2 20

2.2 Calculation Methods

AUTOSIM 3

Table 2.2.1. Summary of AUTOSIM Integrators.


Adams
Gear #1
Gear #2
Step size
variable
variable
variable
Order of integrator
variable: 1-6 variable: 1-6 variable: 1-6
Explicit or implicit
explicit
implicit
implicit
Jacobian update
none
conditional
always
Error monitorimg
yes
yes
yes
Stiff models
very slow
fastest,
fast, stable
sometimes
unstable
Real-time simulation
no
no
no
Continuous jagged
slow
slow
slow
excitation
Smooth model elements
fast
fast
fast
and smooth excitation
transient or free-response
fast
fast
fast
simulation runs

RK2
fixed
2
explicit
none
no
very slow

yes
fast
slow
slow

a variety of sources. If you wish to use a different integration method, then go ahead and
modify or replace the INTEQS subroutine provided with AUTOSIM.
Differential Algebraic Equations (DAEs)
Unlike most other multibody simulation programs, AUTOSIM does not generate
differential-algebraic equations (DAEs), which require special solvers. The ODEs
generated by AUTOSIM can be solved efficiently with methods that were developed
centuries ago, and with ODE integrators from nearly any scientific library or simulation
language (MATLAB, ACSL, ADSIM, etc.). Also, when equations of motion are derived
in simple ODE form, it is easy to generate numerically linearized equations for modal
analysis, stability studies, and controller design.
Research and development of many of the newer integration methods have been
motivated by numerical problems inherent in certain types of equations, particularly
DAEs. The equations generated by AUTOSIM are generally well behaved. They are
explicit, generally nonsingular, not stiff (unless the system model is itself stiff), and
minimal in number. Thus, algorithms that address problems inherent with types of
equations associated with other dynamics formalisms are not only unnecessary, but are
in some cases undesirable because they are less efficient for the ODEs produced by
AUTOSIM.

2.3 Design of the Stand-Alone Simulation Program


This section describes the design and layout of a complete simulation program
generated by AUTOSIM. This layout should be understood in principle if you are using
2 21

2.3 Design of the Simulation Program

AUTOSIM 3

AUTOSIM to generate the program, particularly if you will be including external


routines. If you are interested in the finer details of the program structure, look over the
simulation programs provided as examples with the AUTOSIM software. These
programs are generally well-commented and provide the examples that complement the
reference material contained in this section of the manual.
Which Language: Fortran or C?
Fortran is the traditional language for performing numerical calculations needed in
simulation programs. Since the 1970s, good Fortran compilers have been capable of
performing considerable code optimizations to obtain rapid runtime performance. On the
other hand, C has become the primary general-purpose programming language for all
kinds of computers. The programmer has many more tools and compilers available for C
than for Fortran. Young engineers are more likely to be trained in C than Fortran.
The performance advantages of Fortran may no longer exist. Some modern C
compilers include the same levels of optimization, and can generate programs that run as
fast or faster than the Fortran equivalent. However, a considerable amount of Fortran
code is available for numerical analysis that has as yet no counterpart in C. There are free
libraries with Fortran source code for integrating ordinary differential equations,
performing linear analyses, and performing many other complicated numerical analyses.
Many of these libraries can be used with AUTOSIM-generated Fortran programs.
The same design is used for AUTOSIM-generated programs for both Fortran and C.
The main considerations in choosing a language, in order of importance, are:
1.

Do you need to link with other software? If so, you may not have a choice
choose the language needed for integrating with the other software.

2.

Which language do you like? If you only know one language, use it.

3.

If neither of the above considerations is important, then choose C. C compilers


are cheaper than Fortran ones and are better supported. Integration with other
software most often requires programming in C. If you turn over your work to
another engineer, it is more likely that the new engineer will prefer C.

For large models, the source code generated by AUTOSIM may be lengthy.
(Programs have been generated that exceed a 100,000 lines of code.) Some PC compilers
will fail to compile the code in very large files. In general, it will be necessary to use a
32-bit compiler. It may also be necessary to break up large files into smaller once.
Further, some compilers that work well with small programs are less suitable for larger
ones. This may be one area where Fortran still has an edge. To date, there have been
more problems involving large programs reported with C compilers than Fortran.
In this section, names of routines are always shown in upper case, as they appear in
Fortran (e.g., DIFEQN). The names appear in lower case in C (e.g., difeqn).

2 22

2.3 Design of the Simulation Program

AUTOSIM 3

State Variables
The state variables and their derivatives are declared in the program as arrays.
Different sets of state variables are needed for certain calculations. The Newton-Raphson
calculations require access to independent and dependent generalized coordinates.
Numerical integration calculation algorithms require an array of independent state
variables.
Figure 2.3.1 shows three sets of variables: (1) the computed coordinates, qcc; (2) the
independent coordinates, qic; and (3) the generalized speeds, u. The groups qcc and qic
together make up the generalized coordinates; the group qic and u make up a set of
independent state variables; and the groups qcc, qic, and u make up the entire set of state
variables. All three groups are contained in an array Q that is defined at the top level of
the program (in the MAIN section).
computed
coordinates
qcc

independent
coordinates generalized speeds
qic

Q(NCOORD)
U(NSPEED)
Q(NTOT)
Figure 2.3.1. Equivalence of arrays and state variables.

Depending on settings made in AUTOSIM by the modeler, the computed coordinates


might have derivatives that are integrated or they might not.
Several of the AUTOSIM-generated routines between Q and U arrays for readability.
Others do not. To accommodate both styles, the first element of the U array is mapped
onto the NCOORD+1 element of the Q array. (The same is done with the derivative
arrays, QP and UP.
Program Flow and Organization
The program flow is controlled in the MAIN program. Also, the state variables and
their derivatives are declared as arrays Q and QP in MAIN.
Figure 2.3.2 shows the flow chart for the simulation program. There are five basic
tasks that the software must perform, and these are described in more detail below.

2 23

2.3 Design of the Simulation Program

AUTOSIM 3

START

SET DEFAULTS

INPUT

Set default parameters values

Read files with parameter values and


known functions of time

INITIALIZE

Set initial conditions, start output


file, and write parameters and
initial conditions into an echo file

SIMULATE

Step through simulated time,


compute response variables, write
variables into output file

FINISH

Close files, write final conditions in


echo file

QUIT
Figure 2.3.2. Flow chart for a simulation program.

Table 2.3.1 lists the program modules generated by AUTOSIM. Each is customwritten by AUTOSIM for each model. The subroutine names shown in bold face are the
ones that perform specialized computations for a specific multibody system model. The
Where column in the table indicates the calling sequence of the modules. For example,
DIFEQN is called from FCT, which is called from INTEQS, which is called from MAIN.
Table 2.3.1. Program modules in simulation program.
Program Module
Where
Description
MAIN
control flow of simulation program
DFEQi
DIFEQN D part of DIFEQN, created for big models

2 24

2.3 Design of the Simulation Program


DIFEQN(T, Q, QP, U, UP)
ECHO(IFILE, Q, U, WHEN, FNM)
FCT(T, Y, YP)
FINISH(T, Q, QP, U, UP)
INIT(T, Q, U)
INITNR(T, Q, JAC, ERRF)
INPUT(Q, U, FNAME)
INTEQS(T, Y, YP)
NEWTR1(T, Q)
OPNOUT(IFILE, FNOUT)
OUTPUT(IFILE, T, Q, QP, U, UP)
PDRV1(T, Y, YP, STARTT)
PEDERV(T, Y, PW)
PRECMP
QUASI(T, Q, JAC, ERRF)
QUASI2(T, Q, ERRF)

AUTOSIM 3

FCT
MAIN
INTEQS
MAIN
MAIN
NEWTR1
MAIN
MAIN
INIT
MAIN
MAIN
UPDATE
GEAR
INIT
FCT
QUASI
MAIN
MAIN

D
D
E
E

compute QP and UP given T, Q, and U


create file with echo of input data
interface to DIFEQN
perform analyses after the run
convert units and perform initializations
compute coefficients for NEWTR1
read parameters and initial conditions
integrate equations of motion
solve for initial conditions
create output file and write header
write variables at time T
compute Jacobian for Gear integrator
return Jacobian for Gear integrator
pre-compute constants used in run
compute equilibrium Jacobian & error
compute equilibrium errors
set default values
perform update operations

SETDEF(Q, U)
UPDATE(T, Q, QP, U, UP)
NOTES:
D=used only in dynamics simulation, E=used only in equilibrium simulation, C=used only for
models with computed coordinates

In Fortran, all of the routines shown in the table are subroutines. In C, they are all
functions that return no value (void).
Set Default Values
Upon starting, the MAIN module prints a message on the screen, and then calls
SETDEF to set default values of parameters and system variables. This is done so that
every parameter and variable in the simulation program has a default value to be used if
no input is provided by the user. A significant factor in the perception by the user of the
friendliness of the simulation program is the extent to which the default behavior matches
expectations. Thus, if you are a modeler, you should define default conditions that are
typical for the multibody system model. By looking at the echo file and plotted outputs,
the user can quickly see the intended use of the program.
Read Parameter Values from Input Files
After default values are assigned, subroutine INPUT prompts the user for the name of
an input PARSFILE. The method used by INPUT to read through a PARSFILE was
detailed in Section 2.1.

2 25

2.3 Design of the Simulation Program

AUTOSIM 3

Initialize the Simulation


After all inputs have been read, several tasks are performed in preparation for the
simulation computations. The MAIN program block calls subroutine INIT, ECHO, and
OPNOUT to make the preparations (see Figure 2.3.3).

INIT
Convert Units
PRECMP
NEWTR1
Initialize
subroutines,
tables, etc.
ECHO
OPNOUT

Pre-compute expressions involving


parameters and other constants
Compute valid starting position of
parts in multibody system based on
positions of independent coordinates

Create file and write all parameter


values used for this run.
Create file with simulation variables
and write header information

Figure 2.3.3. Flowchart for the PREPARE task.


INIT performs most of the initializations. It performs computations that must be made
after all parameters have been assigned values, but before the simulation starts. The INIT
routine first converts parameter and initial condition variables from user units (lbm, deg,
etc.) to dynamics units (lb-sec2/in, rad, etc.) with appropriate scale factors. Next, it calls
PRECMP to pre-compute terms appearing in the equations of motion. After that, INIT
calls NEWTR1 to determine initial values for computed coordinates, as will be described
in more detail below. Finally, INIT calls any external initialization subroutines that were
specified by the modeler.
The ECHO routine optionally writes a PARSFILE listing all of the parameter values
and initial conditions for the run. In interactive mode, ECHO prompts the user for a file
name. The subroutine either creates an echo file, or returns without doing anything, based
on the response of the user to the prompt for a file name. In batch mode, ECHO creates a
file if a name was specified in the SIMFILE.
OPNFIL starts the simulation output file(s). The user is prompted for a file name.
This file is mandatory. If the predicted time histories are to be stored in binary format, the
header file is written and closed, and a binary file is then opened for results written as the
simulation proceeds. For an ASCII text file, the header information is written and the file
is left open.

2 26

2.3 Design of the Simulation Program

AUTOSIM 3

The NEWTR1 routine is used when the multibody system position configuration is
described by dependent computed coordinates, related to the independent coordinates by
nonlinear constraint equations of the form
g(q, t) = 0

(2.3.1)

where g is an array of constraint errors with units of length or rad, and q is an array
composed of the computed coordinates and the independent generalized coordinates,
qT = [qccT qicT]

(2.3.2)

where qcc is an array of computed coordinates and qic is an array of independent


coordinates. The arrays g and qcc have the same number of elements. Each equation in
eq. 2.3.1 is due to a physical kinematic constraint, such as requiring two points on
different rigid bodies to coincide.
NEWTR1 performs the calculations using the Newton-Raphson method described in
Section 2.2, and illustrated by the flowchart in Figure 2.3.4. The routine takes as
arguments the time T and the array Q, which corresponds to q in the equations above.
The elements in Q are defined such that the computed coordinates are first, followed by
the independent coordinates, as indicated in eq. 2.3.2. The method is to compute the
errors using eq. 2.3.1 to evaluate the current values of q cc. If the values are not
acceptably close to zero, then the computed coordinates are adjusted by solving the
linearized set of algebraic equations
Simulate the System
The simulation is performed by numerically solving the equations of motion of the
mechanical system over and over, in a loop. Figure 2.3.5 shows the flow chart for this
part of the simulation program. This flowchart applies to all AUTOSIM-generated
simulations. There are three types of simulation that are represented by the flowchart:
dynamics, equilibrium, and kinematics.

2 27

2.3 Design of the Simulation Program

AUTOSIM 3

initial values of computed


coordinates

Compute constraint
errors and Jacobian

INITNR
Errors
OK?
yes

BKSUB

no

LUD

Solve linearized
constraint equations
for changes in
computed
coordinates

new values of computed


coordinates
Figure 2.3.4. Flowchart for NEWTR1.
In all three types of simulations, the program steps through time, using two nested
loops. The inner loop is run when the time variable T is incremented by DT. Each cycle,
the routines INTEQS, FCT, and UPDATE are executed once. (The FCT routine is an
interface that calls DIFEQN for kinematics and dynamics simulations.) In the outer loop,
at some multiple of DT, variables of interest are written into the output file by OUTPUT.
(The output file is the one opened earlier by OPNOUT when the program initializes.)
The routines FCT (and DIFEQN), UPDATE, and OUTPUT have access to the same
arguments and global data structures. The reason that the SIMULATE block is divided
into separate modules is because the computations provided by each are needed at
different intervals, particularly in the case of a dynamics simulation. The routines are
always called in the same sequence: FCT, UPDATE, and then OUTPUT. Variables that
are computed in FCT are also available in UPDATE and OUTPUT. Similarly, variables
computed in UPDATE are available for use in OUTPUT.
The result of a simulation run is usually the output file. Thus, the calls to routines
INTEQS, FCT, and UPDATE exist to support the computation and writing of output
variables in OUTPUT. The output variables can include motion variables, amplitudes of
forces and moments, variables derived from state variables, and other variables that the
modeler may think up. The time interval between samples in the output file is a multiple
of the time step. Depending on the type of simulation program, together with
requirements of any post-processing software, the multiple can be as small as 1, or as
large as several hundred. Typically, the multiple is 1 for kinematic and equilibrium
simulations, and between 2 and 100 for dynamic simulations.

2 28

2.3 Design of the Simulation Program

INTEQS

AUTOSIM 3

D: Integrate differential equations


E, K: do nothing

T T + DT
FCT
(DIFEQN)

D: Calculate derivatives
E: Calculate equilibrium conditions
K: Calculate computed coordinates and auxiliary terms

UPDATE

D,E,K: Update auxiliary variables,


D: Calculate computed coordinates

Write?
no
yes
OUTPUT

Done?
no
yes

Write variables to file for time T

NOTES: D = dynamics simulation


E = equilibrium simulation
K = kinematics simulation

Figure 2.3.5. Flow chart for SIMULATE block.


As indicated in the flowchart, the routines INTEQS, FCT and UPDATE perform
different functions depending on the type of simulation. The structure of the program is
kept the same for the different types of simulations, to make it easier to use the same
AUTOSIM input description to generate related simulations. Also, the similarities in the
different types of simulation programs mean that if you have learned how one type
works, it might be easier to understand the others.
Kinematical Simulation Programs
A multibody system model with zero degrees of freedom (DOF) is called a
kinematical model because the motions are determined solely by considerations of the
geometry of the moving parts. This type of model can also be used to compute forces and
moments required to cause the motions. An analysis of reaction forces and moments for a
0-DOF system is sometimes called inverse dynamics. (To create an inverse dynamics
program, specify the desired reaction forces and moments as output variables using the
AUTOSIM functions rfvect and rmvect.)

2 29

2.3 Design of the Simulation Program

AUTOSIM 3

In a kinematical simulation, both FCT and UPDATE are called each time step. FCT
in turn calls DIFEQN, which may contain equations for the system. INTEQS is a dummy
routine that does nothing. If the system model includes computed coordinates, they are
calculated in DIFEQN before any other calculations are made. The Newton-Raphson
routine NEWTR1, used to establish the initial conditions in the initialization, is used here
also. If all of the output variables are geometric quantities, then DIFEQN may contain no
other equations, and UPDATE may be empty. Any calculations made in DIFEQN or
UPDATE are made to support the calculation of output variables in routine OUTPUT. In
a simulation of this nature, there is seldom a reason to use a print interval that is not the
same as the time step. Thus, OUPUT is typically called each time step.
AUTOSIM can be used to create generic simulation programs that simply compute
output variables that are not necessarily related to a multibody system. For example, if
you want a computer program to compute ten variables as functions of a set of eight
parameters (and time), you can enter the equations for the ten variables into AUTOSIM
(use the add-out command). AUTOSIM will generate a complete program that permits
the parameters to be changed easily, and which generates output files in the output file
formats described in Section 2.1. The INTEQS, DIFEQN, and UPDATE routines in this
case would be empty dummy routines that do nothing.
Dynamical Simulation Programs
If the multibody system has dynamical DOF, then the describing equations include
ordinary differential equations (ODEs) that are integrated by the INTEQS routine. To
perform the integration, it makes use of FCT to compute values of the state variable
derivatives for various values of time and candidate values for the state variables. Each
time step, routine INTEQS calls FCT at least once. This is in addition to the call to FCT
shown in Figure 2.3.5.
FCT in turn calls DIFEQN, which actually performs the computations. The reason
that FCT is used to call DIFEQN is that for purposes of integrating generic ODEs, all
state variables are represented in a single array in INTEQ and FCT. However, to make
the equations more readable, the state variables are divided into generalized coordinates
and generalized speeds in DIFEQN. The FCT routine contains one line of code to
properly interface the argument list of DIFEQN to the requirements of INTEQS.
For all but the most simple models, the major computation effort is spent in routines
DIFEQN, UPDATE, and OUTPUT. Figure 2.3.6 shows approximately the frequencies at
which these routines are invoked with a variable-step integrator. It shows the frequency
of calls to DIFEQN varying between time steps, as needed to obtain a required numerical
accuracy. Regardless of the integration algorithms, the UPDATE routine is called once
per time step, and the OUTPUT routine is called at some multiple of the time step.

2 30

2.3 Design of the Simulation Program

AUTOSIM 3

Simulation Time
DT
Calls to DIFEQN
Calls to UPDATE
Calls to OUTPUT
Figure 2.3.6. Example frequency of in-the-loop tasks.
The routine DIFEQN computes as output the derivatives of the state variables for
time T, given as input the values of state variables and the value of T. The operations
performed in DIFEQN are shown in
block form in Figure 2.3.7. (To fully
START
understand the operation of DIFEQN, it
given Q, U, T
is helpful to study the source code for
one of the example programs provided
with AUTOSIM.) Because DIFEQN is
1. Compute trig
used so much more than the other
functions
routines, AUTOSIM minimizes the
computations performed in it. Generally,
only the equations needed to compute the
2. Call external KINEMATICS
derivatives of the state variables are
subroutines
contained in DIFEQN.
Starting with values of generalized
coordinates in array Q (angles and
displacements), generalized speeds in
array U (rotational and translational
speeds), and time T, DIFEQN computes
values of the derivatives of the
generalized coordinates and speeds,
putting the results in arrays QP and UP,
respectively.

3. Apply kinematical equations,


compute QP

4. Call external DIFEQN


subroutines

5. Compute forces and


moments

The first step is to compute sines and


cosines of state variables that are angles.
These are assigned to elements of arrays
S and C, to avoid repeated computation
of trigonometric functions.
In the second step, which is optional,
auxiliary routines that were explicitly
added by the modeler to the section
KINEMATICS are called. External
routines would be used here if the system

6. Apply dynamical equations,


compute UP
RETURN
have QP, UP,
trigs, Z's
Figure 2.3.7. Flow chart for subroutine
DIFEQN.

2 31

2.3 Design of the Simulation Program

AUTOSIM 3

is subject to prescribed motions, where some of the motions are defined by external
routines. In this case, external routines are needed to compute speeds that are in turn
needed to compute the derivatives of the generalized coordinates.
In the third step, the values of the derivatives of the generalized coordinates are
computed, using values of Q, C, S, U, and output variables from the external routines.
In the fourth step, which is optional, auxiliary routines that were added by the
modeler for section DIFEQN are called. The main reason that such routines might be
used is to compute variables that determine amplitudes of forces and moments in the
system.
In step 5, amplitudes for all forces and moments are computed.
Finally, in step 6, the derivatives of the generalized speeds are obtained.

The UPDATE routine performs two potential functions.


A major purpose of routine UPDATE is to handle any operations that must be
performed once per time step. For example, the model may require external routines that
read values from files, or remember histories of system variables to compute forces and
moments. Also, the UPDATE routine is the only place in the simulation code where all
derivatives of state variables are available each time step. Routines that require values of
accelerations (derivatives of speed) should be placed here, rather than in DIFEQN. If you
want to stop the simulation run when some condition is reached, the place to put the
check for the stop condition is in UPDATE. Stop the run by changing the simulation
variable STOPT to a value less than or equal to T.
Periodic updating is also necessary for hardware in the loop. Once per time step, a
routine is invoked that communicates with hardware, passing computed values to the
digital/analog converter (D/A), and grabbing new values of input variables from the
analog/digital converter (A/D). This routine, if there is one, should be called from within
UPDATE.
UPDATE also contains code generated by AUTOSIM in the event that the multibody
model includes computed coordinates, defined implicitly by eq. 2.3.1. Given that (1) the
initial values of the computed coordinates are established to a close tolerance by routine
NEWTR1 during the initialization, and (2) the differential equations for the computed
coordinates are integrated within a close tolerance at each time step, it turns out that the
normal integration algorithm is fine for simulations covering a limited number of
integration steps. However, for simulations covering thousands of steps, the minuscule
integration error each time step can accumulate, such that the parts in the simulated
multibody system can drift very slowly with time. To prevent this, the computed
coordinates are corrected each time step in routine UPDATE. There are two methods that
can be used to compute these dependent coordinates. (The choice of methods is
determined by the value of the global AUTOSIM variable *fast-computedcoordinates* when the equations are derived.)

2 32

2.3 Design of the Simulation Program

AUTOSIM 3

One method is to use the full Newton-Raphson method, as was done during the
initialization, with routine NEWTR1. Because the current values of the computed
coordinates are very close to the correct values, the NEWTR1 routine never iterates more
than once unless the system is near a singularity. The full Newton-Raphson iteration is
used if the global *fast-computed-coordinates* had a value of NIL when the
analysis was performed.
The second method uses an approximation that is valid for most multibody systems,
and which is computationally faster. It uses correction equations with the form:
gi
qi qi J

ii

(2.3.3)

where qi is a computed coordinate, g i is a corresponding position constraint error, and J ii


is a Jacobian coefficient:
g
Jii = q j
i

(2.3.4)

The correction equation is crude. However, the error itself is very small, being on the
order of the computer precision. Therefore, the correction works well unless it becomes
singular and remains so for many time steps. This approximation is used if the global
*fast-computed-coordinates* had a value of T when the analysis was
performed.
Equilibrium Simulation Programs
A multibody system that is in equilibrium is described by a set of simultaneous
nonlinear equations of the form
f(q, t) = 0

(2.3.5)

where f is an array of generalized forces and moments, and q is the array of generalized
coordinates. A set of specific values for q defines a unique position configuration for the
multibody system. Each element of f corresponds to either a sum of forces or a sum of
moments. It is possible that the equations implicitly define a set of generalized
coordinates q such that the forces and moments balance. Of course, it is also possible that
there are more than one position configurations in which the system is in equilibrium. It
is also possible that there are no possible solutions. Nonetheless, if a solution exists, eq.
2.3.5 is used to find it.
The FCT routine for an equilibrium simulation is written much differently than the
routine of the same name used for a kinematical or dynamical simulation. FCT is not a
simple interface, but is instead a Newton-Raphson equation solver. (In fact, there is no
routine DIFEQN in an equilibrium simulation.) The FCT flow chart is shown in Figure
2.3.8. FCT computes the values of q needed to maintain the system in quasi-static
equilibrium at time t. The nonlinear equations in eq. 2.3.5 are solved using a NewtonRaphson iteration, using routine QUASI, LUD2, and BKSUB2. This algorithm is nearly
identical to that used by NEWTR1 to calculate the initial values of the computed
coordinates (see Figure 2.3.4). One difference, however, is that in the case of routine

2 33

2.3 Design of the Simulation Program

AUTOSIM 3

INITNR (used in NEWTR1), the matrix of Jacobian coefficients is computed from


explicit equations derived by AUTOSIM, whereas in the case of routine QUASI
(used in FCT), the matrix of Jacobians is obtained numerically by perturbation.
initial values of
independent coordinates

Compute force and


moment
equilibrium errors
and Jacobian

QUASI
Errors
OK?
yes

BKSUB2

LUD2

no

Solve linearized
force & moment
equlibrium equations
for changes in
independent
coordinates

new values of
independent coordinates
Figure 2.3.8. Flow chart for routine FCT (equilibrium).

Figure 2.3.9 shows the flow chart for routine QUASI. Routine QUASI2 contains the
describing equations for the multibody system, and computes the generalized forces and
moments in the array f from eq. 2.3.5 above. If the multibody system includes computed
coordinates, routine NEWTR1 is used in QUASI2 to ensure that the computed
coordinates are compatible with the values for the candidate independent coordinates that
are provided to QUASI2 by QUASI.
INTEQS is a dummy routine that does nothing in an equilibrium simulation.

2 34

2.3 Design of the Simulation Program

AUTOSIM 3

LOOP: perturb one


indep. coordinate
Calculate
force/moment errors

QUASI2

Get one column


of Force Jacobian by
difference approx.

no

Loop
done?

yes
Figure 2.3.9. Flow chart for routine QUASI.
Operations Performed after each Run
After the simulation computations have been completed, the output file is closed and
the FINISH routine is called. This routine exists as a place for the modeler to put
equations or routines that might compute summary statistics or other information of
interest that would be calculated after the run is completed. ECHO is then called a second
time, to give the user a chance to create another echo file, with values of all parameters
and the final values of the state variables. Finally, QUITSM is called to quit the
simulation program. This routine contains code that may be compiler dependent, to quit
the program in a manner that fits in well with the normal computer environment (e.g.,
closing windows).
Batch Operation
The AUTOSIM-generated simulation programs can be operated interactively or in
batch mode, as was described in Section 2.1. A library routine, BATCH, controls the
batch operation. This routine is called before any of the tasks described above (it appears
in the MAIN block just before routine SETDEF). The routine has names for all of the
input and output files as arguments, along with two logical variables. If a SIMFILE is
found, it is read to obtain file names for the next simulation run. The simulation run is
made in batch mode, using the file names from the SIMFILE. After the run, the program
loops back and calls routine BATCH again to see if file names for another run are in the
SIMFILE. The program does not quit until the end of the SIMFILE is reached.

2 35

2.3 Design of the Simulation Program

AUTOSIM 3

If a SIMFILE is not found, all file names are set to the string INTERACTIVE and
the logical variables are set FALSE to indicate that the program is running in the
interactive mode.

2.4 C Details
This section describes details of the data structures used in a C program generated by
AUTOSIM. It also describes the routines provided in C libraries with AUTOSIM.
Language Version and Style
The code is written in ANSI C/C++, but should compile with little or no modification
under many C compilers. Although the syntax of C++ is followed, the program does not
make use of the object-oriented features in C++.
Like many numerical analysis programs, the AUTOSIM-generated programs are
based on algorithms first coded in Fortran. Because AUTOSIM provides full simulation
codes in both languages for the same model description, the designs of the C and Fortran
versions have been kept close when possible. Indeed, a side-by-side comparison of the
routines containing the equations of motion (e.g., DIFEQN) show almost identical code,
differing only in syntax and array indexing.
In order to reduce compiler dependencies, two non-standard variable types are used:
Real and Bool. Both are defined in a header file (deftype.h), and should be set to an
appropriate data type for the C compiler being used. With this design, it is possible to
convert all floating-point precision by changing the definition of Real.
When AUTOSIM generates code in C, nearly all variables and functions are written
in lower-case. It is not possible to add variables or functions to an AUTOSIM-generated
program whose names are not all lower case. If you have existing code with functions or
variables in upper-case or mixed case, then have the C preprocessor insert them by
adding a #define statement in a header file. For example, replace the AUTOSIMfriendly myfunc with a mixed-case function name myFunc:
#define

myfunc

myFunc

If the name will be used in all simulations, modify the file deftype.h. Otherwise,
modify the header file for the simulation (e.g., sim.h).
Compiling and Linking a C Program
In AUTOSIM, the command write-c is used to write source code for a set of
functions that are customized for the model defined with AUTOSIM commands. A
corresponding header file must also be created using the command write-h.
The routines listed earlier in Table 2.3.1 contain the equations of motion for the
system, plus code for reading and writing parameters and simulation variables. This code
is written in ANSI C/C++, and contains no known compiler or machine dependencies.
2 36

2.4 Generated C Code

AUTOSIM 3

Table 2.4.1 lists several other files that are provided with AUTOSIM in the directory
clib within directory lib. They contain source code for various library routines and
headers that are not dependent on the model.

File
simlib.c
simlib.h
table.c
table.h
deftypes.h

Table 2.4.1. C library files and directories in clib.


Description
Routines needed for all programs
Header file for simlib.c
Routines needed for programs with table functions
Header file for table.c
Header file for all AUTOSIM-related code. Includes compiler
dependencies.

The file deftypes.h should be viewed and possibly edited to define the data types
Real and Bool. Also, the constants True and False are assigned there. Ideally, you
should only have to look at this file once. It contains no definitions that depend on the
type of model.
To create an executable simulation program, create a project file or make file for your
C compiler that includes the following files:
1.

The .c file created by AUTOSIM for your model (e.g., sim.c).

2.

simlib.c

3.

if you have any AUTOSIM-installed table-lookup functions, then include


table.c.

4.

include files for any external (user-written) code referenced in the model.

The file created by AUTOSIM (e.g., sim.c) contains a line near the top with an
#include statement, referencing the header file sim.h. If you created a header file
with a different name, then you must modify the #include statement.
Data Storage in Arrays and Global Structures
The storage of parameters and variables in the simulation program is fairly simple.
Table 2.4.2 summarizes the arrays that are used in more than one routine. Note that all
names shown can be modified by the modeler, by changing AUTOSIM global variables
as described in Section 2.6.

237

2.4 Generated C Code

AUTOSIM 3

Table 2.4.2. Arrays used in C program.


Array Name Where
Description and dimension
c
dyvars
computed values of cosines
errf
initnr
residual error terms
forcem
dyvars
amplitudes of forces and moments
jac
initnr
Jacobian coefficients for computed
coordinates
pc
prcmp
precomputed constants
q
main
generalized coordinates (NCOORD)
qp
main
derivatives of Q (NSPEED)
s
dyvars
computed values of sines
u
main
generalized speeds (NSPEED)
up
main
derivatives of U (NSPEED)
z
dyvars
intermediate variables (NVARS)
zi
initnr
intermediate variables

There are four global structures, which are described in Table 2.4.3. One of these,
prcmp, includes a single element, the array pc. The other three include sets of related
variables and arrays. Provisions are described later for customizing these blocks, to
include additional elements that you might want to use for external routines.

Structure
dyvars

inpars
prcmp
sypars

Table 2.4.3. Global structures used in simulation program.


Routines where used
Description
difeqn, finish, output, update
arrays and variables that describe
the multibody system (excluding
state variables)
difeqn, echo, finish, init, initnr, input, parameters that describe the
output, precmp, setdef, update
multibody system
difeqn, echo, finish, init, initnr, output, derived parameters that are preprecmp, update
computed
echo, finish, init, input, inteqs, main,
parameters that describe the
opnout, output, precmp, setdef, update numerical simulation process

In addition to the global structures described above, a structure is defined for every
table-lookup function created using the AUTOSIM install-table command.
The source program generated by AUTOSIM is heavily commented. The best way to
obtain a thorough understanding of how the arrays and structures are used is to study the
source code generated for one of the examples provided with AUTOSIM.

238

AUTOSIM 3

2.5 Fortran Details


This section describes details of the data structures used in a Fortran program
generated by AUTOSIM. It also describes the routines provided in Fortran libraries with
AUTOSIM.
Language Version and Style
Computer languages either change with the times or fall into disuse. As the oldest
programming language still in widespread use, Fortran has undergone many changes. The
most recent standard is Fortran 90. The previous standard was Fortran 77, and the one
before that was Fortran 66. The newest standard is not always fully supported or
implemented with all compilers. For example, when AUTOSIM was designed in 1989,
the most commonly used Fortran compiler on the PC did not fully support the Fortran 77
language.
All fortran code generated by AUTOSIM should compile under any compiler that
supports Fortran 77. However, there are several features of the AUTOSIM-generated
simulation that require non-standard extensions to Fortran 77. (The main problem with
Fortran 77 is that it was intended for batch use on computers where the inputs to a
program were provided on punch cards, and the output was printed on a line printer.)

Inputs are accepted from the keyboard and are written to the screen. This is
accomplished by using an asterisk (*) for the Fortran i/o device. This extension
to the language is almost universally supported by modern compilerswe know
of no compilers that do not support it. The printing of information on the screen
is not standard, however, so a compiler-dependent routine is used.

Files created during a simulation run include the time and date that the run was
made. Fortran 77 does not have standard functions for obtaining the time and
date, and therefore a compiler-dependent routine is needed.

Simple binary stream files are readable by programs written in C and other
languages. However, the command for creating the file is not standard, and must
be adjusted for different compilers.

The behavior of the program when it quits is not standard, especially for
windows-based operating systems.

Compiler-dependent code has been isolated into one file, and versions of that file are
provided with AUTOSIM for most of the popular fortran compilers.
Compiling and Linking a Fortran Program
In AUTOSIM, the command write-fortran is used to write source code for a set
of subroutines that are customized for the model defined with AUTOSIM commands.
The sroutines listed earlier in Table 2.3.1 contain the equations of motion for the system,
2 39

2.5 Fortran Details

AUTOSIM 2.0

plus codes for reading and writing parameters and simulation variables. This code is
written in standard Fortran 77, and contains no known compiler or machine
dependencies.
Table 2.5.1 lists several other files that are provided with AUTOSIM in the directory
flib within the directory lib. They contain Fortran source code for various library
routines that are not dependent on the model. (Note: on UNIX and Mac machines, the
files have the suffix .f. In the the Windows version, the suffix is .for.)
Table 2.5.1. Fortran library files and directories in flib.
File
Description
simlib.f
Routines needed for all programs
simlib_dp.f Routines needed for all double-precision programs
simlib_sp.f Routines needed for all single-precision programs
table_dp.f
Routines needed for double-precision programs with table functions
table_sp.f
Routines needed for single-precision programs with table functions
compiler
Directory. Each .f file contains the routines that are compiler dependent.
One and only oneof these files must be linked with the AUTOSIMgenerated program.

To create an executable simulation program, create a project file or make file for your
Fortran compiler that includes the following files:
1.

The .f file created by AUTOSIM for your model (e.g., sim.f).

2.

simlib.f

3.

either simlib_sp.f or simlib_dp.f, depending on whether your program


uses single or double precision.

4.

one and only one file from the compiler directory. For example, use msf.f if
you are using the Microsoft Fortran compiler for Windows.

5.

if you have any AUTOSIM-installed table-lookup functions, then include either


table_sp.f or table_dp.f, depending on whether your program uses
single or double precision.

6.

if you reference external (user-written) code in the model, then include the
corresponding files.

Data Storage in Arrays and Common Blocks


The storage of parameters and variables in the simulation program is fairly simple.
Table 2.5.2 summarizes the arrays that are used in more than one routine. Note that all
names shown can be modified by the modeler by changing AUTOSIM global variables
as described in Section 2.6.

2 40

2.5 Fortran Details

AUTOSIM 2.0

Table 2.5.2. Arrays used in Fortran program.


Array Name Where
Description and dimension
C
/DYVARS/
computed values of cosines
ERRF
INITNR
residual error terms
FORCEM
/DYVARS/
amplitudes of forces and moments
JAC
INITNR
Jacobian coefficients for computed coordinates
PC
/PRCMP/
precomputed constants
Q
MAIN
generalized coordinates (NCOORD)
QP
MAIN
derivatives of Q (NSPEED)
S
/DYVARS/
computed values of sines
U
MAIN
generalized speeds (NSPEED)
UP
MAIN
derivatives of U (NSPEED)
Z
/DYVARS/
intermediate variables (NVARS)
ZI
INITNR
intermediate variables

There are four common blocks used, which are described in Table 2.5.3. One of
these, PRCMP, includes a single element: the array PC. The other three include sets of
related variables and arrays. Provisions are described later for customizing these blocks,
to include additional elements that you might want to use for external routines.
Table 2.5.3. Common Blocks used in simulation program.
COMMON Subroutines where used
Description
DYVARS
DIFEQN, FINISH, OUTPUT, UPDATE
arrays and variables that describe the multibody system
(excluding state variables)
INPARS
DIFEQN, ECHO, FINISH, INIT, INITNR, parameters that describe the
INPUT, OUTPUT, PRECMP, SETDEF,
multibody system
UPDATE
PRCMP
DIFEQN, ECHO, FINISH, INIT, INITNR, derived parameters that are
OUTPUT, PRECMP, UPDATE
pre-computed
SYPARS
ECHO, FINISH, INIT, INPUT, INTEQS, parameters that describe the
MAIN, OPNOUT, OUTPUT, PRECMP,
numerical simulation
SETDEF, UPDATE
process

In addition to the common blocks described above, a common block is defined for
every table-lookup function created using the AUTOSIM install-table command.
The source program generated by AUTOSIM is heavily commented. The best way to
obtain a thorough understanding of how the arrays and common blocks are used is to
study the source code generated for one of the examples provided with AUTOSIM.

2 41

AUTOSIM 3

2.6 Changing the Simulation Program From Within AUTOSIM


There are several reasons that you might want to change certain details in the design
of the simulation programs generated by AUTOSIM. You may need to customize the
code to work with a new compiler. You might want the output files written in a new
format to work with in-house post-processing software. You may just want to change
variable names to match a familiar convention. There are several ways of making
changes of this nature.
Because the full source code generated by AUTOSIM is available to you, the method
that probably comes to mind first is to go in with a text editor and make changes by hand.
This is a good way to become familiar with the design of the AUTOSIM-generated
programs, and is often the best way to make minor one-time changes. If you are
generating many simulation programs, you may want to modify the specifications of the
programs before they are generated by AUTOSIM, to eliminate the need for manual
editing.
It is helpful to know exactly how AUTOSIM generates a simulation program. First, a
multibody system is analyzed and equations of motion are derived. After the analysis, all
of the equations, parameters, and details of the simulation are represented internally, in
computer memory. The code that is generated from the internal representation is
controlled by a number of global AUTOSIM variables. By changing those variables, the
appearance of the generated code is changed. When you specify that a simulation
program is to be written, AUTOSIM assembles a program by merging existing include
files with code that is generated to represent the information stored internally. For C, the
include files are in a folder cinc, also within the lib folder. For Fortran programs, all
of the include files are in a folder finc within the lib folder. The code that comes from
the include files can be modified once and for all just by changing the include file with a
text editor.
There are two methods for changing the design of a simulation program before it is
written: (1) change a global AUTOSIM variable, and (2) modify an include file. In
general, you switch between built-in AUTOSIM options by changing global variables. To
extend the design of the simulation program, you modify an include file.
AUTOSIM Variables Affecting the Program Appearance
Table 2.6.1 lists AUTOSIM Boolean variables (T or NIL) that control options in the
generation of the code. Table 2.6.2 lists variables that are strings or lists of strings
appearing in the source code. There is one other global, *Maximum-Difeqn-Lines*,
that is described in the next subsection.

2 42

2.6 Changing the Simulation Program From AUTOSIM

AUTOSIM 3

Table 2.6.1. Boolean AUTOSIM variables that affect the program appearance.
Variable
Default * Description
*Double-Precision*
NIL
W Use double-precision?
*Expand-Pcs*
NIL
A Reduce number of PC variables?
*Fast-ComputedT
F Use approximation to update computed
Coordinates*
coordinates in a dynamical simulation?
*Int-Vars*
T
A Use intermediate variables?
*No-If-Else*
NIL
W Forbid a long set of if-else blocks in the
input routine?
*No-Pcs*
NIL
A Forbid the use of PC intermediate variables?
*No-Zees*
NIL
A Forbid the use of Z intermediate variables?
*Safe-Divide*
NIL
W Prevent numerical divide by zero?
*Safe-Sqrt*
NIL
W Prevent SQRT of negative number?
*Stiff-Integrator*
NIL
F Use variable-step stiff integrator?
*Verbose*
T
W Comment code liberally?
* Letters indicate when a variable must be set to have an effect. A=before first add-body command,
F=before finish command, W=before writing code.

Table 2.6.2. AUTOSIM string variables appearing in the program.


AUTOSIM Variable
Default
* Use
*Multibody-System-Name*
multibody W appears on screen and in output
system
files
*Unit-Vector-Brackets*
[]
R determines how unit-vectors are
printed in labels and comments
*Unit-Vector-Indices*
XYZ
R determines how unit-vectors,
point coordinates, and moments
of inertia are labeled
*Echo-Header*
NIL
W list of strings printed at start of
output echo files
*Screen-Header*
NIL
W list of strings printed on screen
when program starts
*Extra-Lines-In-ErdNIL
W list of strings printed in header of
File*
output file
*C=*
C===. W divider used in Fortran source
*Dashes*
----W divider used in C source
*Fortran-Implicit*
W line(s) inserted at the start of
every Fortran routine, e.g.,
IMPLICIT NONE
NOTE: Letters indicate when a variable must be set to have an effect. R=before reset command,
W=before writing code.

2 43

2.6 Changing the Simulation Program From AUTOSIM

AUTOSIM 3

Table 2.6.3 lists all of the variable names that can be changed by changing the symbol
assigned to an AUTOSIM variable. In a C program, many of the variables are slots in the
global data structures listed in Table 2.4.3.
Table 2.6.3. Simulation program variable names that can be changed.
Variable AUTOSIM
Description
C
*cos-symbol*
array of cosines
DR
*degree*
symbol to represent deg/rad conversion
ERRF *errf-symbol*
array of constraint errors in INITR
FORCEM *fm-symbol*
array of force and moment magnitudes
G
*gees*
symbol to represent gravitational constant
GFA
*force-array-symbol* array of generalized forces
JAC
*jac-symbol*
Jacobian matrix in INITR
M
*mass-matrix-symbol* mass matrix
PC
*pc-symbol*
array of precomputed constants
Q
*q-symbol*
array of generalized coordinates
QP
*qp-symbol*
array of generalized coordinate derivatives
S
*sin-symbol*
array of sines
U
*u-symbol*
array of independent speeds
UP
*up-symbol*
array of independent speed derivatives
Z
*z-symbol*
array of intermediate variables
ZI
*zi-symbol*
array of intermediate variables in INITNR
NOTE: the above AUTOSIM variables should be assigned new values before the reset command.
Breaking Up DIFEQN
Most of the time-varying calculations for the equations of motion appear in the
DIFEQN routine. For large models, the number of lines of code in this routine can be
large, and cause compiler problems. One problem is that compilers try to optimize the
code and run out of memory. In general most of the optimizations that the compiler
would make have already been made by AUTOSIM. However, the compiler doesnt
know that, and may run into trouble trying.
The problem is avoided by having AUTOSIM break up the DIFEQN routine into
several routines that each contains a limited number of equations. The extra routines are
named DFEQ1, DFEQ2, etc. The AUTOSIM global *Maximum-Difeqn-Lines* is
normally set to 500, limited the number of lines to about 500. (For some arcane technical
reasons, the exact number of statements in each block is usually not exactly 500, but
something closer.)
Set *Maximum-Difeqn-Lines* to NIL to disable the breaking up of DIFEQN.
Set it to a different number to change the size of the individual blocks.

2 44

2.6 Changing the Simulation Program From AUTOSIM

AUTOSIM 3

Include Files
Some of the source code is simply copied from existing files. That code can be
changed for once and for all by replacing the original include file with a modified copy.
There are two primary reasons for modifying include files: (1) to make the code work
better with a specific compiler, and (2) to customize the output files produced by an
AUTOSIM-generated program to work with other software used in-house.
Listing 2.6.1 illustrates how an include file is merged with custom code. The code
generated by AUTSOSIM to match the specific system of interest is shown in bold
typeface, and the code copied from an include file is shown in plain typeface.
Listing 2.6.1. The include file for the OUTPUT subroutine.
C=======================================================================
SUBROUTINE OUTPUT(IFILE, T, Q, QP, U, UP)
C=======================================================================
C This subroutine writes the values of the 7 output variables computed
C by the 4-bar linkage simulation program into an output file, using
C the values at time T.

< Note: code has been deleted for brevity>


C

fill buffer with output variables.


OUTBUF(1)
OUTBUF(2)
OUTBUF(3)
OUTBUF(4)
OUTBUF(5)
OUTBUF(6)
OUTBUF(7)

=
=
=
=
=
=
=

FORCEM(2)
-FORCEM(1)
Z(42)
Z(45)
Q(1)
Q(3)
Z(46)

The following line writes to a file one of three ways


IF (FORMAT(1:1)
WRITE (IFILE,
ELSE IF (FORMAT
WRITE (IFILE,
&

.EQ. '(') THEN


FORMAT) (OUTBUF(ILOOP),ILOOP=1, NVARS)
.EQ. 'TEXT') THEN
'(72(G13.6, '',''))')
T, (OUTBUF(ILOOP),ILOOP=1, NVARS)

ELSE
WRITE (IFILE) (OUTBUF (ILOOP), ILOOP=1, NVARS)
END IF
RETURN
END

Files with complete subroutines have the extension .for (Fortran) or .c (C). Files
with segments of code have the extension .inc, e.g., echo-1.inc.

2 45

2.6 Changing the Simulation Program From AUTOSIM

AUTOSIM 3

Output Files
AUTOSIM-generated programs are capable of producing three kinds of output files
with the simulation results, depending on the value assigned by the user to the FORMAT
keyword. (See Section 2.1.) The code that actually writes into an output file is all
contained in include files that go into the subroutines OPNOUT and OUTPUT. Listing
2.6.1 showed the layout of a typical OUTPUT Fortran subroutine. Note that the format of
the output file is completely provided by the include file (in this case, the include file is
named output-1.inc). Listing 2.6.2 shows the layout of subroutine OPNOUT, which
opens the file and writes the header information.
By changing the include files for OUTPUT and OPNOUT, you can cause the
programs generated by AUTOSIM to create output files in almost any format. Note that a
great deal of labeling information is generated in the OPNOUT subroutine and assigned
to character variables before anything is written. You can modify the way that the file is
written to use any of this information as you please.

2 46

2.6 Changing the Simulation Program From AUTOSIM

AUTOSIM 3

Listing 2.6.2. Layout of typical OPNOUT Fortran subroutine.


C=======================================================================
SUBROUTINE OPNOUT(IFILE, FNOUT)
C=======================================================================
C This subroutine prompts the user for the name of a file set that
C will be created to store time histories of the 7 output variables
C computed by the 4-bar linkage simulation program.
C
C
C
C

A text file is created and opened, and labeling information is


written to facilitate post-processing of the data. Then, the text
file is closed and a corresponding binary file is created and opened
to store the numerical values of the output variables.

C
C

(c) The Regents of The University of Michigan, 1989 - 1992. All


rights reserved.
IMPLICIT NONE
INTEGER
NVARS
PARAMETER
(NVARS = 7)
<Note:

code was deleted here for brevity>

IF (FNOUT .EQ. ' ' .OR. CAPSTR(FNOUT) .EQ. 'INTERACTIVE') THEN


FNOUT = OPNFIL(
& 'Name of (required) file for time history outputs', 'NEW', IFILE)
ELSE
CALL OPNTXT(IFILE, 'NEW', FNOUT)
END IF
NCHAN = 0
NCHAN = NCHAN
LONGNM(NCHAN)
SHORTN(NCHAN)
GENNAM(NCHAN)
UNITSN(NCHAN)
RIGBOD(NCHAN)
<Note:

+
=
=
=
=
=

1
'spindle force'
'Fspindle'
'Force'
'N'
'input'

code was deleted here for brevity>

UNITSN(NCHAN) = 'rad'
RIGBOD(NCHAN) = 'C'
C

Write simple header for TEXT file


IF (FORMAT .EQ. 'TEXT') THEN
WRITE(IFILE, '(256A)') '"Time", ',
& ('"' // SHORTN(ILOOP)(:LENSTR(SHORTN(ILOOP))) // '", ',
&
ILOOP=1, NCHAN)
<Note:

code was deleted here for brevity>

120 FORMAT (A8, 31A32, 100(/'&1000


RETURN
END

2 47

', 31A32))

3.3 ADSIM Code

AUTOSIM 2.0

CHAPTER 3

CONTINUOUS SIMULATION LANGUAGES


Support for the ADSIM and ACSL languages has been dropped from AutoSim
versions higher than 2.0.

CHAPTER 4

MATRIX ANALYSIS LANGUAGES


4.1 Summary of Linear System Representation 2
4.2 MATLAB Code 2

This chapter describes the code generated by AUTOSIM for linear analysis in the
MATLAB matrix analysis language.
This chapter does not begin to cover the uses of MATLAB. For that information, you
should consult the reference manual provided with the language.

41

AUTOSIM 2.0

4.1 Summary of Linear System Representation


The equations of motion of a multibody system can be linearized and put into the
form
.
x = A x + B u

(3.1.1)

where x is an array of linear perturbations of the state variables about a set of reference
values, u is an array of input variables, and A and B are matrices with dimensions sized
to match x and u. Also, a set of output variables y can be defined as
y = C x + D u

(4.1.2)

where C and D are matrices with dimensions sized to match y, x, and u.


If computer code is generated to set up these matrices, then a matrix analysis
language such as MATLAB, CONTROL-C, or MATRIX-X can be used to compute
properties of the linearized system such as eigenvalues, eigenvectors, transfer functions,
etc.
AUTOSIM generates a program whose sole function is to define the matrices A, B,
C, and D. It does this by deriving the full, nonlinear equations of motion, and then taking
partial derivatives of the equations with respect to the state variables. Equations
linearized in this way are valid for any set point. To change the set point, just change the
numerical values of the state variables before computing the matrices.
The current version of AUTOSIM generates MATLAB code for computing the four
matrices. The code is derived symbolically, meaning that only MATLAB is needed to
study the system for different parameter values after the equations are derived.
It is sometimes better to obtain the matrices numerically. For complex models, the
linear equations, can much more complicated than the nonlinear equations. (Although
linear matrices are obtained, the nonlinearities of the system are still left in to
accommodate an arbitrary set-point.) Another consideration is that if the model includes
components whose properties are not symbolically differentiable, then AUTOSIM may
not be able to derive the matrices symbolically. The matrices can be obtained numerically
with the Fortran subroutine FCT, written for time-simulation runs. (See Section 2.3.) By
calling this subroutine repeatedly with perturbations in the state variables x and the input
variables u, the partial derivatives needed for A and B can be computed numerically.

4.2 MATLAB Code


MATLAB is an interactive mathematical analysis language designed for the
manipulation of matrices, developed and sold by The MathWorks, Inc. Sequences of
MATLAB commands stored in special text files called m-files can be executed as
commands. AUTOSIM generates the MATLAB code necessary to define the A, B, C,
and D matrices for a multibody system and writes it into a file that can be executed as an
m-file from within MATLAB. The purpose of the m-file is simple: it defines four arrays
42

4.2 MATLAB Code

AUTOSIM 2.0

named MatrixA, MatrixB, MatrixC, and MatrixD, representing the A, B, C, and D


matrices, respectively. After executing the m-file, you can execute MATLAB commands
involving those arrays. For example, to generate Bode plots (using the optional Control
System Toolbox), type in the command
bode(MatrixA, MatrixB, MatrixC, MatrixD, 1)

The layout of the m-file generated by AUTOSIM with the write-matlab


command consists of the following sections:
1.

Numerous comments describe the multibody system model, listing bodies, state
variables, forces, and moments.

2.

Parameters appearing in the equations are assigned default values.

3.

The parameters are converted from user units to dynamics units.

4.

Constant terms are defined.

5.

Variable terms are defined.

6.

Matrices M a t r i x A , MatrixA1, MatrixAA, MatrixB1, MatrixB,


MatrixC, and MatrixD are defined.

AUTOSIM derives code for the equations of motion in the form:


AA x = A1 x + B1 u

(4.2.1)

Thus,
A = (AA)-1 (A1)

B = (AA)-1 (B1)

(4.2.2)

After defining matrices AA, A1, and B1 (as matrices MatrixAA, MatrixA1, and
MatrixB1, respectively), the generated m-file defines A and B according to eq. (4.2.2).
You may want to split up the generated MATLAB code into several m-files, with
each performing a specific function. For example, by putting the parameter assignments
(section 2) in a separate file from the equations (sections 4, 5, and 6), you can modify
parameters of interest without constantly editing the m-file with the equations.

43

PART 2

SYMBOLIC ANALYSIS

This part of the manual explains how to use AUTOSIM to generate simulation and
analysis software for your models.
Chapter 5 Building a Model
This chapter describes how you go about building a model with AUTOSIM. The
approach you take is to describe the model using your own parameters and the
geometric conventions covered in Section 1.3. It also explains how you can view
information about the model, to provide insight about how to best describe
complex elements, and to help debug your model.
Chapter 6 Using External Code
This chapter explains how to include code that was not generated by AUTOSIM
into your models. Such code can be in the form of equations, functions, and
subroutines. The chapter also offers guidance on why and where to use external
code.
Chapter 7 Advanced Topics
This chapter describes advanced uses of AUTOSIM. It describes methods for
modeling systems that have historically been difficult to simulate, and suggests
strategies for optimizing simulation speed. It also describes how elementary Lisp
capabilies can be used to create new AUTOSIM commands.

CHAPTER 5

BUILDING A MODEL
5.1 Introduction 3
5.2 Multibody Terminology and Definitions 4
Geometric Definitions 5
Points 5
Vectors 5
Reference Frames 6
Coordinate Systems and Unit-Vectors 6
Distinctions Between Coordinates, Points, and Vectors 7
Dyadics 7
AUTOSIM Bodies 8
Point Masses and Rigid Bodies 9
Massless Reference Frames 9
Parent Bodies and the Nominal Configuration 9
Standard Body Points 9
Joints and Constraints 10
Body Degrees Of Freedom (DOF) 10
Tree Topologies 10
Closed Kinematical Loops 11
Additional Constraints 11
Holonomic and Nonholonomic Constraints 12
Forces 12
Moments, Couples, and Torques 13
Angular Orientation of a Rigid Body 14
Angular Velocity of a Moving Reference Frame 14
Mass and the Inertia Tensor (Dyadic) 14
5.3 Overview of an AUTOSIM Analysis 15
Syntax of Commands 15
Interactive Computer Algebra 17
5.4 Defining the Bodies and Joints 18
The Add-Body Command 18
State Variables 20
The Motion Command 21
The No-Movement Command 22
Generic Constraint Commands 22
Guidelines for Defining Joints 23
Controlling the Definitions of the State Variables 24

51

Chapter 5: Building a Model

AUTOSIM 2.0

5.5 Adding Forces and Moments 26


Gravity 27
Working Forces and Moments 27
The Add-Line-Force Command 27
The Add-Strut Command 28
The Add-Moment Command 29
Non-working Constraint Forces and Moments 29
5.6 Defining Auxiliary Variables 31
The Add-Variables and Add-Equations Commands 31
Simulation Languages 32
Linear Analysis 32
Circular Dependencies in Force Definitions 32
Fortran Output Variables 33
5.7 Installing Nonlinear Tablular Functions 34
5.8 Specifying the Analysis 35
5.9 Viewing Results of the Analysis 36
Commands for Printing 36
Recommended Debugging Checks 36
5.10 Customizing the AUTOSIM-Generated Program 38
Properties of AUTOSIM Symbols 38
AUTOSIM Units Expressions 39
5.11 Generating the Numerical Analysis Program 40

This chapter describes how you go about building a model with AUTOSIM. The
approach you take is to describe the model using your own parameters and the geometric
conventions covered in Section 1.3. It also explains how you can view information about
the system, to provide insight about how to best describe complex elements, and to help
debug your model. The chapter is limited in scope to models that can be built with no
manual programming.
Details of the numerical analysis methods used in the AUTOSIM-generated programs
were described in the previous chapters. The next chapter explains how you include
external code (not generated by AUTOSIM) into your models.

52

AUTOSIM 2.0

5.1 Introduction
Figure 5.1.1 shows the basic method for studying a multibody system with
AUTOSIM. As a modeler, you put some thought into developing a model that captures
the essential features of interest in the physical system (step 1). Then, you describe that
model to AUTOSIM (step 2), and generate a numerical analysis computer program (step
3). The product of this activity is a custom computer program that simulates the system
based on your model and established numerical analysis methods. The custom program is
a tool for the end user to view the behavior of the system for any parameter values of
interest (steps 4, 5, and 6).
The model is an idealization of an actual physical system, in which moving parts and
subsystems are assumed to behave as purely rigid bodies, affected by forces and moments
whose magnitudes are defined deterministically as functions of the motions and of time.
To design such a model, you must:
1.

identify all moving parts as point masses or rigid bodies,

2.

describe geometric constraints on the movements of the parts, and

3.

describe forces and moments that influence the motions of the parts.
1. Design Model
of multibody system
Modeling
(Symbolic
Analysis)

2. Prepare AUTOSIM Inputs


to describe system model

3. Run AUTOSIM
to generate custom program

4. Prepare Model Inputs


to describe specific system
Simulation
(Numerical
Analysis)

5. Run Simulated Test


with custom program

6. View Results
(plots, statistics, animations)
Figure 5.1.1. Modeling and simulation with AUTOSIM.

53

5.1 Introduction

AUTOSIM 2.0

For example, consider the planar


automotive suspension example shown
2
N
again in Figure 5.1.2. A model should
have three moving bodies, shown as the
A
1
links A and B, and the spindle, shown as
part C. These parts cannot move
3
C
arbitrarily. Although body C can rotate
g
4 5
and move vertically and horizontally,
these movements are not independent. The
motions of body C are constrained by the
geometry (kinematics) of its connections
8
to bodies A and B. Therefore, our model
F
must include these connections. The
7
B
6
motions of the system do not just happen
by chance: they are the response of forces
Figure 5.1.2. Four-bar linkage.
applied to the parts. From the figure, we
see that model should include the effects of the gravitational field, the spring connecting
points 2 and 7, and the vertical force applied to point 5.
This chapter and the next focus on how you describe your model to AUTOSIM. The
AUTOSIM commands are flexible, to let you describe your model directly and simply.
There is a close correspondence between the the decisions you make in designing the
model and the AUTOSIM inputs. In this chapter, you will see how to build your model in
AUTOSIM. You will

introduce rigid bodies, massless reference frames, and point masses;

describe geometric constraints on the movements of the parts; and

describe forces and moments that influence the motions of the parts.

Section 1.3 reviewed the basic vector notation that you use to describe positions and
other quantities in three dimensions. The next section reviews the rest of the multibody
language you will use to describe your model.
The AUTOSIM-generated program based on your model might be used for years by
end users, who change parameters to fit the model to different designs. If this is the case,
time spent up front, refining the model, can make it more productive to use. Obtaining
parameter values for a simulation model can be a time consuming task for the end user.
You have complete control over the parameters used in the model, and it can be worth
some thought to define the model with parameters that are readily available to the
intended end user.

5.2 Multibody Terminology and Definitions


This section explains conventions for describing the elements of multibody systems
that are used in this manual. The major geometric elements are bodies, points, and
vectors. Other elements are forces and moments. Points and vectors were reviewed in
54

5.2 Multibody Terminology and Definitions

AUTOSIM 2.0

Section 1.3. This section continues, providing a more complete review of the terminology
and definitions of the language you will use to describe your models.
Geometric Definitions
Most of the AUTOSIM inputs descriptions are geometric, and are based on vector
notation. The notation is unusually simple for engineering software. Rather than dealing
with matrices of coordinates, you deal with more fundamental geometric objects such as
points and vectors.
Points
A point is a basic geometric entity that defines a position in space. We use a point as
a means to identify any position, stationary or moving, that is a part of the model. The
point may represent a physical spot on a mechanical object; it may represent a spot on a
mechanical object that can move; or it can represent a position in space that is not a part
of any physical part, but which is of interest when we describe a multibody system. All
points in AUTOSIM are given symbolic names. Figure 5.2.1 shows a moving body A, the
inertial reference N, and four points of interest, named O, P 1, P2, and P3.

ay

ax

N
ny

P3

P1
nx

P2
Figure 5.2.1. Points and unit-vectors in a moving body.
Vectors
A direction vector is another basic geometric entity. One way to define a direction is
by considering a line connecting two points in three-dimensional space, say, points P2
and P 3 in Figure 5.2.1. A segment of the line that has a length of one unit is the direction
of the line. An important characteristic of a direction is that it has no location. For
example, in the figure, the direction of vector ax is the same as that of vector connecting
points P2 and P3, rP2 P 3 .
More generally, a vector is a geometric object with a direction and size.
(Mathematically, it is a tensor of rank 1). The physical meaning of a vector is determined
by the units we assign to its size. For example, the size of vector rP2 P 3 is w, with units of
length. A vector may have other units, such as length per time (velocity), force, length
times force (moment), etc.
A one-dimensional array is called a vector by many authors. To avoid confusion with
the concept of a vector described above, the word vector is reserved in all AUTOSIM
documentation for the geometric object (tensor of rank 1) just described.

55

5.2 Multibody Terminology and Definitions

AUTOSIM 2.0

Reference Frames
A reference frame is a geometric environment in which points remain fixed with
respect to each other at all times. In Figure 5.2.1, the distances between points P 1, P2, and
P3 remain fixed at all times. Therefore, a moving reference frame exists, in which those
points are fixed.
Coordinate Systems and Unit-Vectors
In order to describe points and directions, we commonly use coordinate systems. A
coordinate system is a numbering convention used to assign a unique ordered trio of
numbers to each point in a reference frame. In AUTOSIM, all coordinate systems are
right-handed, Cartesian systems, defined by (1) a reference frame in which the system is
fixed, (2) an origin point, and (3) three mutually orthogonal directions that define the
axes. By right handed, we mean that if two of the directions are x and y, then the third
direction z = x y. Figure 5.2.2 shows four possible coordinate systems for describing
the location of a point P. (The third axis in each case is perpendicular to the plane of the
paper, pointing up.)
Moving
Reference
Frame
Ao
Point P

O
Bo

Fixed
Coordinate
Systems
O'
Figure 5.2.2. Alternative coordinate systems.
A direction vector that is used to define the axis of a coordinate system is called a unit
vector. In figure 5.2.1, ax and ay are unit vectors. For each body in an AUTOSIM model,
there are three associated unit-vectors. They are named by appending one of three indices
to the name of the body. For example, the unit-vectors for body B are bx , by, and bz.1

AUTOSIM recognizes indices of X, Y, Z, 1, 2, 3, or any set that you assign to the global variable
*unit-vector-indices*.

56

5.2 Multibody Terminology and Definitions

AUTOSIM 2.0

AUTOSIM writes unit-vectors with enclosing brackets or braces. For example, the unitvectors for body B would normally appear in an AUTOSIM session as [bx], [by], and
[bz].1
The three coordinates of a point P in a coordinate system whose axes are in the
directions ax, ay, and az and whose origin is a point A0 are defined mathematically as:
rAoP ax, rAoP ay, rAoP az.
A coordinate system is fixed if it is defined in a fixed reference system, and moving if
defined in a moving reference system. A specific coordinate system has just one origin,
one set of three axis directions, and one reference frame. Another coordinate system can
be defined by changing any of the three elements. It is possible to have any number of
coordinate systems in a reference frame that share the same origin point, but with
different axis directions, and it is possible to have any number of coordinates systems
with the same axis directions, but different origin points.
Distinctions Between Coordinates, Points, and Vectors
It is important to understand the distinction between coordinates, points, and vectors.
A vector is independent of all coordinate systems. AUTOSIM deals with unit-vectors,
vectors, and points without tying them to specific coordinate systems. This gives you a
great deal of flexibility and convenience in describing the system.
You use coordinate systems to describe the locations of points in your model. With
AUTOSIM, you can introduce as many coordinate systems as you like, to simplify your
descriptions of the various points and directions in your model.
The fact that AUTOSIM manipulates points and vectors directly may require some
adjustment in your thinking if you have extensive background in dynamics and modeling.
In a dynamics analysis performed with pencil and paper, much of the effort goes into
developing and manipulating coordinates characterized by expressions. In AUTOSIM,
this is not necessary. Coordinates are derived automatically, as needed, behind the
scenes, leaving you free to deal only with the symbols for unit-vectors and points. It is
possible to analyze the most complex of multibody systems in AUTOSIM without ever
entering a sine or cosine function.
Dyadics
A dyadic is used in AUTOSIM as an extension of the vector concept. If you are
unfamiliar with dyadics, dont worry. You can build the most complex models in
AUTOSIM without even knowing that there is such a thing as a dyadic. However,
AUTOSIM supports vector operations with dyadics, and there may be occasions where
you find a knowledge of dyadics useful.

AUTOSIM recognizes <> and [] as delimiters for unit-vectors, or any set that you assign to the global
variable *unit-vector-brackets*.

57

5.2 Multibody Terminology and Definitions

AUTOSIM 2.0

Consider point P3 from Figure 5.2.1. If P1 is the origin of a coordinate system, whose
X and Y axes are in the directions ax and ay, then the coordinates of point P3 are (w, h),
defined as (rP1 P 3 ax, rP1 P 3 ay). If we want to write an expression for the vector, one way
would be
rP1 P 3 = w ax h ay
or, from the definition of the coordinates,
rP1 P 3 = (rP1 P 3 ax) ax + (rP1 P 3 ay) ay

(5.2.1)

Another way of writing eq. 5.2.1 is


rP1 P 3 = rP1 P 3 (ax ax) + rP1 P 3 (ay ay)

(5.2.2)

The terms (ax ax) and (ay ay) are dyads. Mathematically, a dyad is a tensor of rank 2. It is
a potential multiplication between two unit-vectors. A dyad is really just a notational
convenience: two unit-vectors written next to each other on paper. A vector operation
made on the first unit-vector in the pair will be multiplied by the second unit-vector in the
pair. A vector operation made on the second unit-vector in the pair will be pre-multiplied
by the first unit-vector. A dot product with a dyad in which both unit-vectors are the same
(e.g., ax ax) results in a vector projected in the direction defined by the dyad.
An algebraic expression that includes dyads is called a dyadic.
Two kinds of dyadics are commonly used with AUTOSIM. One, built from three
mutually orthogonal unit-vectors, is called a basis dyadic. For example, consider the
dyadic:
A = a x ax + a y ay + a z az .
rA=r=Ar

(5.2.3)

Regardless of how the vector r was originally written, after a dot product with A it is
written in terms of a x , a y , and a z . Thus, a dot product with A implies a coordinate
transformation to the coordinate system A. (AUTOSIM includes a function called basis
that provides the basis dyadic for a body.) The other application, which will be discussed
later, is for representing the rotational inertia properties of a rigid body.
AUTOSIM Bodies
In AUTOSIM, the body is an entity that includes (1) a moving reference frame, (2) a
coordinate system, and, optionally, (3) a point mass or rigid body. Like points, bodies are
identified with short names consisting of one or more capital letters. Body N always
refers to the inertial reference, and other bodies are named as they are entered. Because
there is a one-to-one correspondence between rigid bodies, reference frames, and
coordinate systems, all three are named the same.
In much of the following material, the body under consideration is called body B, to
shorten the descriptions.

58

5.2 Multibody Terminology and Definitions

AUTOSIM 2.0

Point Masses and Rigid Bodies


A point mass is a particle with mass but no rotational inertia properties. A rigid body
is an object with mass and rotational inertia properties, in which all points are fixed in the
same reference frame. Elementary physics show that the mass distribution of a rigid body
is completely summarized by three pieces of information: (1) the total mass of the body,
(2) the location of its center of mass, and (3) the inertia tensor (dyadic). These elements
will be described shortly.
Massless Reference Frames
Each body might correspond to a mechanical element in the multibody system.
However, it is often useful to consider reference frames for which there are no
corresponding rigid bodies. For example, to describe the vehicle handling model in
Appendix B of the Introductory Guide to AUTOSIM, we introduced a massless reference
frame U to which axle masses were attached.
Parent Bodies and the Nominal Configuration
Each body you add has a position defined relative to N or to another body in the
system. That other body is called the parent. Your definition of its position and
orientation relative to the parent is called the nominal configuration. If the body can
move relative to the parent, then the nominal configuration defines the position when the
state variables, introduced by AUTOSIM to account for the motion, are zero.
Standard Body Points
Each body has at least three associated points that are introduced automatically when
the body is added to the system. For body B, these points are: (1) B0, the origin of B, (2)
BCM, the center of mass of B, and (3) BJ, the joint-point of B, which is a point fixed in
the parent that coincides with B0 when the body is in its nominal position. Figure 5.2.3
shows these three points for a body B in its nominal configuration and a new position.

B0, BJ

BJ

BCM
B0

(a) body B in nominal configuration


(b) body B in new position
Figure 5.2.3. The three standard points in a body.

59

BCM

5.2 Multibody Terminology and Definitions

AUTOSIM 2.0

Joints and Constraints


Kinematic relationships between bodies are often constrained due to joints. Joint
constraints are handled in two ways in AUTOSIM: (1) by limiting body degrees of
freedom (DOF), and (2) by defining additional constraint conditions.
Body Degrees Of Freedom (DOF)
Most of the joints are accommodated when the movement of a body is defined
relative to its parent. The number of independent movements allowed by the joint
connecting a body to its parent is called the number of body degrees of freedom (DOF).
There can be from zero to three rotational DOF, and from zero to three translational
DOF. Counting all the possibilities, there are 16 basic connection geometries (4
translational options multiplied by 4 rotational options).
Tree Topologies
When all of the joints in a model can be handled by considering the body DOF, the
system has a tree topology. Consider the four-bar linkage example, shown again in part a
of Figure 5.2.4. Suppose there is no physical connection between bodies B and C. In that
case, the system has three bodies and three joints. Part b of the figure shows a graph of
parent-child relations of the bodies. In the graph, each body appears as a node, labeled
with the symbol for the body. The lines connecting the nodes indicate constraints
involving movements of two bodies relative to each other. This type of graph is called a
tree, and, therefore, the system is called a tree-topology system.

A
N

ny
A
nx

C
C

b. graph of topology
with no joint between
bodies B and C.
Figure 5.2.4. Four-bar linkage.

a. model geometry

C
c. graph of topology
with all joints

A characteristic of a tree-topology system is that the relative motion between any two
bodies is not constrained geometrically by the motion between any other two bodies. For
example, if there is no connection between bodies B and C, then the rotation of body C
relative to A does not depend on the rotation of A or B relative to ground.

5 10

5.2 Multibody Terminology and Definitions

AUTOSIM 2.0

The geometric relations of most tree-topology systems can be described in


AUTOSIM with a single command, add-body. This is because you always describe the
DOF of each new body when you add it to the model. In the four-bar linkage example,
the joint between the ground and link A is defined when body A is added to the model.
The joint between ground and B is defined when B is added, and the joint between A and
C is described when C is added.
Closed Kinematical Loops
Now, consider the joint connection that actually exists between bodies B and C in the
four-bar linkage. In addition to the lines shown in part b of the figure, another line is
needed to connect B and C. Part c of the figure shows that when such a line is added,
there is a loop in the graph. In contrast to a tree-topology system, the relative motions
between two bodies on a loop may be constrained by geometry, such that they depend on
the relative motions of all other bodies on the loop. In the case of the four-bar linkage
(with all joints), the relative angle between bodies C and A depends on the angles of A
and B relative to ground.
Additional Constraints
Closed kinematical loops are handled in AUTOSIM by adding constraint conditions.
Constraint conditions are also needed if your model includes a type of joint beyond the
16 basic connection geometries that can be specified for a new body.
When adding constraints to your model, you will need to keep track of the DOF of
the system model. Before the constraint is added, there will be too many DOF, and
therefore, too many generalized speed variables, and, possibly, too many generalized
coordinate variables. When applying the commands to add constraints, you should
choose variables and speeds to remove, based on your knowledge of the model. In
general, the variables to remove are the ones that would be the most responsible for
causing the unallowable movements. Consider the four-bar linkage example. Just after
the three moving bodies are added, the model, as partially described to AUTOSIM, has
three DOF instead of one as it should. Each circular motion shown in the figure is
represented with a generalized coordinate and a generalized speed. That means that two
DOF must be removed with constraints. Suppose we are considering a constraint that
there should be no movement in the nx direction at the joint connecting bodies B and C.
From the figure, we can see that the rotation of C mainly causes movement in the
direction nx. Therefore, we would select the rotation and rotational speed of C as the
variables to eliminate when we constrain movement in the nx direction.
Most common mechanical joints provide constraint conditions that are relatively easy
to describe by eliminating relative motion between two points in a given direction.
Unconventional constraints can also be applied. There is almost no limit to the types of
constraint that can be applied to motion or position in AUTOSIM. The general approach
for describing a complex constrained motion is to give the body too many DOF, as it
might move if the complex joint were not present. Then, constraints are added to remove
the DOF in such a way so as to satisfy the constraint conditions.

5 11

5.2 Multibody Terminology and Definitions


Holonomic and Nonholonomic
Constraints

AUTOSIM 2.0

It is possible to constrain motion


without directly constraining position. For
ay
example, the simple planar model of a
ax
ny
unicycle shown in Figure 5.2.5 permits the
unicycle to move in the direction ax and to
nx
rotate, but not to move in the direction ay.
However, there are no constraints on the
Figure 5.2.5. Planar unicycle model.
location of the unicycle. This system
would be described by introducing a body with 3 DOF (two translations, one rotation),
and then introducing a constraint that the lateral velocity (in the ay direction) must be
zero. A constraint on motion but not position is called a nonholonomic constraint. In
contrast, constraints on position (e.g., the constraints in the four-bar linkage) are called
holonomic constraints.
Forces
A force is an action on a body that would cause the body to accelerate if an opposite
action is not also applied to the body. A force is represented mathematically as a vector
and a point. The magnitude of the vector has units of force (pounds or newtons). The
point and the direction of the vector define a line of action for the force. (The point is
necessary because a vector would otherwise not be associated with a specific location.)
The point is on the body affected by the force.
Newtons first law is that every action has an equal and opposite reaction. Every
action on a body is reacted, either by another body, or the inertial reference (ground). In
AUTOSIM, a single force is applied automatically to both bodies. The line of action is
the same for both bodies, but the magnitude is given the opposite sign for the second
body. Figure 5.2.6 shows how two bodies are affected by the same force. The line of
action of the force passes through points A1 and A2 in body A, and through B1 and B2 in
body B. The arrow head by point A1 shows the direction that the force acts on body A.
By Newtons law, the force must act in an opposite direction on body B, and this is
indicated by the arrow head by point B 1. Both points B1 and B2 lie on the line of action.
Therefore, either one could be used to describe the force as it acts on body B. Similarly,
both points A1 and A2 lie on the line of action, and could be used to describe the force as
it acts on body A. In fact, any one of the four points shown in the figure could be used
together with the direction vector to define the line of action of the force acting on either
body. Furthermore, any point on the line could be used to locate the line of action.

5 12

5.2 Multibody Terminology and Definitions

A2
A1

AUTOSIM 2.0

Force F
B2
B1

A
B

Figure 5.2.6. A force acting on two bodies.


Moments, Couples, and Torques
A moment is a cross product of a distance vector with a force. A moment is always
defined relative to a point, such that the distance vector in the moment is the position
vector connecting the reference point for the moment with any point lying on the line of
action of the force (see Figure 5.2.7.a). If two forces are applied to the same body with
the same magnitudes, opposite directions, and with distinctly different lines of action
spaced by some distance, the vector sum of the forces is zero. A pair of forces with these
properties is called a couple. Although the vector sum of the forces is zero, the vector
sum of the moments is not zero (see Figure 5.2.7.b). It is elementary to show that the
moment of a couple is the same for any point in a reference frame. The moment of a
couple is called a torque. A torque (also called a moment in all AUTOSIM
documentation) can be characterized by a vector. (The moments implied in Figure 5.2.7
would have directions pointing perpendicular to the plane of the figure.) Because the
choice of a reference point does not affect the definition of the couple, it is not necessary
to specify a point for a moment vector. The magnitude of the vector has units of length
times distance, and the direction of the vector is the direction of the moment.
F
F

M=dF

F
a. moment of force F about point P
b. couple consisting of two forces
Figure 5.2.7. Moments and Couples.
A moment is an action on a body that would cause the body to accelerate in rotation
about its mass center if an opposite action is not also applied to the body. Newtons first
law requires that every moment have an equal and opposite reaction. Every action on a

5 13

5.2 Multibody Terminology and Definitions

AUTOSIM 2.0

body is due to another body or to the inertial reference (ground). In AUTOSIM, a single
moment is applied to both bodies. The direction of the moment is the same in both cases,
but the magnitude is given the oppossite sign for the second body.
Angular Orientation of a Rigid Body
AUTOSIM automatically keeps track of the angular orientation of all rigid bodies in
the model. There is really no reason to be concerned with how the orientation is
represented, because the effects are generally accounted for with the functions dot,
cross, and angle. However, for the record, AUTOSIM maintains a direction cosine
matrix for each body, linking its orientation to that of its parent. Given a body B (with
unit-vectors bx , by , and bz), and parent body A (with unit-vectors a x, a y, and a z), the
direction cosine matrix C is defined as
b x ax
C = b y ax
b z ax

b x ay
b y ay
b z ay

b x az
b y az
b z az

(5.2.4)

Angular Velocity of a Moving Reference Frame


The angular velocity of a moving body is defined implicitly from the definition of the
derivative of a vector fixed in the reference frame:
.
b = B b

(5.2.5)

where vector b is fixed in body B, and B is the angular velocity of B. Note that angular
velocity is a property of an entire body, and not of a particular point in the body. For a
body constrained to planar motions, eq. 5.2.5 defines an angular velocity vector with a
direction perpendicular to the plane. For a body undergoing arbitrary three-dimensional
rotations, the direction of the angular velocity vector is not always obvious.
Mass and the Inertia Tensor (Dyadic)
The mass of a rigid body B is defined in Newtonian dynamics as a coefficient that
links the momentum vector and the velocity vector of the mass center, B*, according to
the equation
pB = mB vB*

(5.2.5)

where pB is the momentum vector of B, mB is the mass of body B, and vB* is the velocity
of the mass center B*. A similar property is defined for rotation. In this case, an inertia
tensor links the angular momentum vector with the angular velocity vector for the rigid
body
hB* = IB* B

5 14

(5.2.7)

5.2 Multibody Terminology and Definitions

AUTOSIM 2.0

where hB* is the angular momentum vector (relative to the body mass center B*), IB* is
the rotational inertia tensor for body B relative to B*, and B is the angular veloctity of
B.
The rotational inertia is a tensor of order 2. When describing the inertial properties of
a rigid body, you provide a 33 matrix such as
Ixx
I = Ixy
Ixz

Ixy
Iyy
Iyz

Ixz
Iyz
Izz

(5.2.8)

The values in the matrix are specific to a particular coordinate system. (When entering
the coefficients in a matrix, you can use any coordinate system in the model.) AUTOSIM
converts the matrix form of eq. 5.2.8 to a dyadic form, such as
I = Ixx ax ax + Iyy ay ay + Izz az az + Ixz ax az + Ixz az ax + Ixy ax ay
+ Iyx ay ax + Iyz ay az + Iyz az ay

(5.2.9)

The advantage of the dyadic form is that you can use the inertia dyadic without concern
for any required coordinate transformations. For example, suppose you want to define the
angular momentum of rigid body with the definition: h = I . When deriving an
expression for angular momentum as the dot product of a vector and dyadic, AUTOSIM
will perform any transformations automatically.

5.3 Overview of an AUTOSIM Analysis


The description of a model in AUTOSIM loosely follows the sequence shown in
Figure 5.3.1. In almost all steps, AUTOSIM generates equations automatically and
symbolically. The scope of this chapter is limited to models that can be built with no
manual programming, and therefore, the step for describing external variables and
routines is shown in gray in the Figure. (Chapter 6 covers this step.)
Table 5.3.1 lists the core AUTOSIM commands for describing your models.
Syntax of Commands
Details of using specific commands are presented in Chapter 8. However, in this
chapter, and the two that follow, several commands are described. When the syntax of a
command is shown, it is presented in a form such as the following:
no-movement point1 point2 direction {:q q} {:u u}
Each command or function may have a set of mandatory arguments that must be present,
and must appear in the correct order. Mandatory arguments are shown in italics
immediately after the symbol that identifies the function or command. For example, there
are three mandatory arguments to no-movement: point1, point2, and direction. There
can also be one or more optional arguments. Curly braces {} are used to indicate sets of

5 15

5.3 Overview of an AUTOSIM Analysis

AUTOSIM 2.0

reset the system

Optional steps (sequence


not important)

add rigid bodies and optional constraints

change default values


of parameters

describe optional external variables and routines

change names of
parameters

add optional active forces and moments


change units of
parameters
define optional output variables
finish the symbolic multibody analysis

change global
variables

write computer source code.

add optional
points

Figure 5.3.1. Sequence of AUTOSIM commands.


Table 5.3.1. Commands for building description of multibody system.
Command
Description
add-body
Add rigid body, point mass, reference frame, or
coordinate system to system model.
add-gravity
Add effect of uniform gravity field.
add-line-force
Add force with specified direction.
add-moment
Add moment with specified direction and magnitude.
add-point
Add point fixed or moving in a body.
add-position-constraint Remove generalized coordinate to satisfy equation.
add-speed-constraint
Remove speed variable to satisfy equation.
add-strut
Add force connecting two points.
motion
Constrain system coordinate to follow a function.
no-movement
Constrain movement between points in one direction.
arguments that are optional. If the braces are followed by an asterisk, {}*, the set
enclosed by the braces can be repeated. In most cases, optional arguments are identified
by keywords. They are shown in the Courier font. Keywords are easily recognized
because they always begin with a colon character. For example, no-movement has two
optional arguments, identified with the keywords :q and :u. Keyword arguments must
appear after the mandatory arguments, but can appear in any order with respect to each
other.

5 16

5.3 Overview of an AUTOSIM Analysis

AUTOSIM 2.0

Interactive Computer Algebra


Although the main purpose of AUTOSIM is to generate numerical analysis programs,
the computer algebra capability can also be useful. At any time, you can type live into
AUTOSIM. To enter an algebraic expression directly, enclose the expression in double
quotes and precede it by an exclamation mark, !. To assign an expression to an
external variable for future use, use the command setsym.
For example, Listing 5.3.1 shows a short interactive session in which AUTOSIM
derives expressions for the example system. In the listing, text you would type is shown
in boldface, and text generated by AUTOSIM is shown in a plain typeface. (Line
numbers have been added to aid the discussion. The computer screen did not show any
line numbers.)
Listing 5.3.1. Interactive session using AUTOSIM
1. ? !"pos(s0)"
2. (Q(2)*[nz] + Q(1)*[nx])
3. ? (setsym v "vel(s0)")
4. (U(1)*[sx] + (U(2) -PC(3)*U(3))*[sz])
5. ? v
6. (U(1)*[sx] + (U(2) -PC(3)*U(3))*[sz])
7. ? !"v*@v"
8. (V*U(1)*[sx] + (V*U(2) -PC(8)*U(3))*[sz])
9. ? !"dot(@v, [nz])"
10. ((U(2) -PC(3)*U(3))*C(3) -U(1)*S(3))
11. ? !"dxdt(@v)"
12. (-(-UP(2) + PC(3)*UP(3) + U(1)*U(3))*[sz] + (UP(1) + U(3)*(U(2) PC(3)*U(3)))*[sx])
13. ? !"partial(@v,wr)"
14. -PC(7)*U(3)*[sz]

In line 1, the function pos is used to obtain a vector to point S0 from the inertial
origin, rSo . The result from AUTOSIM involves two variables introduced by AUTOSIM,
Q1 and Q 2, and the unit-vectors nx and n z. In line 3, the command setsym is used to
generate a similar expression for the velocity of point S0, vS o and assign the expression to
an external AUTOSIM variable that we will name v. (AUTOSIM creates the variable v
and assigns a value). To see its value, we can type in its name, as in line 5. In subsequent
inputs, we can refer to vS o preceding the symbol v with the @ character, as is done in
lines 7, 9, 11, and 13. If the symbol v is used without the @ character, then AUTOSIM
treats it as an ordinary symbol. For example, see the result of the input in line 7, which
involves the symbol v and the expression assigned to the variable v. In line 9, the
component of vSo in the nz direction is defined with the dot function. In line 11, the time
vS o
.
is derived, where
derivative v S o is derived, and in line 13, the partial derivative W
R
WR is a model parameter.
The interactive computer algebra capability is not absolutely essential for obtaining
equations of motion. However, it offers a powerful tool for obtaining auxiliary equations
for alternate analyses, and for checking the correctness of the model as it is being
developed. The algebraic functions in AUTOSIM are described in Section 8.2.

5 17

AUTOSIM 2.0

5.4 Defining the Bodies and Joints


All of the AUTOSIM commands are described in detail in Section 8.1. As a reference
section, it covers the hows of using the commands. In this section, the major commands
for describing bodies and joints are discussed with an emphasis on the whys of using
them to define your model.
The Add-Body Command
The Add-body command is the fundamental tool for describing a multibody system
in AUTOSIM. All moving bodies and coordinate systems are defined with this command.
Add-body has one required argument, symbol, which identifies the body for future
reference. It has many other arguments that are optional, as indicated below by the terms
in braces {}:
add-body symbol

{:parent parent} {:mass mass} {:name string} {:inertiamatrix inertia-matrix} {:inertia-matrix-coordinatesystem matrix-coordinate-system}{:coordinate-system
coordinate-system} {:joint-coordinates joint} {:cmcoordinates c m} {:translate translate} {:bodyrotation-axes axes} {:parent-rotation-axis parentrotation-axis} {:reference-axis reference-axis} {:smalla n g l e s small-angles} {:small-translations smalltranslations} {:no-rotation no-rotation}

The reference documentation for this command is in Section 8.1. Without going into
a great deal of detail, the major pieces of information provided for the new body (called B
for short) are summarized below:
What existing body is the parent of B?
The :parent keyword is used to specify a parent other than the default, N.
How does B translate relative to parent?
The :translate keyword is used to convey the number of translational DOF
and the directions in which they occur.
How does B rotate relative to parent?
The :body-rotation-axes keyword is used to convey the number of
rotational DOF and the axes about which they occur.
Where is the origin of B relative to the origin of parent?
The origin of the coordinate system for B, B0, is nominally coincident with a
point in parent called the joint-point of B. If B has translational DOF, its origin
moves with respect to the joint-point. The joint point is defined with the
:joint-coordinates keyword.
How do the axes in B rotate relative to the axes in parent?
If B has no rotational DOF, the axes for the coordinate system of B are parallel
with those of parent. Otherwise, the first rotation of B occurs about an axis

5 18

5.4 Defining the Bodies and Joints

AUTOSIM 2.0

specified with the :body-rotation-axes keyword that is aligned with the


direction in parent specified with the :parent-rotation-axis keyword.
How are the axes in B aligned nominally relative to the axes in parent?
The nominal orientation of the coordinate system of B (when all angles are zero)
is determined by the direction identified with the :reference-axis keyword.
This axis is orthogonal to the vector identified with the :parent-rotationaxis keyword.
What are the mass and inertial properties of B?
The :mass and :inertia-matrix keywords are used if you do not want
AUTOSIM to automatically introduce parameters for the inertial properties. The
:cm-coordinates keyword is used if the center of mass is not located at the
origin of the coordinate system of B.
Is the body a point mass?
A point-mass is added as a body with no rotational degree of freedom (do not use
the :body-rotation-axes keyword or the parent-rotation-axis
keyword) and zero rotational inertia (use the :inertia-matrix keyword with
a value of zero).
Are any of the motions of B relative to parent small?
The keywords :small-angles and :small-translations can be used to
inform AUTOSIM that certain quantities are, in an engineering sense, going to
be small relative to other variables.
The add-body command is also used for several other modeling purposes. A body
can be added whose motions are not computed with differential equations in the
simulation code. Some reasons for doing this are the following:
Composite bodies
You can define a body with zero degrees of freedom so that AUTOSIM will
automatically add or subtract inertial properties to a composite body. To define a
body with no degrees of freedom, do not specify values with the keywords
:translate, :body-rotation-axes, or :parent-rotation-axis.
Auxiliary coordinate systems
You can define an auxiliary coordinate system in an existing body. To introduce
an additional coordinate system, describe the body as if it has a single rotational
degree of freedom. Specify the :body-rotation-axes, :parentrotation-axis, and :reference-axis to establish the nominal
orientation. However, to indicate that it does not rotate dynamically relative to
the parent, use the keyword :no-rotation with the symbol T. To avoid
affecting the inertial properties, specify :mass and :inertia-matrix values
of zero.
Moving reference frames
You can introduce a moving reference frame to help define output variables or
force directions. Add a body with the desired orientation, then remove the

5 19

5.4 Defining the Bodies and Joints

AUTOSIM 2.0

generalized coordinate and speed with the motion command. Be sure to set the
mass and inertia matrix to zero to avoid influencing the system dynamics.
State Variables
Section 1.5 introduced the general concept of state variables for a multibody system.
State variables are introduced automatically by AUTOSIM to mathematically describe
the state of the system, such that any position or speed variable of interest can be written
as an explicit function of the state variables. The number of state variables increases as
you add bodies, and decreases as you add constraints. AUTOSIM also has commands
that let you add your own state variables, to augment those required for the multibody
system. For example, you might include differential equations for a hydraulic system
linked to the rigid-body system. (Details of how you go about adding state variables will
be described in Chapter 6.)
Figure 5.4.1 shows all of the categories of state variables that are manipulated by
AUTOSIM. The primary categories are described in Table 5.4.1.
State Variables
Coordinates

Speeds

Generalized Coordinates

Generalized Speeds

Independent
Coordinates
Computed
Coordinates

Extra Coordinates

Extra Speeds

Figure 5.4.1. Categories of state variables.


The broadest set includes all state variables, and is divided into two groups:
coordinates and speeds. Coordinates are further divided into two sets: generalized
coordinates and extra coordinates. The generalized coordinates include all variables that
represent displacement in either translation or in rotation between the bodies. They have
units of length or angular displacement (e.g., in, rad), and are all introduced by
AUTOSIM to correspond to movements that you specified in the add-body commands.
The generalized coordinates are further divided into two groups: independent coordinates
and computed coordinates. The computed coordinates are not truly independent, and can
be computed from values of the independent coordinates using algebraic constraint
equations .

5 20

5.4 Defining the Bodies and Joints

AUTOSIM 2.0

The speeds are grouped in two categories: generalized speeds and extra speeds. The
generalized speeds include all variables that describe velocity between bodies, and have
units of length/time or angular rate (e.g., in/sec, rad/sec). The extra coordinates and extra
speeds are variables that you might have added (see Chapter 6).
Table 5.4.1. Definitions of primary types of state variables.
Type
Units
Description
Source Command
Independent
length, angle
translation or rotation of
add-body
Coordinate
body relative to parent
Computed
length, angle
translation or rotation of
add-body
Coordinate
body relative to parent
Extra Coordinate
anything
user-defined variable
add-state-variable
Generalized Speed
length/time,
speed variable
add-body
angle/time
Extra Speed
anything
user-defined variable
add-state-variable

Any multibody system that can be modeled with AUTOSIM can be analyzed without
ever viewing the names and definitions of the state variables. The functions tq, tu, rq,
and ru allow you to access any state variable, regardless of how it is currently named
(see Section 8.2.). However, if you are interested, the names and definitions of all state
variables can be viewed at any time using the print functions described in Section 5.9.
Be aware that AUTOSIM renumbers the state variables whenever a DOF is added or
removed, so it is not a good idea to refer to state variables by their indices. Each time
add-body is invoked, new independent coordinates and independent speeds are
introduced for each joint degree of freedom. For example, the variable q 3 might be
changed to q4 after a new body is added. Each time the constraint commands motion or
no-movement are applied, a generalized speed is removed and an independent
coordinate is redefined as a computed coordinate. The variables are are renumbered at
this time, also. For example, the variable q4 might be changed to q2 after a constraint is
added. The command add-speed-constraint causes a generalized speed to be
removed without affecting the coordinates, and the command add-positionconstraint causes an independent coordinate to be redefined as a computed
coordinate without affecting the speeds.
The Motion Command
The simplest way to constrain movement is with the motion command. Its syntax is
motion q exp
This removes a DOF by assigning a generalized coordinate q to an expression exp,
and setting a generalized speed to the derivative of exp. This command only works if the
derivative of the generalized coordinate is a generalized speed. If the state variables are

5 21

5.4 Defining the Bodies and Joints

AUTOSIM 2.0

defined such that this is not true, you should revise your AUTOSIM input as described in
a later subsection (Controlling the Definitions of the State Variables).
The No-Movement Command
The no-movement command is a convenient way to describe constraints that
prevent the relative movement of two points in some direction. Its syntax is
no-movement point1 point2 direction {:q q} {:u u}
where point1 is a point in one body and point2 is a point in a second body (or ground).
Table 5.4.2 summarizes some common situations where joints are added with the nomovement command. In each case, point1 is a point on the first body constrained by the
joint, and point2 and direction are set to define the type of joint.
Table 5.4.2. Some joints that can be added with no-movement command.
Joint
System
Point2
Direction(s)
point on plane
3D
point in plane
to plane
sliding
planar point fixed in line of sliding in plane, to line of sliding
sliding
3D
point fixed in line of sliding 2 times: to line of sliding
and each other
pin joint
planar
joint location in second
2 times: in plane, to each
body
other
ball-joint
3D
joint location in second
3 times: to each other
body
cylinder
3D
point fixed joint axis
2 times: to joint axis and
each other

This command does not require that you specify the coordinate and speed to remove.
However, you are nearly always better off if you specify the variables to remove with the
optional keyword arguments :q and:u.
Generic Constraint Commands
In addition to the holonomic constraints applied by joints, a system may also be
subject to nonholonomic constraints. These are constraints on motion but not position or
orientation, as was shown in the unicycle example (see Figure 5.2.5). Each nonholonomic
constraint is handled with the command add-speed-constraint.
Not all joints can be accommodated with the no-movement command. For unusual
joints, use the add-speed-constraint command is together with the command
add-position-constraint to eliminate a speed variable and a coordinate.
The add-speed-constraint and add-position-constraint commands
search for a variable to eliminate. You are nearly always better off if you specify the

5 22

5.4 Defining the Bodies and Joints

AUTOSIM 2.0

variables to remove with the optional keyword arguments :q and:u. Also, the following
guidelines should be considered.
Guidelines for Defining Joints
Joints that are defined in the add-body command are handled by algorithms that
lead to highly efficient formulations by taking advantage of the topology of your model.
Contraints defined with the motion command also lead to efficient equations. Joints
defined with commands no-movement, add-position-constraint, and addspeed-constraint involve much more symbolic computation, and do not take
advantage of topology. Also, as noted above, the constraint functions require some
judgement on the part of the modeler.
The best results are usually obtained by using the following guidelines:
1.

Minimize the use of additional constraints to define joints. If at all possible, use
add-body to define a tree that includes all joints in the model.

2.

Avoid long chains in the tree (chains will be described shortly).

3.

When it is necessary to add constraints, use the no-movement command if


possible.

4.

Use your knowledge of the system to select the variables to remove (using the :q
and :u keywords), rather than letting AUTOSIM choose the variables.

To illustrate these guidelines, consider the four-bar linkage example, shown again in
Figure 5.4.2. Assume that our description of this system begins with the definitions of the
seven points shown, as was done in Appendix D of the Introductory Guide to AUTOSIM.
Next, our job is to describe the three moving bodies and the joints connecting them.
Figure 5.4.3 indicates four ways of describing this system. In the graphs, constraints
between a body and its parent are shown with solid lines, and additional constraints are
shown with dotted lines.
2
N

3
g

C
4

nx
8
6

Figure 5.4.2. Four-bar suspension model.

5 23

5.4 Defining the Bodies and Joints

AUTOSIM 2.0

Case a in
Figure 5.4.2 is
the same as was
A
B
A
B
A
A
C
B used in the
Introductory
Guide
to
AUTOSIM.
C
C
C
After the bodies
are added, two
no-movement
B
commands are
applied to add
a.
b.
c.
d.
the joint at point
Figure 5.4.3. Four topologies for the four-bar linkage.
8
between
bodies B and C.
Case b is similar, except that when body C is added, body B is defined as its parent,
rather than A. The two no-movement commands are used to add the joint between
bodies A and C at point 3. Case c represents a description in which A is the parent of C,
which is the parent B. After the bodies are added, the joint betwen B and N at point 6 is
added with two no-movement commands. In cases a, b, and c, each body is given a
single rotational DOF when it is added. In case d, body C is defined with N as the parent.
Although C can only rotate relative to A or B, it moves in the n x and ny directions
relative to N, and rotates as well. Therefore, it is given two translational DOF and one
rotational DOF. After the three bodies are added in case d, the system has 5 DOF. Four
constraints are added to define the joints at points 3 and 8. (Two no-movement
commands are needed to define each of those joints.)
N

Based on the four guidelines, the descriptions represented in the first two graphs
would be preferred. Case c has a long chain (three levels, rather than the two levels in
cases a and b), and case d requires more constraint commands than the other descriptions
(four no-movement commands are needed, rather than the two needed for the other
three cases).
Other modeling considerations are presented in Chapter 7.
Controlling the Definitions of the State Variables
This section describes the manner in which AUTOSIM introduces state variables. If
you are not interested in controlling the definitions of the state variables, feel free to skip
ahead.
If you use AUTOSIM to generate simulation programs, there is usually no reason to
be concerned with how the state variables are defined. Regardless of their definitions,
you can instruct AUTOSIM to write any conceivable variable into the output files
generated by the simulation program, as described in Section 5.6. However, you may
wish to control how the variables are specified to make it easier to specify a constraint.

5 24

5.4 Defining the Bodies and Joints

AUTOSIM 2.0

Or, you may wish to generate equations for your own type of analysis, that might require
a certain form.
State variables are introduced automatically when you use the add-body command
to define a body that can move relative to its parent. One generalized coordinate is
introduced for each DOF of the new body relative to its parent, and the coordinates are
simply the amplitudes of the permitted movements. By defining generalized coordinates
this way, the equations of motion for a tree-type system involve a minimum number of
coordinates.
With each coordinate, a speed variable is also introduced automatically. The speed
variable is defined as the derivative of the coordinate, except for the following three
cases:

A body with three rotational DOF relative to its parent the three rotational
speed variables are defined as scalar measures of the absolute rotational velocity
of the body

A body with three translational DOF relative to its parent the three
translational speed variables are defined as scalar measures of the absolute
velocity of the body mass center

A body restricted to planar motions, with two translational degrees of


freedom the translational speeds are defined as scalar measures of the
absolute velocity of the body mass center

You can force AUTOSIM to define all generalized speeds as derivatives of the
coordinates by describing the system using bodies with just one DOF. For example, if a
free body with 6 DOF is introduced with a single add-body command, the speeds are
defined as components of velocity in the local coordinate system. Consider the following
example:
(add-body b :translate (x y z) :body-rotation-axes (x y z))
(print-speeds)
INDEPENDENT SPEEDS
==================
U(1): Abs. X trans. speed of
U(2): Abs. Y trans. speed of
U(3): Abs. Z trans. speed of
U(4): Abs. X rot. speed of B
U(5): Abs. Y rot. speed of B
U(6): Abs. Z rot. speed of B

BCMC (m/s)
BCMC (m/s)
BCMC (m/s)
(rad/s)
(rad/s)
(rad/s)

The kinematical equations below illustrate that the speeds [U(1) ... U(6)] are not the
derivatives of the generalized coordinates [QP(1) ... (6)]:
QP(1) = U(3)*S(5) + C(5)*(U(1)*C(6) -U(2)*S(6))
QP(2) = -(U(3)*C(5)*S(4) -U(2)*(C(4)*C(6) -S(5)*S(4)*S(6)) -U(1)
&
*(C(4)*S(6) + C(6)*S(5)*S(4)))
QP(3) = U(3)*C(5)*C(4) + U(2)*(C(6)*S(4) + C(4)*S(5)*S(6)) +
&
U(1)*(S(4)*S(6) -C(4)*C(6)*S(5))
QP(4) = (U(4)*C(6) -U(5)*S(6))/C(5)
QP(5) = U(5)*C(6) + U(4)*S(6)

5 25

5.4 Defining the Bodies and Joints

AUTOSIM 2.0

QP(6) = U(6) -QP(4)*S(5)

The same physical component can be described as six separate bodies, where the first
five are massless. Each of the six bodies has just one DOF:
(add-body b1 :translate x :mass 0 :inertia-matrix 0)
(add-body b2 :parent b1 :translate y :mass 0
:inertia-matrix 0)
(add-body b3 :parent b2 :translate z :mass 0
:inertia-matrix 0)
(add-body b4 :parent b3 :body-rotation-axes x :mass 0
:inertia-matrix 0)
(add-body b5 :parent b4 :body-rotation-axes y :mass 0
:inertia-matrix 0)
(add-body b :parent b5 :body-rotation-axes z)
(print-speeds)
INDEPENDENT SPEEDS
==================
U(1): Abs. X trans. speed of B10 (m/s)
U(2): Y trans. speed of B20 rel. to B1 (m/s)
U(3): Z trans. speed of B30 rel. to B2 (m/s)
U(4): X rot. speed of B4 rel. to B3 (rad/s)
U(5): Y rot. speed of B5 rel. to B4 (rad/s)
U(6): Z rot. speed of B rel. to B5 (rad/s)

In this case, the kinematical equations confirm that the speeds are defined as derivatives
of the coordinates:
QP(1)
QP(2)
QP(3)
QP(4)
QP(5)
QP(6)

=
=
=
=
=
=

U(1)
U(2)
U(3)
U(4)
U(5)
U(6)

5.5 Adding Forces and Moments


Movements of a multibody system are the result of forces and moments applied to the
bodies. Forces and moments are described below under three categories:
1.

gravitational forces,

2.

working contact forces and moments and field-effect forces other than gravity,
and

3.

non-working contact forces and moments (sometimes called reaction forces and
moments).

5 26

5.5 Adding Forces and Moments

AUTOSIM 2.0

Gravity
The effects of a uniform gravitational field are very easy to add to your model. The
command add-gravity automatically accounts for all downward gravitational forces.
The syntax of the command is
add-gravity {:direction direction} {:gees symbol}
The command assumes a uniform gravitational field, which has the same effect
regardless of the location of the body within the field. Normally, the only argument you
would use is the direction, to specify the direction in which gravity acts. For the four-bar
linkage example, the direction would be specified as ny. The default is the nz direction
the American standard for vehicle dynamics models.
The treatment of gravity applied by the add-gravity command is valid for models
of systems that are operated on or near the surface of the earth. For some spacecraft
models, where the variation in gravity as a function of distance from the earth may
influence the motions, you might need to add gravity forces as if they were working
contact forces acting on the bodies from the inertial reference N.
Working Forces and Moments
After all of the bodies and constraints are defined, the remaining elements in a
multibody model are those that generate working forces and moments. Forces and
moments are described by vectors. There are three commands you use to add them to
your model:
add-line-force
add a force when the direction of the line of action is easily described.
add-strut
add a force whose line of action passes through two established points in
different bodies.
add-moment
add a pure couple. (Moments due to forces defined with add-line-force and
a d d - s t r u t are automatically included. Only moments that have no
corresponding forces should be added with this command.)
The Add-Line-Force Command
This command defines a force in the system that passes through a given point and
whose line of action has a specified direction. Its syntax is
add-line-force symbol
{: n a m e s t r i n g } {:direction direction}
{:magnitude magnitude} {:point1 point1} {:point2
point2} {:x x} {:x0 x0} {:v v} {:no-forcem no-forcem}
where symbol is a symbol used later to identify the force. The force element has a given
direction, specified using any AUTOSIM vector expression. The magnitude of the force

5 27

5.5 Adding Forces and Moments

AUTOSIM 2.0

is specified as an AUTOSIM scalar expression. The line of action for the force is defined
by point1 and direction. The point point1 serves two roles: (1) it defines the location of
the line of action, and (2) it identifies the body upon which the force acts (the body
containing point1 is subject to the action of the force). The other point, point2, also serves
two roles: (1) it identifies the body that reacts the force, and (2) it is used, together with
point1, to define a relative displacement and velocity that can be used in the expression
for the force magnitude. (See the full description in Section 8.1 for details.) Be aware that
point2 does not necessarily lie on the line of action for the force.
The add-line-force command is normally used to describe the following kinds
of forces:

moving contact forces, such as sliding, rolling, aerodynamics, etc.

forces generated by compliant structures, such as leaf springs, beams, etc.

force components for structures or elements with multi-dimensional forcedeformation properties, such as bushings or structures characterized by stiffness
matrices.

The add-line-force command is used to describe the spring, damper, and tire
forces in the example vehicle ride model. It is also used to describe the vertical force
applied to body C in the example four-bar linkage model.
The Add-Strut Command
This command defines a force whose line of action passes through two established
points in different bodies. Its syntax is
add-strut symbol {:name string} {:magnitude magnitude} {:point1 point1}
{:point2 point2} {:x x} {:x0 x0} {:v v} {:no-forcem noforcem}
where the arguments are identical to those used in add-line-force, except that there
is no direction argument. Here, the line of action for the force is defined as a line passing
through points point1 and point2.
This command is used to add a physical element whose end-points are easily seen
from a drawing of the system. For example, it is used to describe the spring shown in the
four-bar linkage example. It is important to define points such that the direction of the
line connecting them remains valid (with respect to the force element model) as the
system goes through its normal range of motion. Elements where the line of action does
not pass through the attachment points are often described easier (and more correctly)
with the add-line-force command.
In general, equations derived by AUTOSIM as the results of the add-strut
command are more complex than those derived as a result of the add-line-force
command.

5 28

5.5 Adding Forces and Moments

AUTOSIM 2.0

The Add-Moment Command


This command introduces the moment of a pure couple between two bodies.
(Moments due to forces acting between bodies are derived automatically by AUTOSIM.)
Its syntax is
add-moment symbol {: n a m e string} {:direction direction} {:magnitude
magnitude} {:body1 body1 } {:body2 body2} {:no-forcem
no-forcem}
where the arguments are similar to those used in add-line-force, except that the
point arguments point1 and point2 are replaced with body arguments body1 and body2.
This is the only command for putting in a moment that is not the result of a force.
Because the direction argument can be any vector expression, and the magnitude
argument can be any scalar expression, the possibilities for including couples in the
model are almost limitless.
Non-working Constraint Forces and Moments
Geometric constraints imply that forces and moments are applied to the bodies to
enforce the constraints. When analyzing the forces and moments acting on a rigid body
by hand, an elementary tool is the free body diagram, which shows every force and
moment acting on the body. For example, Figure 5.5.1 shows the free body diagram for
body A in the four-bar linkage. Forces applied at points 1 and 3 can be decomposed into
vertical and horizontal components as shown.
F1y

F3y
M1

F1x

M3
F3x

3
1
Figure 5.5.1. Free-body diagram for link A in the four-bar suspension.
An increment of work due to a force is defined as the product of an incremental
distance and the component of a force vector acting in the direction of the incremental
distance. For example, the incremental work associated with a spring involves the spring
force multiplied by the incremental change in spring length. If there is no incremental
movement, then there is no incremental work. For angular movements, an increment of
work due to a moment is defined as the product of the incremental rotation angle (in
radians) and the component of the moment acting in the direction of the incremental
rotation. If there is no incremental rotation, then the moment does no work.
The nature of a pin joint is that it prevents translational movement, but does not
restrict rotation about the axis of the pin. Therefore, the two moments shown in the
figure, M1 and M3, are zero, and the four forces, F1x, F1y, F3x, and F3y, are in general,
not zero. Because the pin joints prevent translational movement, point 1 on body A
coincides with point 1 in the inertial reference, N. With no incremental movement, the
forces F1x, F1y , F3x , and F 3y, can never do work. Hence, they are called non-working
5 29

5.5 Adding Forces and Moments

AUTOSIM 2.0

forces. Non-working forces are the result of constraint conditions. If the constraint
conditions are taken into account, then the non-working forces do not add any
information about the system, and they are not needed to predict the motions of the
system.
When building your description of the model, you do not have to include nonworking forces and moments. If a force cannot cause a movement along its line of action,
you dont have to include it. For example, none of the forces shown in Figure 5.5.1 need
to be included in your model description. If a moment cannot cause a rotation about an
axis parallel with the direction of the moment vector, you dont have to include it. If you
do include a non-working force or moment, it will not influence the dynamic motions of
the model.
Although non-working forces and moments do not influence the dynamic behavior of
a multibody system, they may be of interest. Non-working forces and moments,
generated in reaction to constraint conditions, can be calculated as output variables in an
AUTOSIM-generated simulation program using two special functions:
rfvect the resultant reaction force vector for a body and all of its children in the
topology.
rmvect the resultant reaction moment vector for a body and all of its children in
the topology. The moment is taken about the origin of the specified body.
The method used by AUTOSIM to compute a resultant force vector with the function
rfvect is very simple. Newtons law can be written
B
fR = mB aB* ( f)B

(5.5.1)

B
where fR is the reaction force vector for body B and its children, m B is the mass of B,

aB* is the acceleration of the mass center of B, and ( f)B is the sum of all known forces
acting on B. In other words, the sum of all forces acting on B is divided into categories of
the known forces ( f) and a resultant unknown force, fB
R . AUTOSIM applies eq. 5.5.1 to
bodies with no children, to determine a resultant reaction force for each. Then, it applies
the equation to each parent. However, when analyzing the parent, the reaction force for
the child is a known force, and is therefore added in the ( f) part of the equation. The
process is continued recursively until the parent is N, the inertial reference.
A similar method is used by AUTOSIM to compute reaction moments to support the
rmvect function. In this case, the analysis is more complex because the Euler equation
requires that AUTOSIM deal with the (1) angular acceleration, (2) all known pure
moments, (3) the moment of the DAlembert force (m B aB*) about a reference point, and
(4) the moments of all known forces about the reference point. The basic method is the
same, however, with AUTOSIM starting with children bodies and then analyzing parent
bodies recursively until reaching the inertial reference.

5 30

AUTOSIM 2.0

5.6 Defining Auxiliary Variables


AUTOSIM automatically introduces state variables, derivatives of state variables,
force variables, and moment variables. There are occasions where you may wish to
define auxiliary variables in building your model.

If you are generating code for a simulation language (ACSL, ADSIM), you may
want to define variables that appear in the equations of motion but which are
computed outside of the equations generated by AUTOSIM.

If you are generating code for a linear analysis language (MATLAB), you need
to distinguish between symbols that represent constants (i.e., parameters) and
variables.

If your model has circular dependencies in force definitions, you can easily
generate approximate equations by copying some forces as auxiliary variables, to
use values from the previous time step. (Circular dependencies will be defined
later in this subsection.)

You define auxiliary variables with the command add-variables, and assign
expressions to the variables with the command add-equation.
If you are generating a Fortran simulation code, you need to specify what variables
the simulation program is supposed to calculate. (The commands for specifying Fortran
output variables are listed later in this section.)
The Add-Variables and Add-Equations Commands
The command add-variables is used to declare that a symbol varies with time, as
opposed to being a constant parameter. The syntax for using this command to declare that
symbols vary with time is
add-variables dyvars real {variable}*
The first argument (dyvars) indicates that the variables might be used in any program
block where equations appear, and the second argument (real) indicates that the
variables are floating-point, with the default precision (single or double, as defined by the
global *double-precision*). All remaining arguments define variables that you
plan to use in developing your model. Each variable should be either a symbol that you
will use to represent a variable, or a dimensioned array of variables with the form
"name(dimension)", e.g., "A(100)".
The command add-equation is used to place an equation into a region of the
simulation program, in any language. The syntax of this command is
add-equation where symbol exp {:comment string}

31

5.6 Defining Auxiliary Variables

AUTOSIM 2.0

where the argument where identifies the region in which the equation appears, and the
equation itself has the form
symbol = exp
Simulation Languages
If you are generating code for a simulation language, then you may wish to maintain
some equations in a part of the code that can be easily changed. For example, suppose
you want to add a force to your ACSL model in such a way that the user can easily
change the defining equation for the magnitude of the force. Further, suppose that the
force could be defined using the add-line-force command as follows for a body
with a single translational DOF:
(add-body b :translate z)
(add-line-force f1 :point1 b0 :direction [nz] :magnitude "-k*tq(b)")

The above force definition is a spring acting on body B from the ground, with a spring
rate K. The following commands create an equivalent set of equations:
(add-body b :translate z)
(add-variables dyvars real f1)
(add-line-force f1 :point1 b0 :direction [nz] :magnitude f1)
(add-equation derivative f1 "-k*tq(b)")

See how the force definition has been split into two commands: the add-lineforce command still defines the direction of the force and the point through which it
acts. However, the magnitude has been simplified from the expression -k*tq(b) to the
symbol F1, which was declared as a variable in the preceding add-variables
command. The default equation for F1 is defined by the add-equation command.
Linear Analysis
If you are generating linearized matrices for MATLAB, then excitations that would
be represented by algebraic expressions, splines, or linearly interpolated tables in a time
simulation must instead be represented by simple symbols. The add-variables
command must be used to define those symbols as variables, to prevent AUTOSIM from
defining them as model parameters. Appendix A of the Introductory Guide to AUTOSIM
shows how the same model is treated for simulation and linear analysis. Table function
ROAD(X), used to define inputs at the front and rear axle, is replaced by two variables:
ZF and ZR that represent the same inputs.
Circular Dependencies in Force Definitions
In some models, definitions of force magnitudes are mutually dependent. For
example, consider a system in which there is a friction force, whose magnitude is
proportional to a reaction force. The friction force cannot be calculated in the simulation

5 32

5.6 Defining Auxiliary Variables

AUTOSIM 2.0

program unless there is a value for the reaction force, and the reaction force cannot be
calculated until values are available for all accelerations. The equations have the form
Ff = f(Fr)

.
u = f(Ff)

.
Fr = f(u )

(5.6.1)

.
where Ff is a friction force, Fr is a reaction force, and u is the set of derivatives of the
generalized speeds. The three parts of eq. (5.6.1) cannot be sorted for sequential
calculation because there is a circular dependency.
A traditional method for time simulation programs is to use an estimate of one of the
forces to get started. For example, suppose that we replace eq. (5.6.1) with
Ff = f(Fr)

.
u = f(Ff)

.
Fr = f(u )

(5.6.2)

where Fr is an estimate of Fr. In time simulations, the value from the previous time step
is most commonly used.
You can use definitions of the form of eq. 5.6.2 by adding an auxiliary variable to
store the force at each time step, so the value is still available at the next time step. The
value of the auxilary variable should be assigned in the UPDATE part of the program.
For example, suppose the force being stored is identified by the symbolic name F2. Then,
the way to save a copy of that force value is as follows:
(add-variables dyvars real f2copy)
(add-equation update f2copy "fm(f2)")

In the definition of any forces whose magnitudes depend on F2, but which are defined
before force F2 is added, you would use F2COPY, the estimate of F2.
One problem with this approach is that we are introducing an artificial dynamic effect
into the model. There is a slight phase lag associated with using a force from a previous
time step. If the force is associated with a relatively high frequency in the system, the
phase lag may be significant if the time step is not kept small. Thus, it may be necessary
to use a smaller time step than would otherwise be needed if the delayed force values
were not used.
Circular dependencies occur mainly for two reasons: (1) forces are dependent in some
fashion on accelerations (such as the reaction forces in the above example), and (2) the
inertial properties of a body are neglected, resulting in a quasi-static force or moment
balance for a subsystem. As an example of the second reason, consider an automobile
with compliance in the steering system. The side forces generated by the tires, that steer
the vehicle, are nonlinear functions of the steer angle of the wheel. However, the steer
angle of the wheel is influenced by the side force applied to the wheel by the tire.
Other methods for handling circular dependencies are described in Section 7.1.

5 33

5.6 Defining Auxiliary Variables

AUTOSIM 2.0

Fortran Output Variables


The purpose of a simulation program is usually to generate time histories of variables
of interest. Thus, it is essential to specify exactly which variables from the model are of
interest. The command add-out is used to specify virtually any output variable that you
can conceive. Additionally, there are a few commands that automatically specify that the
simulation code generated by AUTOSIM include groups of standard variables as output
variables. These commands are listed in Table 5.6.1.
Table 5.6.1. AUTOSIM commands for specifying outputs.
Command
Action
add-accelerations-to-output
Add derivatives of speeds to output list.
add-coordinates-to-output
Add generalized coordinates to output list.
add-forces-to-output
Add all active forces to output list.
add-moments-to-output
Add all active moments to output list.
add-out
Define an arbitrary output variable.
add-speeds-to-output
Add generalized speeds to output list.
add-standard-output
Add state variables, accelerations, forces,
and moments to output list.
These commands can be used at any time after all bodies and constraints are
described, and before the analysis is finished. Also, they should be used after all of the
variables of interest have been defined. For example, add-forces-to-output
should not be used until all of the forces have been introduced. (The only forces added to
the list of outputs are those that have been introduced when the add-forces-tooutput comand is applied.)
A list of all output variables is maintained by AUTOSIM. The commands in the table
add variables to this list, which is later used when writing the subroutines OPNOUT and
OUTPUT in the simulation code. At any time, the list can be viewed with the command
print-outputs.

5.7 Installing Nonlinear Tabular Functions


It is very common for multibody models to include arbitrary functional relations
between two variables that are based on a table of X-Y values provided by the end user at
run time. The function typically has the form: F(X), where X is a floating-point value
computed in the equations of motion. Including a table function in your model is easy.
Just refer to the function in your AUTOSIM commands as if it exists. For example, a
nonlinear spring force might be defined with the command
(add-line-force f :point1 b0 :direciton [nz] :magnitude "-spr(tq(b))")

where SPR is some function that returns a force as a function of displacement.

5 34

5.7 Installing Nonlinear Tablular FunctionsAUTOSIM 2.0


Of course, for the generated code to run, you must make sure that the function does in
fact exist and is properly linked to the generated code. If you are generating code for a
simulation language such as ACSL or ADSIM, then you will normally define the tables
of values using built-in capabilities of the languages. If you are generating code in
Fortran, use the command install-table to automatically generate Fortran code for
the function and several supporting subroutines to read, write, and initialize data for the
table. The syntax of the command is
install-table function title {:default default} {:echo echo} {:read read}
{:deriv deriv} {:npts npts} {:ntabs ntabs} {:tablefunction table-function} {:common common} {:xunits
xunits} {:yunits yunits} { :keyword keyword} {:id i d }
{:values values}
The name of the new function is specified by the mandatory argument, function. A string
of text printed in output files is specified by the other mandatory argument, title. (Other
arguments are defined in the reference description listed in Section 8.1.)
There are four kinds of built-in table-lookup methods, which are compared in Figure
5.7.1 for the four-point table: ((1 1) (1.5 1.1) (2.5 2) (3 3)).
5

tabe

spline

tabf
splinf

2
3
2
1
1
0

0
0

2
3
4
0
1
2
Figure 5.7.1. Examples of four table functions.

5.8 Specifying the Analysis


The analysis commands are listed in Table 5.8.1. Generally, the first entry in an
AUTOSIM input file is the command reset, and one of the the last entries is the
command finish. The commands dynamics, linear, and equilibrium are used
to specify details of the analysis.
After the dynamics, linear, or equilibrium command is applied, the system is
frozen and further elements such as bodies and forces cannot be added. however, it is still

5 35

5.8 Specifying the Analysis

AUTOSIM 2.0

possible to enter new points, define output variables, and use the AUTOSIM symbolic
algebra capabilities to view expressions for variables derived from the system
description. After the finish command is applied, it is no longer possible to add output
variables.

5 36

5.8 Specifying the Analysis

AUTOSIM 2.0

Table 5.8.1. Commands for analyzing.


Command
Action
dynamics
Perform dynamics analysis using options.
equilibrium
Perform equilibrium analysis.
finish
Finish up dynamics analysis.
finish-update
Finish up equations in subroutine UPDATE.
kinematics
Derive kinematical equations for multibody system.
linear
Derive and linearize equations of motion.
reaction-forces
Derive reaction force vectors.
reaction-moments
Derive reaction moment vectors.
reset
Clear description of multibody system and initialize.

There are several formal procedures (formalisms) that can be used to derive the
equations of motion. These are selected using the :formalism keyword for
dynamics, as described in Chapter 8.
The finish command causes AUTOSIM to inspect the equations and identify the
ones that are significant. Symbols and equations that are not needed are not included in
the AUTOSIM-generated source code.

5.9 Viewing Results of the Analysis


At any time during a session with AUTOSIM, information about the system can be
viewed. The printing commands are used to generating documentation about the model,
and for debugging the model and checking that the description is as intended.
Commands for Printing
Table 5.9.1 lists the commands for printing information about the current state of the
model.
Recommended Debugging Checks
After the system has been analyzed with dynamics and the equations have been
checked with finish, it is a good idea to use the commands shown in bold print in
Table 5.9.1. The commands print-parameters, print-default-directions,
and print-default-positions are particularly useful after default numerical
values have been assigned to all parameters via the set-defaults command (see
Section 5.10).

5 37

5.9 Viewing Results of the Analysis

AUTOSIM 2.0

Table 5.9.1. Commands for printing.


Command
Action
print-bodies
Print data for all body objects.
print-body
Print data for one body object.
1
print-constraints
Print replacement expressions for
dependent speeds.
print-coordinates1
Print definitions of generalized
coordinates.
1
print-default-directions
Print numerical coordinates of all unitvectors.
1
print-default-positions
Print numerical coordinates of all points.
1
print-forces
Print definitions of all active forces.
print-kane
Print Kane dynamic terms for a body.
print-kanes1
Print Kane dynamic terms for all bodies.
1
print-moments
Print definitions of all active moments.
1
print-outputs
Print definitions of all output variables.
print-parameters1
Print definitions of all parameters used in
equations.
1
print-points
Print definitions of all points.
print-rf
Print data for one reaction force object.
print-rfs1
Print data for all reaction force objects.
1
print-speeds
Print definitions of generalized speeds.
1
print-symbols
Print all symbols from AUTOSIM input.
rtf
Print results of commands in RTF format.
1 Can be used with the write-to-file command to route the printed information to a file.

The command print-parameters should always be used to view the dimensions,


masses, etc. that appeared in expressions communicated to AUTOSIM, or in some cases,
which were introduced automatically. Every symbol appearing in the list produced by
print-parameters should look reasonable. If there are any dimensions or
coefficients that were not intended to be included, they may be the result of a misspelled
name in an input, or an incorrect use of an AUTOSIM command. If any parameters
thought to be important do not appear, it is an indication that either (1) there was an input
error such that AUTOSIM did not properly receive the expression involving the
parameter, or (2) even though the parameter appeared in the input, it is not required to
simulate the system.

5 38

AUTOSIM 2.0

5.10 Customizing the AUTOSIM-Generated Program


AUTOSIM automatically builds a list of all parameters that appear in the final
equations of motion. Most of these are parameters that you use in expressions passed as
arguments to commands such as add-body, add-line-force, etc. In addition,
AUTOSIM automatically introduces symbols for mass and inertia terms if you accept the
default settings in add-body.
Properties of AUTOSIM Symbols
In addition to manipulating symbols that represent parameters and variables in the
multibody model, AUTOSIM also maintains additional information about each symbol,
as summarized in Table 5.10.1
Table 5.10.1. Properties of symbols maintained by AUTOSIM.
Property
Application
Example Value
name
string used in labels
speed of BCM rel. to origin, [bx]
units
used to apply scale factors and
L*F/A
generate labels
small-order simplification of equations
0
default
numerical value when user does
300.0
not provide value
const-or-var is symbol constant or variable?
const

Table 5.10.2 lists commands that are used to assign attributes to symbols representing
parameters and variables.
Table 5.10.2. Commands for setting attributes of symbols and expressions.
Command
Action
in-lb
Set units system to in-lb, with degree, gs.
install-indexedInstall one-dimensional parameter arrays.
parameters
large
Declare symbol is large.
mks
Set units system to SI, with degree, gs.
set-defaults
Set default numerical values of symbols.
set-derivs
Set derivatives of symbols.
set-names
Set names of symbols or expressions.
setsym
Set values of globals and external symbols.
set-units
Set units for symbols.
si
Set units system to SI (angle=rad, acceleration=m/s).
small
Declare symbol is small.

5 39

5.10 Customizing the AUTOSIM-Generated Program

AUTOSIM 2.0

Names assigned by AUTOSIM to symbols are correct, but generic. You will often
have a name in mind that will have more meaning to the intended user of the simulation
code. (For example, use the command set-names to replace speed of BCM rel. to
origin, [bx] with forward vehicle speed)
An ambiguity exists when you use an expression such as F(2). Is F(2) a function
whose argument is 2, or is F(2) the second element in an array of parameters? AUTOSIM
uses the same rule as most compilers: if the symbol followed by parentheses has not been
declared as an array, it is assumed to be a function. Thus, a special command, installindexed-parameters, is used to declare an array of indexed parameters.
AUTOSIM Units Expressions
AUTOSIM manages units conversions, from user units to and from dynamics units.
Every parameter and variable symbol in equations derived by AUTOSIM has an
associated units expression. The units expression involves generic units names, such as L
for length, F for force, etc. For example, a spring stiffness parameter would typically
have the units expression F/L. The units systems that are provided with AUTOSIM
involve units whose symbols are assigned to global variables. Table 5.10.3 lists those
globals, the default symbols, and the descriptions. Note that mass is not included: units of
mass are defined with the units expression F*T2/L.

Global
*angle*
*counts*
*degree*
*force*
*gees*
*length*
*time*

Table 5.10.3. Global units-symbols variables.


Default
Description
A
angular units (e.g., deg, rad)
C
integer units (e.g., counts, cycles)
DR
conversion coefficient: deg/rad (57.3)
F
force units (e.g., lb, N)
G
gravitational constant (e.g., 386.2, 9.80665)
L
length units (e.g., in, ft, m, mm)
T
time units (e.g., sec)

AUTOSIM deduces the units associated with each symbol from its context. When
angles are involved, an ambiguity exists and the units assumed by AUTOSIM might not
be what you had in mind. You will have to set the units in such cases with the command
set-units. When setting the units for a parameter, the value should be an expression
involving the symbols shown as defaults in the above table.
AUTOSIM commands and functions that have arguments for units, such as
install-table, expect the units to be specified as expressions built from the symbols
listed in Table 5.10.3.
The units expressions attached to each variable and parameters are not dependent on a
specific units system. A dimension has units of length, regardless of what those units are

5 40

5.10 Customizing the AUTOSIM-Generated Program

AUTOSIM 2.0

called. AUTOSIM maintains tables that are used when generating code and labels to
determine properties of each units expression. Table 5.10.4 lists the three properties
associated with units expressions.

Property
name
gain
generic
name

Table 5.10.4. Properties of AUTOSIM units expressions.


Application
Example
string used in labels
in-lb/deg
scale factor: (user units)/(dynamics unist)
1/DR
string used in labels
Torsional stiffness

AUTOSIM comes with three built-in units systems, which are installed with the
commands in-lb, mks, and si. The command install-units can be used to
augment the existing units system or override settings. The syntax of the command is
install-units units {:name name} {:gain gain} {:gen-name generic-name}
where units is a units expression. Name is the string printed for the units in all labels.
Gain is an expression or number used to convert to a dynamics units system (values in
user-units are divided by gain to convert to dynamics units). The generic name is used in
some labels as a default for a variable based solely on its units.

5.11 Generating the Numerical Analysis Program


AUTOSIM supports a variety of computer languages for showing the equations
derived for a multibody system. Commands for writing code and documentation are
listed in Table 5.11.1. All of the commands can be used to generate output code in the
AUTOSIM window. However, it is more likely that you will want to route the output to a
file. The command write-to-file is used to do this. The command has the syntax
write-to-file command file-name
where command is the name of a write command from Table 5.11.1 and file-name is the
name of a destination file that should include path-name information, if necessary, is
appropriate for your operating system. For example, the command to generate a Fortran
simulation program might be
(write-to-file write-sim "model2/version1/sim.f")

On the Macintosh platform, a command write-mac-file performs the same


function as write-to-file, but takes advantage of the Mac interface.
The global variable *target-language* determines the syntax of equations
printed in the AUTOSIM window. The valid values for this variable are the symbols
fortran, acsl, adsim, c, matlab, and rtf. (Change the value using the setsym
command.) However, the setting does not have any effect on the output generated by the
most of the functions listed in Table 5.11.1.
5 41

5.11 Generating the Numerical Analysis Program

AUTOSIM 2.0

Table 5.11.1. Commands for writing.


Command
Action
write-acsl
Write simulation program in ACSL and Fortran.
write-adsim
Write simulation program in ADSIM.
write-c
Write set of C functions with equations of motion.
write-difeqn
Write subroutine DIFEQN.
write-dolud
Write subroutine DOLUD.
write-echo
Write subroutine ECHO.
write-eqs
Write equations of motion in RTF form.
write-eqs-doc
Write background documentation for equations.
write-fct
Write subroutine FCT for dynamics program.
write-fct2
Write subroutine FCT for equilibrium program.
write-finish
Write subroutine FINISH.
write-fortran-doc
Write documentation for Fortran simulation program.
write-help
Write all on-line help for AUTOSIM commands.
write-help-globals Write all on-line help for AUTOSIM globals.
write-init
Write subroutine INIT.
write-initr
Write subroutine INITR.
write-input
Write subroutine INPUT.
write-inteqs
Write subroutine INTEQS.
write-main
Write MAIN Fortran program block.
write-matlab
Write code in MATLAB for generating matrices.
write-newtr1
Write subroutine NEWTR1.
write-opnout
Write subroutine OPNOUT.
write-output
Write subroutine OUTPUT.
write-pederv
Write subroutine PEDERV.
write-precmp
Write subroutine PRECMP.
write-quasi
Write subroutine QUASI.
write-setdef
Write subroutine SETDEF.
write-sim
Write complete Fortran program.
write-sim-minimal
Write Fortran program without library routines.
write-to-file
Apply a write command, sending the output to a file.
write-update
Write subroutine UPDATE.
Note: All of the above commands work with the write-to-file command.

5 42

CHAPTER 6

USING EXTERNAL CODE


6.1 Why Use External Code? 2
6.2 Single-Valued Functions 3
6.3 Subroutines and Multiple-Valued Functions 3
The Add-Subroutine Command 4
The Add-Variables Command 5
Adding Parameters for External Fortran Code 5
Example 6
6.4 Equations 7
6.5 Adding State Variables 7
6.6 Installing Differentials 8

This chapter explains how you include code not generated by AUTOSIM into your
models. You can also extend your model by augmenting the equations of motion for the
mechanical system to include equations for additional state variables.
You describe the external code such that it is properly included in AUTOSIMgenerated programs. In addition to the material in this chapter, you should become
familiar with the design of the simulation code, described back in Part 1.
There are three kinds of code that you can use in an AUTOSIM-generated program:

single-valued functions,

subroutines and multiple-valued functions, and

equations.

It may also be necessary to install the information needed by AUTOSIM to derive


derivatives of external functions and variables.

61

AUTOSIM 2.0

6.1 Why Use External Code?


Why use external code? Usually, you add code because there is some functionality
that you want in the simulation program that is not standard in AUTOSIM. Table 6.1.1
lists some common reasons. The exact reasons will be specific to your model and the
requirements of the end user.
Table 6.1.1. Reasons for Using External Code.
Objective
Possible Solution(s)
Compute forces or torques using
1. Use external function in definition of
complicated procedures.
force/moment magnitude, or,
2. add subroutine to DIFEQN that returns
magnitude as argument.
Compute complicated output
1. Use function to define output variable, or,
variable.
2. add subroutine to OUTPUT that returns
variable of interest as argument.
Stop simulation under certain
Put subroutine in UPDATE that changes STOPT
conditions.
simulation parameter to a value T.
Read parameters used by external
1. Add subroutine to INPUT that reads from
procedures.
buffer (same line) or from file (next line(s)),
or,
2. use add-parameters command.
Echo parameters used by external
1. add subroutine to ECHO that writes
procedures.
information into output file, or,
2. use add-parameters command.
Set default values of parameters
Add routine that sets default values from within
used in external routines.
subroutine SETDEF.
Initialize dependent parameters and Add routine with initializations to subroutine
variables used in external routines. INIT.
Prompt user for additional inputs.
Add routine with user prompts to subroutine INIT.
Use procedures that calculate new Perform the update operation (saving the new
values based on old values.
value) in a separate subroutine call made from
UPDATE.
Integrate variables independently
Include an integration in a subroutine called from
of the multibody state variables.
UPDATE.
Compute and print summary
Perform the computations in a subroutine called
statistics.
from UPDATE. Compare T and STOPT; when T
STOPT, the run is over and the summary should
be printed.

62

AUTOSIM 2.0

6.2 Single-Valued Functions


A single-valued function provides an output value based on values of zero or more
arguments. It is used the same way as built-in functions such as SIN, ABS, etc. Functions
are very easy to incorporate into AUTOSIM: just refer to the function as if it exists. For
example, consider a function TIREF that takes a single argument ALPHA and returns a
value. Suppose the TIREF function is used to define a force with the add-line-force
command:
(add-line-force fy2 :direction [b2] :point1 br
:magnitude "tiref(angle([b1], vel(br), [n3]))")

The Fortran code generated as a result of the above is:


FORCEM(1) = TIREF(ATAN2(((A -L)*U(3) + U(2)), U(1)))

As far as AUTOSIM is concerned, external functions are indistinguishable from


functions that are built into the target language. It is your responsibility as a model
builder to properly link to the external code according the the methods employed for your
Fortran compiler or simulation language.
It may be that AUTOSIM will need to take a partial derivative or time derivative of
an external function. If an error message is printed, indicating that there is no information
about how to take the derivative, then a rule for differentiating the function must be
installed with the command install-differential.

6.3 Subroutines and Multiple-Valued Functions


A Fortran subroutine is invoked with the CALL statement. If the subroutine has no
arguments, the syntax is of the form
CALL SUB1

where SUB1 is the name of the subroutine. If there are arguments, the syntax is
CALL SUB2(A1, A2, ... AN)

where SUB2 is the name of the subroutine, and A1, A2, etc. are Fortran expressions
passed as arguments. Arguments are used both for passing input data to the subroutine,
and returning output data from the subroutine. The arguments must be of the proper data
type expected by the subroutine (integer, real, character, etc.). Arguments passed as
inputs to subroutines can be any valid Fortran expression. However, arguments used to
receive data from the subroutine must be Fortran variables.
In a simulation language such as ACSL or ADSIM, a routine that returns more than
one value is called a multiple-valued function. The calling convention for multiple-valued
functions explicitly identifies arguments as being inputs or outputs. For example, a
function with two output values and three input arguments is invoked as follows:

63

6.3 Subroutines and Multiple-valued Functions

AUTOSIM 2.0

o1, o2 = mulfun(i1, i2, i3)

where o1 and o2 are the output values, and i1, i2, and i3 are the input arguments of
the function mulfun.
There are several commands to instruct AUTOSIM about an external subroutine or
multple-valued function.
The Add-Subroutine Command
The add-subroutine command instructs AUTOSIM to write code to invoke a
subroutine or multiple-valued function. The syntax is
add-subroutine where name arguments {:comment string} {:keyword keyword}
where the argument where tells AUTOSIM the location of the call to the routine, name is
the name of the routine, and arguments is a list of input and output arguments for the
routine.
Subroutines and multiple-valued functions are more complicated to include in your
models than single valued functions, because you must specify where the subroutine or
function is invoked. It must be invoked after all information needed for input arguments
is available, and before any of the output variables are used. Table 6.3.1 lists the valid
locations that can be assigned to the argument where.
Table 6.3.1. Places where external code can be added.
Keyword
Language
Location
Purpose of external code
adsim
ADSIM
DYNAMIC
calculate forces and moments
derivative
ACSL
DERIVATIVE calculate forces and moments
derivative
Fortran
DIFEQN
calculate forces and moments
1
difeqn
Fortran
DIFEQN
calculate forces and moments
discrete
ACSL
DISCRETE
calculate stuff at discrete intervals
echo
Fortran
ECHO
print data into an echo file
finish
Fortran
FINISH
calculate stuff at end of run
input
Fortran
INPUT
read input data associated with keyword
init
ADSIM
INITIAL
perform initializations before run
init
Fortran1
INIT
perform initializations after all inputs
init
MATLAB
perform initializations before run
kinematics
Fortran
INITNR,
calculate variables involving
DIFEQN
kinematical constraints
output
Fortran
OUTPUT
compute output variables
1
setdef
Fortran
SETDEF
assign default values to program
variables
start
ACSL
before DERIV initialize ACSL variables
1
update
Fortran
UPDATE
calculate stuff once per time step

64

6.3 Subroutines and Multiple-valued Functions

AUTOSIM 2.0

1 also used for ACSL

The Add-Variables Command


The command add-variables is used mainly for two reasons: (1) to declare that a
symbol varies with time, as opposed to being a constant parameter, and (2) to define
variables that appear in external subroutines (added with the command addsubroutine) that receive values from the subroutines. The first application was
described in Section 5.6, and the second application is discussed here.
If you add a subroutine or multiple-valued function that computes output variables
that appear in the equations for your model, then you must declare the variables with this
command to tell AUTOSIM that the symbols represent variables, rather than constant
parameters. The syntax for the command is
add-variables where type {variable}*
The argument where is the location of the subroutine using the variables (see Table
6.3.1). The argument type is the type of variable expected by the subroutine (integer, real,
etc.). If the variable is a floating-point number, use the symbol real and AUTOSIM will
declare it as single or double precision, based on the value of the global variable
*double-precision*.
Each variable should be either a symbol that you will use to represent a variable, or a
dimensioned array of variables with the form "name(dimension)", e.g., "A(100)".
Adding Parameters for External Fortran Code
AUTOSIM scans the equations of motion for unknown symbols that it will add to the
list of model parameters. You can also force AUTOSIM to add parameters with the
commands:
add-parameters
This command adds specified symbols to the list of parameters that are read and
echoed by the simulation program. They are stored in the common block
/INPARS/.
add-hidden-parameters
This command adds specified symbols to the list of parameters that are read by
the simulation program. They are stored in the common block /INPARS/.
However, they are not echoed by the program. These are usually indices or
auxiliary parameters used to control the interpretation of keywords in the INPUT
subroutine.
install-indexed-parameters
This command adds specified one-dimensional arrays to the list of parameters
that are read and echoed by the simulation program. They are stored in the
common block /INPARS/.

65

6.3 Subroutines and Multiple-valued Functions

AUTOSIM 2.0

All parameters are declared as floating point numerical Fortran variables, using the
precision defined by the global variable *double-precision*. If you need an integer
as an argument for a subroutine, use the Fortran INT function to convert the floating
point parameter to an integer, as shown in the example below.
Example
If you add an external subroutine to the INPUT part of a Fortran code, the subroutine
may require extra input arguments that determine how it reads inputs. For example,
suppose a subroutine RDEXT(X, I) sets an internal variable to the value of X, with the
choice of which variable to set being determined by the value of I. If the simulation code
is to maintain the keyword-based PARSFILE format for all inputs, the end user would
use one keyword to set I, and another to set X. For example, a portion of an input
PARSFILE might read
* ID is an index ID, and XKEY is a keyword for the value passed to RDEXT
id 1
xkey 100.
id 2
xkey 250.

Suppose we want the simulation program to process the above input as follows:
whenever the keyword XKEY is encountered, the subroutine RDEXT is called, with the
first argument assigned to the value read for XKEY, and the second argument assigned to
the parameter ID. Thus, the above input would cause to calls to RDEXT, equivalent to
CALL RDEXT(100., 1)
CALL RDEXT(250., 2)

Code would be generated by applying the following commands:


(add-hidden-parameters xkey id)
(add-subroutine input rdext (xkey "int(id)") :keyword xkey)

Excerpts of the actual generated Fortran code that calls the subroutine are shown
below:

ELSE IF (KEY .EQ.


READ(BUFF2, 140)

ELSE IF (KEY .EQ.


CALL RDEXT(XKEY,

'ID') THEN
ID
'XKEY') THEN
INT(ID))

The echo file would not include code to write the most recent values of XKEY and
ID, because they were defined as hidden parameters. Typically, you would have an
external subroutine that would echo this type of information, e.g., subroutine
WRTEXT(X, I).

66

AUTOSIM 2.0

6.4 Equations
There are several reasons that you might want to augment the equations derived by
AUTOSIM with additional equations that you define by hand. Three common reasons
are:

to control the locations of describing equations in simulation codes generated for


simulation languages such as ACSL (see section 5.6),

to save values for the next time step, to handle models with circular dependencies
(see section 5.6), and

to define the derivatives of auxiliary state variables (see next section).

You can add your own equations with the command add-equation. The syntax is
add-equation where symbol exp {:comment string}
where the equation has the form
symbol = exp
and the argument where identifies the location for the equation. Table 6.3.1 lists the valid
locations that can be used for the where argument (these are the same as those associated
with the add-subroutine command).

6.5 Adding State Variables


The add-state-variable command is used to add a state variable that would not
otherwise be included in the multibody model. Generally, this is done when the
multibody system includes a sub-system with its own dynamics. For example, a
controller might have dynamics involving voltages. Another example is that a hydraulic
system might have dynamics involving fluid flow and pressure. The syntax of the
command is
add-state-variable symbol deriv units {:type type}
Symbol is a symbol to use for the new coordinate. Deriv is a symbol to use for its
derivative. Units is an expression for the units of symbol.
Because AUTOSIM has no information about what the new variable represents, you
must provide information for computing a value for deriv. To do this, you need to add an
equation with the command add-equation, or, an external subroutine, as defined with
add-subroutine. (The where argument for either add-equation or addsubroutine should be either kinematics or difeqn.)

67

AUTOSIM 2.0

6.6 Installing Differentials


AUTOSIM derives derivatives and partial derivatives of expressions under certain
conditions, such as:

linear analysis requires partial derivatives of forces, moments, and DAlemberts


forces with respect to the state variables;

equilibrium analysis requires partial derivatives of forces and moments with


respect to the state variables;

dynamics analysis requires time derivatives of terms in constraint equations; and

auxiliary variables might involve derivatives of any motion variables.

AUTOSIM determines derivatives symbolically, and must be able to take the


differential of any symbol or function appearing in the equations. All of the necessary
rules exist for dealing with built-in functions and variables and parameters introduced
automatically by AUTOSIM. However, you may have to add rules for variables and
functions that you have added. Two commands exist for this purpose. The first,
install-differential, is used to install the knowledge of how the differential is
obtained for a function or variable. The second, set-derivs, can be used only for
variables. It does not add any functionality beyond that provided by installdifferential, but it is slightly more convenient to use.

68

CHAPTER 7

ADVANCED TOPICS
7.1. Modeling Issues 2
Friction 2
Lash, Intermittent Contact, and Collisions 4
Flexible Bodies 5
Circular Dependencies 6
7.2. Computation Speed 7
Type of Formulation 7
The Mass Matrix 8
The Order-N Option 9
Combining Masses 10
Constraints 10
Computer Algebra Settings 11
7.3. Programming New Commands 12
Sources of Lisp Information 12
Lisp Basics 12
Example New Command 14
Lisp Forms Used 17
Summary of Example Command 19
Restrictions of AUTOSIM Commands in Lisp Functions 19
AUTOSIM Data Types 20

This chapter describes advanced uses of AUTOSIM that were not covered in the
previous chapters. Section 7.1 covers methods for modeling systems that have historically
been difficult to simulate. Section 7.2 covers the topic of computation speed, and reviews
the options available for maximizing run-time performance of AUTOSIM-generated
simulation programs. Section 7.3 illustrates by example how elementary Lisp capabilities
can be used to define new AUTOSIM commands.

71

AUTOSIM 2.0

7.1. Modeling Issues


This section describes some tricks for modeling multibody elements that are not
associated with common algebraic descriptions. The first subsections deal with nonlinear
behaviors such as friction, lash, and impact.
Most nonlinear model elements are components that generate forces and moments.
They are relatively easy to include in AUTOSIM models by way of the standard commands
add-line-force, add-strut, and add-moment. All three of these commands
allow the magnitude of the force or moment to be an algebraic expression, which gives you
almost unlimited modeling options. One approach that can always be used for forces and
moments that are not easily represented with standard algebraic functions is to write an
external routine in Fortran (or another target language, such as C, ADSIM, etc.), and use
that function in the algebraic expression. This becomes necessary when the force is defined
by a set of equations and a series of conditional IF statements. However, if Fortran is the
target language, the functions built into Fortran permit limited conditional definitions. Four
nonlinear functions that can be used to good effect are abs, max, min, and sign.
Example equations involving these functions are shown in the remainder of this section.
Friction
Friction forces exist in most multibody systems. The nature of a pure Coulomb friction
is shown in Figure 7.1.a. The force depends on a normal force Fn , a friction coefficient ,
and the direction of sliding. The sign function (intrinsic in Fortran) might be used to
define a friction force Fcf as follows
.
Dont use!
(7.1.1)
Fcf = sign(| Fn|, x )
.
where x is the rate at which the two parts slide past each other. However, if you use the
above definition in a simulation model, you are asking for numerical trouble. Although a
real friction force lies somewhere between Fcf when the sliding rate goes to zero, the
.
simple equation does not include this critical behavior. If x is slightly positive, a negative
.
friction force is generated, causing x to go negative at the next time step. Then, the
.
negative value of x causes a positive friction force that causes the system to move such
.
that x is positive at the next time step. Rather than settling peacefully into a static
equilibrium when the sliding stops, a model based on eq. 7.1.1 can oscillate with a period
of twice the integration time step.
Although eq. 7.1.1 is not recommended for general use to represent friction, it can be
used for models in which the system is never allowed to settle into an equilibrium state.
Rotating machinery, or systems constantly subjected to forced motions may be adequately
modeled with the above simple representation.
Figure 7.1.1.b shows an approximation that is sufficient for representing the behavior
of friction in most systems. A simple equation form is
.
.
(7.1.2)
Fcf = sign(min(|x | Cf, | Fn|), x ) Saturating Damper
.
where Cf is a damping rate. For large values of x , the force has the magnitude | Fn|, as in
.
the case of pure Coulomb friction. However, for small values of x , the equation behaves
72

7.1. Modeling Issues

AUTOSIM 2.0
Fcf

.x

a. True Coulomb Friction


Fcf

.x

b. Saturating Damper
Fcf

.x

c. Complex Curve Approximation


Figure 7.1.1. Coulomb friction.
as a linear damper. The parameter Cf should be selected based on model characteristics,
such that with a typical integration time step, it takes several steps to settle to the condition
.
x = 0.
To use either of the above two approximations in your AUTOSIM model, you would
type in an equation of the proper form for the force magnitude in an add-line-force or
add-strut command.
Even with a properly selected value of C f, the sharp corners in the function shown in
Figure 7.1.1.b can cause minor problems if you run the simulation with a variable-step
integrator. Figure 7.1.1.c shows a more complex approximation that eliminates the
corners. The friction force is approximated with a shaping function as
.
Complex Approximation
(7.1.3)
Fcf = | Fn| shape(x )

73

7.1. Modeling Issues

AUTOSIM 2.0

.
where shape(x ) is a shaping function. You can define the shaping function by writing a
custom function, or by using the AUTOSIM install-table command.
Lash, Intermittent Contact, and Collisions
Mechanical systems in which bodies collide or make intermittent contact have
historically been challenging to simulate. Common examples are cam-followers, joints with
lash, and collisions. When two parts in the system may be in contact for more than an
instant, the system has fewer DOF during that time. For example, a cam follower has zero
DOF if its motion is completely defined by the cam shape. However, when the parts are not
in contact, they move independently.
The most common approach for modeling this behavior is to define a force that is the
result of the contact, whose magnitude is a nonlinear function of displacement and velocity.
The force magnitude is zero when the parts are not in contacts. When the distance between
the two points is less than some threshold, then the force is the same as a spring and
damper element, in which the spring and damper rate are high enough that the stiffness
does not introduce a dynamic effect that interacts with the frequencies of interest.
In AUTOSIM, the element is introduced with the add-line-force command.
Supposing that the distance between points is x, and contact occurs when x<x0, then a
function that would provide the nonlinear behavior of interest could be
.
F = max[sign(1, x0 x), 0] [K (x-x0) + C x ]

(7.1.4)

Note that the max function has a value of 1 when x0 > x (during contact), and a value of 0
otherwise.
There are two practical problems associated with this modeling approach. First, values
must be assigned to the spring and damping coefficients that are sufficiently high that the
new resonance frequencies introduced to the system are much higher than those of interest.
Second, the presence of these stiff springs and dampers make the model stiff, requiring that
the stiff integrator be used to solve the equations. It is also important to always include
damping, and to set the damping coefficient proportional to the spring stiffness.
The spring and damper rates need not be associated with real properties of the system.
Typically, valid simulation results can be obtained using rates that are much lower than the
real material properties. By using lower rates, the simulation program can be run faster
with less likelihood of numerical instabilities. If possible, you might want to define the
spring and damper rates in the model as functions of masses, or hard-wired with
numbers, to eliminate the potential problem that the end user might select inappropriate
values that cause dynamic interactions (with rates too low) or stability problems (with rates
too high).
Another modeling approach for this type of behavior is to generate two models: one
with the reduced DOF for the case of contact, and another for the additional DOF when
they are not in contact. You would have to hand-write some code in the target language

74

7.1. Modeling Issues

AUTOSIM 2.0

(Fortran, C, etc.) to switch between equation sets based on some condition associated with
contact.
Flexible Bodies
AUTOSIM derives equations of motions only for multiple rigid-body systems. It does
not deal automatically with flexible elements such as beams and plates, nor with finite
element solvers. However, there are several ways to model flexible bodies in AUTOSIM.
The most common method is to model a flexible body as several lumped mass elements
connected by springs and dampers, with the spring and damper coefficient selected to
match material properties. In the spacecraft example, compliance in the boom was modeled
as a hinge with two rotation DOF. If a flexible body is broken up into several masses, then
add each with the add-body command. You can set the masses and inertias of the parts to
be fractions of an overall mass parameter. For example, consider the model of a beam
shown in Figure 7.1.2.
ny

M/3
nx

M/3

M/3

L/6
L/3

L
Figure 7.1.2. Lumped mass model of a beam.
The above model could be described with the following add-body commands:
(add-body b1 :translate (x y) :parent-rotation-axis z
:mass "m/3" :inertia-matrix ("izz/9" 0 0)
:joint-coordinates (0 0 0) :cm-coordinates ("L/6" 0 0))
(add-body b2 :parent b1 :parent-rotation-axis z :small-angles t
:mass "m/3" :inertia-matrix ("izz/9" 0 0)
:joint-coordinates ("L/3" 0 0) :cm-coordinates ("L/6" 0 0))
(add-body b3 :parent b2 :parent-rotation-axis z :small-angles t
:mass "m/3" :inertia-matrix ("izz/9" 0 0)
:joint-coordinates ("L/3" 0 0) :cm-coordinates ("L/6" 0 0))

The commands for elements 2 and 3 are nearly identical, because the default coordinate
system for the joint coordinates is the parent, and the default coordinate system for the
center of mass coordinates is the new body. Note that the three parts are described using
the beam length, L, the beam mass, M, and the beam inertia about the Z axis, Izz. Also,
knowing that the relative movements will be small, the :small-angles keyword is used
to obtain simpler equations. In addition to the add-body commands, it is also necessary
to add two torsional springs with the add-moment command to provide bending
stiffness.

75

7.1. Modeling Issues

AUTOSIM 2.0

A method that is sometimes used to include flexible body mode shapes in models used
to study vibrations is to use a rigid body oscillator to obtain the vibrational motions, and
then use a shaping function to estimate the contribution of the vibration at different points in
the structure. This method can work when the rigid body vibrations drive the vibrations of
a flexible body, but the body flexing has negligible influence on the rigid body vibrations.
A more rigorous method for including flexible elements is through the use of an
external subroutine that computes forces at various points in the structure based on
displacements. Suppose there is a subroutine that takes as input ten displacement values,
and produces as output ten corresponding forces. Including the subroutine in an
AUTOSIM model is no different than as was described in Section 6.3. Using the vector
algebraic functions of AUTOSIM, you can define any required displacements (and
velocities) between points located on rigid bodies as inputs. Using add-line-force,
you can properly include all forces generated by the subroutine into the rigid body
equations.
Circular Dependencies
In some models, you will find that various force definitions are interdependent. When it
is impossible to sort the equations for sequential calculation, the equations are said to be
circular. Circular dependencies occur mainly for two reasons: (1) forces are dependent in
some fashion on accelerations (e.g., reaction forces), and (2) the inertial properties of a
body are neglected, resulting in a quasi-static force or moment balance for a subsystem.
This problem was introduced in Section 5.6 and a method was presented for using
auxiliary variables to work around the problem. When the circularity is due to a
dependency of a force on acceleration, the method in Section 5.6 is the only tested method
that has been used in AUTOSIM. However, when the circularity is due to part of the model
being treated quasi-statically, there are other options. Three different techniques have been
used with AUTOSIM models:
1. values from the previous time step are used to break the circularity of the
equations, as described in Section 5.6;
2. the model is defined to include an extra DOF, such that the force or moment
balance is determined dynamically, rather than quasi-statically; or
3.

an external subroutine is added to perform a quasi-static analysis for the dependent


variables.

The first technique was described in Section 5.6 and will not be repeated. For the
second and third techniques, consider as an example an automobile with compliance in the
steering system. The side forces generated by the tires, that steer the vehicle, are nonlinear
functions of the steer angle of the wheel. However, the steer angle of the wheel is
influenced by the side force applied to the wheel by the tire. In reality, the wheel does not
deflect instantly in response to applied forces. It is a modeling decision to treat the
deflection of the wheel as either (1) a quasi-static response to applied forces, or (2) a
dynamic response, with the wheel steer given a DOF such that the steer angle changes
dynamically in response to applied forces. If the model includes the dynamical DOF, then

76

7.1. Modeling Issues

AUTOSIM 2.0

there is no circularity. The steer angle is computed by integrating the differential equations,
and is no longer an algebraic function of the applied forces.
The reasons for going with a quasi-static representation, rather than a dynamic one, are
typically (1) the dynamic model has more differential equations, and (2) the eigenvalue
associated with the additional DOF is beyond the frequency range of interest. If the DOF is
included, the model may become stiff and require that a stiff integrator be used to solve
the equations of motion. As a rule of thumb, a model developed with a quasi-static
representation and the simple approximation described in Section 5.6 will run much faster
than one with the dynamics in it if the equations of motion are otherwise not stiff.
However, if the model already has some high eigenvalues in it, then there may be little or
no penalty for including the additional dynamics to eliminate the circular dependency.
The third technique for handling a quasi-static force balance is to create an external
routine that performs the quasi-static equilibrium analysis. In the automotive steering
example, we might create a subroutine that takes as inputs variables contributing to the steer
angle, and which produces as output the side force from the tire and the steer angle due to
compliance. Of the three techniques listed here, the third approach often leads to the best
run-time speed. The method described in Section 5.6 requires that the time step be kept
small enough to reduce the significance of phase-lag errors associated with using values
from the previous time step. The method of including the extra dynamical DOF requires
that the integration method deal with the much faster eigenvalues introduced.
Version 2.0 of AUTOSIM generates equations for equilibrium or dynamic simulation,
but not both together. Therefore, some programming is required to apply the third
technique. To reduce the programming, you can use AUTOSIM to generate an equilibrium
analysis program for the quasi-static subsystem (e.g., the wheel and compliant steering
connections), and then modify the generated code to make an external subroutine. Unless
you are confident in your understanding of the operation of equilibrium analyses, it will
probably be the most productive to use the first technique, described in Section 5.6.

7.2. Computation Speed


The computer time needed to simulate a dynamic multibody system depends on (1) the
computer hardware, (2) the formulation of the equations of motion, and (3) the type of
algorithm used to numerically integrate the equations. This section addresses the second
area, by describing options in AUTOSIM that influence the formulation of the equations of
motion. (The third area, involving integration algorithms, was covered in Section 2.2.)
Type of Formulation
Since the early 80s there have been dozens of papers published each year describing
new formulations for multibody systems. When the formulations are written in generic
form, the number of arithmetic operations needed to compute the derivatives is often
reported as a function of N, the number of degrees of freedom of the system. There are

77

7.2. Computation Speed

AUTOSIM 2.0

several discrepancies in how a given model is described that can confound theoretical
comparisons.
The value of N associated with a model can may be defined differently for different
formulation methods. Note that the formulation obtained with AUTOSIM always involves
a minimal set of generalized speeds, such that N is the number of dynamical DOF. For
example, the four-bar linkage has just one DOF. In most of the multibody dynamics
literature, the number of dynamical equations is larger then the number of DOF for
constrained systems. For the four-bar linkage example, N would be at least 3 in most other
formulations, and often much higher to include auxiliary equations added to account for
constraint conditions.
A second source of variation in the computational complexity in equations generated by
AUTOSIM is due to the symbolic simplifications that are made. Models with rotation axes
that are parallel require less complex equations than models with tilted rotation axes. The
effects of the simplifications are highly dependent on the specific model. The only reliable
way to determine the efficiency of the equations generated by AUTOSIM is to generate the
code and run it.
As a general rule of thumb, the only sure-fire way to compare two formulations for a
given model is to try both, and time the simulation runs on the same computer. (This is true
for formulations obtained with AUTOSIM and those obtained by other methods.)
The Mass Matrix
When the dynamical equations of motion are obtained by traditional means, they occur
with the implicit form:
.
Mu = f

(7.2.1)

where M is called the mass matrix, with dimensions N, u is the array of N generalized
speeds, and f is the generalized force array, with dimension 1N. The elements of M are
time-varying functions of the generalized coordinates, q, and the elements of f are timevarying functions of the coordinates q and the generalized speeds, u.
In order to obtain the derivatives of the speeds, it is necessary to uncouple the equations
by transforming eq. (7.2.1) from the implicit form into an explicit form:
.
u = M -1 f

(7.2.1)

As described in Section 2.2, simultaneous linear equations are commonly solved with
lower-upper triangular decomposition (LUD). If performed numerically, the uncoupling
involves a number of arithmetic operations proportional to N 3. As N grows large, the
.
decomposition dominates the effort associated with calculation of the derivatives u . Thus,
the computational work associated with dynamical equations that have a mass matrix is
usually considered to be proportional to N3.
When performed symbolically, the LUD solution involves fewer operations if the mass
matrix contains zeros. For example, the transformation is trivial if M is diagonal: solving
the equations involves no more then dividing each row by the diagonal element of M. On
78

7.2. Computation Speed

AUTOSIM 2.0

the other hand, if M contains no zeros, then the LUD solution obtained symbolically has
the same complexity as the numerical solution .
AUTOSIM includes several formulation options that are specified with optional
keyword arguments in the dynamics command, as described in Section 8.1. They
involve two classes of dynamics formulations.
The most versatile analysis options in AUTOSIM involve derivations based on Kanes
method, which involves a mass matrix. Equations are obtained in the form of eq. (7.2.1).
There are two options involving the mass matrix, which are specified with arguments to the
dynamics command. The first option, specified with the :formalism keyword, is
whether the transformation of eq. (7.2.1) to the form of eq. (7.2.2) is done symbolically or
numerically. If done numerically (use the symbol numerical-lud), AUTOSIM spends
less time to derive the equations. If done symbolically (the default), more time is needed,
with the potential payoff that the equations obtained will be more efficient. When the
analysis is performed, AUTOSIM prints a map of the mass matrix. For example, when the
example spacecraft model is processed, the following map is printed:
(*
(*
(0
(0
(0
(*
(0
(0
(*
(*

*
*
0
0
0
0
*
*
*
*

0
0
*
*
0
*
0
*
*
*

0
0
*
*
*
0
*
*
*
*

0
0
0
*
*
*
*
*
*
*

*
0
*
0
*
*
*
*
*
*

0
*
0
*
*
*
*
*
*
*

0
*
*
*
*
*
*
*
*
*

*
*
*
*
*
*
*
*
*
*

*)
*)
*)
*)
*)
*)
*)
*)
*)
*)

Because the above map includes some zeros, the symbolic solution is more efficient to
run than the numeric one. However, if the map contained no zeros, then there would be no
advantage to the symbolic decomposition.
With many system models, the elements of M change very slowly relative to the
elements of f. AUTOSIM includes an option to insert code to compute the elements of M
and the decomposition only when the elements have changed enough to matter. This option
is enabled by providing a value of T with the keyword :conditional-lud in the
dynamics command. For systems in which N is large, the conditional LUD option can
speed up a simulation by several hundred percent. However, it is an approximation, and
therefore the results should be compared with a reference simulation derived with the
option disabled.
The Order-N Option
The dynamics command can also be used to specify that the equations are to be
derived using method developed by Dr. Roger Wehage at the Tank Automotive Command
(TACOM) of the U.S. Army. This is an order-n method that does not involve a mass
matrix. The computation needed to obtain values for the derivatives of u is roughly
proportional to N. As noted in the description of the dynamics command in Section 8.1,
this option is subject to restrictions in how the bodies are connected. In particular, the
model cannot include algebraic constraints defined with the commands motion, no79

7.2. Computation Speed

AUTOSIM 2.0

movement, add-position-constraint, and add-speed-constraint.


Instead, such constraints must be modeled as stiff spring/damper elements, as is described
below.
The experience to date has shown that the Kane formulation is better than the order-n
formulation for most vehicle and robotics models. However, the order-n formulation may
provide the most efficient equations for certain large models. The only way to definitively
determine the best formulation for a given model is to derived the equations of motions
with and without the order-n option in the dynamics command.
Combining Masses
If the mass center of a body cannot move relative to the parent body, then a modeling
option is to lump the mass with that of the parent, thereby changing the mass, mass center,
and inertia tensor of the parent. This option applied when a model includes wheels or rotors
that (1) spin about a fixed axis, and (2) have their mass centers fixed on the axis. The
results of this modeling change are that (1) simpler equations are obtained, and (2) an
incorrect reaction force vector associated with the spinning part is obtained. The choice of
whether to combine masses is determined by the value of the Boolean global variable
*combine-masses*. Set it to T to improve the computational performance, or set it to
NIL if you are computing reaction forces and moments involving rotors and wheels.
Constraints
There are two basic modeling approaches for handling constraints. First, they can be
included as algebraic constraints using the commands motion, no-movement, addposition-constraint, and add-speed-constraint. The effects of the
algebraic constraints are

to reduce the number of DOF of the model, and therefore, to reduce the size of the
mass matrix,

to increase the complexity of the remaining equations, and

to increase the coupling between the equations.

The difficulty with this approach is in defining constraint conditions and selecting
variables to eliminate. For complex, highly constrained systems, the equations obtained are
complex and it can take a long time for AUTOSIM to derive them. However, because the
number of equations is reduced, the overall efficiency has proven to be better than
alternative methods with most benchmarks performed to date.
The other approach is to model the constraints as stiff spring/damper elements
connecting points that are not supposed to move relative to each other, using the command
add-line-force. The effects of these force elements are

to add high-frequency vibrational modes to the model that would not otherwise be
present,

to leave the number of state variables unaffected, and

7 10

7.2. Computation Speed

AUTOSIM 2.0

to leave the coupling between the equations unaffected.

The problem with this approach is that the system is given dynamic properties
associated with DOF that are not of interest. The stability of the simulation depends on the
values assigned to the spring and damper parameters. The eigenvalues added are probably
much higher than the others in the system, and therefore a stiff integrator should be used to
solve the equations.
Both methods can be used to give valid simulation results. The first, using geometric
constraints, is the more conventional method. The second approach, using stiff springs and
dampers, is suggested as an alternative that may yield faster code for some large models.
If geometric constraints are used, and the resulting constraint equations are
complicated, the computational speed can be improved by setting the global variable
*fast-computed-coordinates* to T. When the variable is NIL, then a full
Newton-Raphson iteration is used each time (see Sections 2.2 and 2.3). If it is T, then the
approximation described in Section 2.3 is used.
Computer Algebra Settings
The symbolic algebra functions built into AUTOSIM behave differently according to
settings of the global variables listed in Table 7.2.1. By changing these settings, you can
control the appearance of the equations and add checks to prevent numerical errors.
However, the default settings will generally result in the fastest code. One exception is that
for very simple models, more compact equations are sometimes obtained by setting the
global *no-zees* to a value of T.
Table 7.2.1. Computer Algebra Settings
Global
Def. Condition
*drop-small-terms*
T
Drop terms when added to larger terms?
*expand*
NIL Expand products of sums as they occur?
*expand-pcs*
NIL Expand intermediate symbols for a constant?
*fast-computedT
Use approximation to update computed coordinates in a
coordinates*
dynamical simulation?
*int-vars*
T
Introduce intermediate symbols to simplify equations?
*no-pcs*
NIL Disable the use of intermediate constants?
*no-zees*
NIL Disable the use of intermediate variables?
*safe-divide*
NIL Check all denominators for zero in generated code?
*safe-sqrt*
NIL Check sign of all square roots in generated code?

7 11

AUTOSIM 2.0

7.3. Programming New Commands


The AUTOSIM program was written in the Common Lisp language. A feature of Lisp,
inherited by AUTOSIM, is that new commands can be created and executed on the fly.
Nearly all capabilities of Lisp are included in AUTOSIM. (On some platforms, new
commands cannot be compiled. They are interpreted. Because nearly all of the work is
done by existing compiled AUTOSIM code, there is usually no discernible difference in
speed between compiled and interpreted functions.)
Lisp is an interesting language. It has been in use almost as long as Fortran, but has
primarily been associated with research in symbolic computation and artificial intelligence.
Early computer algebra programs such as MACSYMA and REDUCE were written in Lisp.
The language is very consistent in its syntax, with the result that the basics can be learned
in less than an hour. However, it is a large and complex language, with over 700 standard
functions, macros, and special forms. If you want to add new commands and functions to
AUTOSIM, and are new to Lisp, it might be somewhat daunting to try to figure which of
those 700 functions are the most useful for extending AUTOSIM. The purpose of this
section is to show, mainly by example, a style of programming new commands in Lisp.
Sources of Lisp Information
The following material is not intended as a first introduction to Lisp. If you have no
prior experience with Lisp, you will need an introductory text. Two that fit well with the
type of programming used in AUTOSIM are:
Common Lisp, by Wade L. Hennessey, McGraw-Hill Book Company, 1989
Lisp, Objects, and Symbolic Programming, Robert. R. Kessler, Scott, Foresman/Little,
Brown College Division of Scott, Foresman and Co., 1988
The definitive reference document for the language of Common Lisp is
Common LISP: The Language, 2nd Edition, Guy Steele, Digital Press, 1990.
The first edition of the reference by Steele, published in 1984, defines all of the features in
Common Lisp that are used in AUTOSIM. The second edition includes all of the original
features, plus enhancements and the Common Lisp Object System (CLOS).
Lisp Basics
Although this section is not intended to teach Lisp, a few fundamentals that are
particularly relevant to writing new AUTOSIM commands will be reviewed. The objective
is mainly to resolve the style of AUTOSIM commands with Lisp conventions.
Throughout this manual, AUTOSIM algorithms have been called commands and
functions. In fact, Lisp does not have anything called a command. It has forms, where a
form is a parenthesized list that is evaluated to produce a result. There are three kinds of list
forms that are evaluated: functions, macros, and special forms. As you go to write new
commands or functions, you will need to understand the distinctions between Lisp
functions and macros. (Special forms are standard macros built into the standard Common
7 12

7.3. Programming New Commands

AUTOSIM 2.0

Lisp language.) Before considering how macros and functions differ, we begin by
reviewing the Lisp evaluation process.
Lisp data are organized by objects. An object can be a number, a symbol, a list, a
matrix, and many other types. When you type in a complete object, followed by a carriage
return, the object is evaluated by Lisp and a result is printed. Numbers and strings evaluate
to themselves. Symbols evaluate to a value. If a symbol has not been assigned a value, an
error message is printed an attempt is made to evaluate it. For example, consider the
following interactive session:
(setsym a "sin(t)")
SIN(T)
a
SIN(T)
b
> Error: Unbound variable: B
> While executing: SYMBOL-VALUE
> Type Command-/ to continue, Command-. to abort.
> If continued: Retry getting the value of B.
See the Restarts menu item for further choices.
1 >

The Lisp symbol A was assigned a value that is the algebraic expression SIN(T).
Whenever A is evaluated, that assigned expression is returned. The Lisp symbol B had not
been assigned a value, and trying to use it results in an error.
Most forms are functions. Lisp functions follow simple rules for evaluation. The first
element of a list is the name of the function, and other elements are arguments. In
processing the function, Lisp first evaluates each argument. When all have been evaluated,
the values are passed to the function named by the first element of the list. Consider the
list function, which creates a list object:
(list 1 2 3)
(1 2 3)

In this example, the arguments to the function list were the numbers 1, 2, and 3. Each
number was evaluated, and the results were assembled into a list object. Now consider the
use of the symbol A that has been previously assigned a value:
(list 1 a 3)
(1 SIN(T) 3)

In this case, the evaluation of A resulted in the value SIN(T). If we attempt to make a list
with a symbol that has not been assigned a value, the result is as follows
(list 1 b 3)
> Error: Unbound variable: B
> While executing: SYMBOL-VALUE
> Type Command-/ to continue, Command-. to abort.
> If continued: Retry getting the value of B.
See the Restarts menu item for further choices.
1 >

Lisp includes a provision for passing a symbol directly to a function, rather than its value.
The symbol is preceded with a single quote character. Consider the following:
7 13

7.3. Programming New Commands

AUTOSIM 2.0

(list 1 a 'a 'b)


(1 SIN(T) A B)

The first two arguments were evaluated as before. The second two were not, with the result
that the list includes the symbols A and B.
If you define a new Lisp function where one of the arguments might be a symbol, you
must always use a quote character when using your function. For example consider a new
function mylist, defined and applied as follows
? (defun mylist (sym)
(list 'my sym))
MYLIST
? (mylist 1)
(MY 1)
? (mylist 'a)
(MY A)

When using AUTOSIM commands, you do not have to add the quote character. That is
because all commands that involve symbols involve both a Lisp function and a Lisp macro.
A macro is a template for text, often used to simplify the syntax by avoiding the need for
quoting arguments. When the first item of a list is the name of a macro, Lisp processes it
by replacing the text with the text of the macro, but with substitutions of arguments into the
template. The arguments are not evaluated automatically. After the replacement, the text is
processed as if it were typed in. Consider a macro version of the mylist algorithm:
? (defmacro mylist (sym)
`(list 'my ',sym))
MYLIST
? (mylist 'a)
(MY 'A)
? (mylist a)
(MY A)

The template is indicated by the back quote character (`). Within the list following the back
quote, any symbols preceded by a comma are place holders that are replaced with the macro
arguments. Note that in the first use of the macro, the quoted argument is put into the list.
In the second use, the symbol A is put into the list with no quote. If we wanted the macro
to evaluate the argument sym, were would not precede the comma with the quote character
in the macro definition. With the quote character, we suppress the evaluation of the
argument. Thus, if the argument is a symbol, the symbol is put into the list.
The general style for programming AUTOSIM commands is to create a Lisp function
that does the work, and, if some of the arguments might be symbols, to create a
corresponding Lisp macro that applies the quotes in the right places and calls the function.
This style will be illustrated by example below.
Example New Command
Consider a new command that will add a linear spring and damper element to a model
such as the pitch-lane vehicle ride model. For reference, Listing 7.3.1 shows the original

7 14

7.3. Programming New Commands

AUTOSIM 2.0

definitions of the suspension spring and damper forces. In comparing the add-lineforce commands for the front and rear suspensions, we see that the commands are very
similar. This leads us to consider a new command that will automatically add a spring and
damper force. Further, suppose we want to improve the description, to include labeling
information for output variables to be computed by the simulation program. Four output
variables will automatically be added: the spring force, damper force, spring deflection, and
damper rate.
To design a new command in AUTOSIM, it is helpful to test the proposed modeling
work using conventional AUTOSIM inputs. For this purpose, the inputs in Listing 7.3.2
were made for the front suspension. The difference between the two listings is that the
second specifies labeling information in detail for four variables to be written as output
variables by the simulation program. (The two add-line-force commands for the
front suspension are identical in the two listings.)

7 15

7.3. Programming New Commands

AUTOSIM 2.0

Listing 7.3.1. Original suspension force definitions in vehicle model.


;;; add linear suspensions between sprung and unsprung masses
(add-line-force fsf :name "front spring force" :direction [sz]
:magnitude "(wf - maf)*g/2 -kf*x"
:point1 af0 :point2 afj)
(add-line-force fdf :name "front damper force" :direction [sz]
:magnitude "-cf*v" :point1 af0 :point2 afj)
(add-line-force fsr :name "rear spring force" :direction [sz]
:magnitude "(wr - mar)*g/2 -kr*x"
:point1 ar0 :point2 arj)
(add-line-force fdr :name "rear damper force" :direction [sz]
:magnitude "-cr*v" :point1 ar0 :point2 arj)

Listing 7.3.2. Definition of front suspension in vehicle model.


(setsym x "dot([sz], pos(af0, afj))"
v "dxdt(@x)")
(add-out @x "f del" :long-name "front spring deflection"
:gen-name "Deflection" :units L :body "front spring")
(add-out @v "f vel" :long-name "front damper rate"
:gen-name "Rate" :units "L/T" :body "front damper")
(add-line-force fsf :name "front spring force" :direction [sz]
:magnitude "(wf - maf)*g/2 -kf*x" :point1 af0 :point2 afj)
(add-line-force fdf :name "front damper force" :direction [sz]
:magnitude "-cf*v" :point1 af0 :point2 afj)
(add-out "fm(fsf)" "f fs" :long-name "front spring force"
:gen-name "Force" :units F :body "front spring")
(add-out "fm(fdf)" "f fd" :long-name "front damper force"
:gen-name "Force" :units F :body "front damper")

We can study Listing 7.3.2 to determine which variables and labels are generic and
which must be specified for each spring and damper pair. In this case, suppose we decide
that the information specific to each spring and damper set includes the items listed in Table
7.3.1 as arguments for the new command.
Given values for the arguments listed in the table, we can define the following
conventions:

the spring rate is a parameter Ks, where s is the short symbol;

the damper rate is a parameter Cs;

the spring force is bias Ks x, where x is the distance between the two specified
points in the specified direction;

the symbols used for the spring and damper forces are sSF and sDF, respectively;

7 16

7.3. Programming New Commands

AUTOSIM 2.0

Table 7.3.1. Arguments for the new command.


Argument
Example
Description
point1
af0
first point used to define body acted on by forces and
spring deflection (same as point1 in add-line-force)
point2
afj
second point used to define body acted on by forces and
spring deflection (same as point2 in add-line-force)
direction
[sz]
the direction of the spring and damper lines of action
bias
(wf - maf)*g/2 bias in the spring force magnitude (e.g., static load)
s
F
short symbol for location of the spring and damper set
name
front
name associated of location of the spring and damper set

the names of the spring and damper elements are name spring and name
damper, where name is the specified name; and

the names of the spring and damper forces are name spring force and name
damper force.

Listing 7.3.3 shows Lisp code that defines a new command that serves the required
purpose. (To help describe the inputs, the lines in the listing have been numbered. The
actual AUTOSIM input listing does not include the numbers.)
The new command add-spring-damper is programmed as a macro, defined with
the Lisp defmacro macro. The macro has the six arguments defined in Table 7.3.2. All
the macro does is invoke a function add-spring-damper* with the arguments quoted.
The function add-spring-damper*, defined with the Lisp defun macro, has the
same six arguments and does the work.
Lisp Forms Used
Most of the functions used in the add-spring-damper* function are AUTOSIM
functions. However, three Lisp functions are used to create new symbols and strings from
the arguments. They are let*, intern, and format.
Let* is a Lisp special form:
let* ({variable | (variable value) }*) {declaration}* {form}*
It defines local variables and assigns values to them. All forms evaluated in the let* can
use those variables. In the example, lines 5 through 15 establish local variables d, x, v,
etc. For example, the value assigned to d is the result of applying the AUTOSIM function
arg-dir to the argument direction. As another example, the value assigned to x is the
result of applying the function dot to the direction of d and the position vector connecting
point1 and point2. The local variable are defined within the scope of the let* form, which
ends on line 32 with a closing parenthesis.

7 17

7.3. Programming New Commands

AUTOSIM 2.0

Listing 7.3.3. New command for adding spring and damper elements.
1.
2.

(defmacro add-spring-damper (shortsym longstr p1 p2 dir bias)


`(add-spring-damper* ',shortsym ',longstr ',p1 ',p2 ',dir ',bias))

3.
(defun add-spring-damper* (shortsym longstr point1 point2 direction
4.
bias)
5. (let* ((d (arg-dir direction))
6.
(x (dot (dir d) (pos* point1 point2)))
7.
(v (dxdt x))
8.
(sf (intern (format nil "~aSF" shortsym)))
9.
(df (intern (format nil "~aDF" shortsym)))
10.
(k (intern (format nil "K~a" shortsym)))
11.
(c (intern (format nil "C~a" shortsym)))
12.
(springf (format nil "~a spring force" longstr))
13.
(damperf (format nil "~a damper force" longstr))
14.
(sbody (format nil "~a spring" longstr))
15.
(dbody (format nil "~a damper" longstr))
16.
)
17.
18.
19.

(add-out* x (format nil "~a del" shortsym)


:long-name (format nil "~a spring deflection" longstr)
:gen-name "Deflection" :units "L" :body sbody)

20.
21.
22.

(add-out* v (format nil "~a vel" shortsym)


:long-name (format nil "~a damper rate" longstr)
:gen-name "Rate" :units "L/T" :body dbody)

23.
24.
25.

(add-line-force* sf :name springf


:magnitude (sub (arg-exp bias) (mul k x))
:direction d :point1 point1 :point2 point2)

26.
27.

(add-line-force* df :name damperf :magnitude (neg (mul c v))


:direction d :point1 point1 :point2 point2)

28.
29.

(add-out* (fm* sf) (format nil "~a fs" shortsym)


:long-name springf :gen-name "Force" :units "F" :body sbody)

30.
31.
32.

(add-out* (fm* df) (format nil "~a fd" shortsym)


:long-name damperf :gen-name "Force" :units "F" :body dbody)
))

Intern is a function with the form:


intern string
It searches for the symbol named by string. If not found, it creates and interns such a
symbol. For example, given the string FSF as an argument, it would return the symbol
FSF.
Format is a function with the form
format destination control-string {arg}*

7 18

7.3. Programming New Commands

AUTOSIM 2.0

If destination is NIL, format returns a string holding output defined by control-string and
args. Occurrences of ~a in control-string are replaced by the args. For example, the form
(format nil "K~a" shortsym)

would return the string KF if shortsym is assigned the symbol F.


Summary of Example Command
The design of the example command is based on the listing of AUTOSIM commands
shown first in Listing 7.3.2. Symbols and strings in the original AUTOSIM inputs are
replaced with local variables, defined with the let* Lisp form in the new function. Strings
are constructed using the Lisp format function, and symbols are created with the Lisp
intern function.
Using the new command, the front and rear suspensions in the pitch-plane vehicle
model could be defined with the two commands:
(add-spring-damper f "front" af0 afj [sz] "(wf - maf)*g/2")
(add-spring-damper r "rear" ar0 arj [sz] "(wr - mar)*g/2")

Restrictions of AUTOSIM Commands in Lisp Functions


AUTOSIM routines that are programmed as Lisp functions can be used in new Lisp
functions that you write. In general, AUTOSIM routines programmed as macros cannot be
used. The reason is that the macros take symbols at face value, whereas the functions use
the values assigned to the symbols. Usually, the AUTOSIM functions are invoked with
local variables whose values are determined by the arguments to your Lisp function. For
example, the macro
(add-point p :body b :coordinates (i j k))

defines a point P in body B with coordinates I, J, and K, whereas the function


(add-point* p :body b :coordinates (list i j k))

defines a point whose symbol is the value of the variable P, in the body whose symbol is
the value of variable B, with coordinates that are the values of the variables I, J, and K.
Table 7.3.2 lists the AUTOSIM functions that support similarly named macros.
The exclamation mark (!) is an abbreviation for a macro, and it cannot be used in the
body of a Lisp function. In general, f-strings are parsed using symbols or global values
assigned to symbols. They are never parsed using local values of symbols. Therefore,
expressions must be specified in Lisp notation rather than as f-strings. For example, rather
than writing "dot(dir(d), pos(point1, point2))" in line 6 of Listing 7.3.3, it was necessary
to write
(dot (dir d) (pos* point1 point2)).

7 19

7.3. Programming New Commands

AUTOSIM 2.0

Table 7.3.2. AUTOSIM functions that support macros.


add-body*
linear*
add-equation*
mass*
add-force*
massc*
add-gravity*
motion*
add-hidden-parameters*
no-movement*
add-line-force*
origin*
add-moment*
point-ave*
add-out*
print-body*
add-parameters*
print-kane*
add-point*
print-rf*
add-speed-constraint*
print-short-body*
add-state-variable*
reaction-forces*
add-strut*
rfvect*
add-subroutine*
rmvect*
add-to-erd-header*
rot*
add-variables*
rq*
basis*
ru*
default*
set-defaults*
dynamics*
set-derivs*
fm*
set-name*
help*
set-units*
inertia*
symexp*
inertiac*
tq*
install-differential*
tu*
install-table*
write-to-file*
install-units*
Table 8.2.1 lists all of the computer algebra functions, and shows the Lisp function names
in parentheses when they differ from the names used in f-strings. (For example, the
function add is used instead of the function +.)
F-strings can be used in Lisp functions if they involve specific symbols. For example,
in line 22 of Listing 7.3.3, we were able to specify the units with the expression "L/T"
because we wanted the symbols L and T to be used, not values assigned to local variables
L and T. (Just as well, as there were no local variables L or T.)
AUTOSIM Data Types
Lisp includes over 40 data types. These include numbers, symbols, lists, sequences,
matrices, hash tables, characters, strings, file streams, and more. It also permits
programmers to define new data types as subsets of the structure object. Section 8.4
lists all of the AUTOSIM data types, and also contains descriptions of the major ones. The
main reason that you would need to know details of a data type is to access information
associated with a data object. For example, by knowing that the point data type includes
a slot called body, you know that there is a function point-body that returns the body
data object associated with a point data object.
7 20

7.3. Programming New Commands

AUTOSIM 2.0

7 21

PART 3

REFERENCE

This part of the manual contains one (large) chapter of reference material:
Chapter 8 AUTOSIM Reference
This is the alphabetical reference for AUTOSIM. It provides the specifics of
AUTOSIM commands, functions, global variables, and data types.

CHAPTER 8

AUTOSIM REFERENCE
8.1 Commands 3
? 7
add-body 8
add-equation 12
add-gravity 14
add-line-force 15
add-moment 17
add-out 18
add-point 20
add-position-constraint 21
add-speed-constraint 22
add-standard-output 23
add-strut 24
add-subroutine 26
add-variables 30
dynamics 31
equilibrium 34
finish 34
in-lb 36
install-differential 37
install-table 38
install-units 40
8.2 Functions 79
! 81
angle 85
cross 90
default 91
dir 91
dot 91
dplane 92
dxdt 92
fm 96
ke 97
mag 98
nominal 99

linear 42
motion 45
no-movement 46
print-coordinates 49
print-default-directions 49
print-default-positions 50
print-parameters 53
print-speeds 56
reset 59
set-defaults 61
set-names 62
setsym 62
set-units 63
si 64
write-acsl 66
write-adsim 66
write-c 67
write-matlab 73
write-sim 77
write-to-file 78

partial 99
pos 101
relvel 102
rfvect 102
rmvect 103
rot 104
rq 104
ru 104
tq 107
tu 107
vel 108
z 108
81

AUTOSIM 2.0
8.3 Globals 109
*compiler* 114
*double-precision* 116
*fortran-implicit* 121
*include-path* 122
*int-vars* 122
*multibody-system-name* 126

*no-zees* 127
*pre-comp* 128
*stiff-integrator* 132
*target-language* 133
*time-eqs* 134

8.4 Data Types 139


body 141
expression 144
force 145

moment 147
point 148

This chapter is the reference for the AUTOSIM language. It describes four parts of
AUTOSIM in separate sections: commands, functions, global variables, and data types.
Commands and functions, described in Sections 8.1 and 8.2, are associated with
algorithms that do something. The distinction in classifying them is that a function is
used to obtain a value, whereas a command is used to perform analyses or display
information1. Commands, on the other hand, are used to do something other than provide
a single value.
Section 8.3 described global variables whose values can be set to control the
computer algebra, the modeling, and the code generation operations in AUTOSIM.
Section 8.4, describing AUTOSIM data types, is of interest only if you are a Lisp
programmer creating new AUTOSIM commands.

Each section consists of an alphabetic reference listing of all items. Major items are
listed in the table of contents above, and are indicated with larger headings in the chapter.

Technically, commands also return values because they are programmed in Lisp. Both functions and
commands are programmed as Lisp functions and macros, as described in Chapter 7.

82

AUTOSIM 2.0

8.1 Commands
As seen from the examples in the introductory guide, most of the analyses performed
with AUTOSIM are controlled by only a few commands such as add-body, addpoint, no-movement, reset, and finish. Major procedures such as these are
very important to understanding the basic use of AUTOSIM, and are noted with larger
captions. However, many other functions and commands exist which are useful for finetuning the simulation code, or for writing new commands that apply a predetermined
AUTOSIM analysis. This section contains definitions for over 100 commands,
summarized by categories in Tables 8.1.1 through 8.1.7.
The arguments associated with each command are defined under the heading Usage.
Each command or function may have a set of mandatory arguments that must be present,
and must appear in the correct order. Mandatory arguments are shown in italics
immediately after the symbol that identifies the function or command. There can also be
one or more optional arguments. Curly braces {} are used to indicate sets of arguments
that are optional. If the braces are followed by an asterisk, {}*, the set enclosed by the
braces can be repeated. For example, the command add-variables has two
mandatory arguments and an unlimited number of optional arguments.
Usage
add-variables where type {variable}*
In many cases, optional arguments are identified by keywords. They are shown in the
Courier font. Keywords are easily recognized because they always begin with a colon
character. For example, the command linear has optional arguments with keywords :u
and :y.
Usage
linear {:u u} {:y y}
Keyword arguments can appear in any order with respect to each other, after the
mandatory arguments. For example, the following two lines are equivalent:
(linear :u f :y ("rq(a)+rq(b)"))
(linear :y ("rq(a)+rq(b)") :u f)

83

8.1 Commands

AUTOSIM 2.0

Table 8.1.1. Commands for building description of multibody system.


add-body
Add rigid body, point mass, reference frame, or
coordinate system to system model.
add-gravity
Add effect of uniform gravity field.
add-line-force
Add force with specified direction.
add-moment
Add moment with specified direction and magnitude.
add-point
Add point fixed or moving in a body.
add-position-constraint Remove generalized coordinate to satisfy equation.
add-speed-constraint
Remove speed variable to satisfy equation.
add-strut
Add force connecting two points.
motion
Constrain system coordinate to follow a function.
no-movement
Constrain movement between points in one direction.
Table 8.1.2. Commands for analyzing.
dynamics
Perform dynamics analysis using options.
equilibrium
Perform equilibrium analysis.
finish
Finish up dynamics analysis.
finish-update
Finish up equations in subroutine UPDATE.
kinematics
Derive kinematical equations for multibody system.
linear
Derive and linearize equations of motion.
reaction-forces
Derive reaction force vectors.
reaction-moments
Derive reaction moment vectors.
reset
Clear description of multibody system and
initialize.
Table 8.1.3. Commands for building a Fortran simulation program.
add-accelerations-to-output
Add derivatives of speeds to output list.
add-coordinates-to-output Add generalized coordinates to output list.
add-equation
Add equation to simulation program.
add-forces-to-output
Add all active forces to output list.
add-hidden-parameters
Add parameters that are hidden from the end user.
add-moments-to-output
Add all active moments to output list.
add-out
Define an arbitrary output variable.
add-parameters
Add parameters to simulation program.
add-speeds-to-output
Add generalized speeds to output list.
add-standard-output
Add state variables, forces, to output list.
add-state-variable
Add variable whose derivative is integrated.
add-subroutine
Generate code to CALL an external subroutine.
add-to-erd-header
Add Fortran to write line in output file header.
add-variables
Add variables to a simulation program.

84

8.1 Commands

AUTOSIM 2.0

Table 8.1.4. Commands for printing.


?
Print on-line help. (Same as help.)
help
Print on-line help. (Same as ?.)
print-bodies
Print data for all body objects.
print-body
Print data for one body object.
1
print-constraints
Print replacement expressions for dependent
speeds.
1
print-coordinates
Print definitions of generalized coordinates.
print-default-directions1 Print numerical coordinates of all unit-vectors.
print-default-positions1 Print numerical coordinates of all points.
print-forces1
Print definitions of all active forces.
print-kane
Print Kane dynamic terms for a body.
print-kanes1
Print Kane dynamic terms for all bodies.
1
print-moments
Print definitions of all active moments.
print-outputs1
Print definitions of all output variables.
1
print-parameters
Print definitions of all parameters in equations.
print-points1
Print definitions of all points.
print-rf
Print data for one reaction force object.
print-rfs1
Print data for all reaction force objects.
1
print-speeds
Print definitions of generalized speeds.
print-symbols1
Print all symbols referenced in AUTOSIM input.
rtf
Print results of other commands in RTF format.
1 Can be used with the write-to-file command to route the printed information to a file.

Table 8.1.5. Commands for setting attributes of symbols and expressions.


in-lb
Set units system to in-lb, with degree, gs.
large
Declare symbol is large.
mks
Set units system to SI, with degree, gs.
set-defaults
Set default numerical values of symbols.
set-derivs
Set derivatives of symbols.
set-names
Set names of symbols or expressions.
setsym
Set values of globals and external symbols.
set-units
Set units for symbols.
si
Set units system to SI (angle=rad, acceleration=m/s).
small
Declare symbol is small.
Table 8.1.6. Commands for installing new AUTOSIM capabilities.
install-differential
Install definition of differential of function.
install-func
Install definition of function for use in F-strings.
install-indexed-parameters Install indexed parameters as 1-D arrays.
install-table
Install linear interpolation or spline function.
install-units
Install name and gain for units expression.

85

8.1 Commands

AUTOSIM 2.0

Table 8.1.7. Commands for writing.


write-acsl
Write simulation program in ACSL and Fortran.
write-adsim
Write simulation program in ADSIM.
write-difeqn
Write subroutine DIFEQN.
write-dolud
Write subroutine DOLUD.
write-echo
Write subroutine ECHO.
write-eqs
Write equations of motion in RTF form.
write-eqs-doc
Write background documentation for equations.
write-fct
Write subroutine FCT for dynamics program.
write-fct2
Write subroutine FCT for equilibrium program.
write-finish
Write subroutine FINISH.
write-fortran-doc
Write documentation for Fortran simulation program.
write-help
Write all on-line help for AUTOSIM commands.
write-help-globals Write all on-line help for AUTOSIM globals.
write-init
Write subroutine INIT.
write-initr
Write subroutine INITR.
write-input
Write subroutine INPUT.
write-inteqs
Write subroutine INTEQS.
write-main
Write MAIN Fortran program block.
write-matlab
Write code in MATLAB for generating matrices.
write-newtr1
Write subroutine NEWTR1.
write-opnout
Write subroutine OPNOUT.
write-output
Write subroutine OUTPUT.
write-pederv
Write subroutine PEDERV.
write-precmp
Write subroutine PRECMP.
write-quasi
Write subroutine QUASI.
write-setdef
Write subroutine SETDEF.
write-sim
Write complete Fortran program.
write-sim-minimal
Write Fortran program without library routines.
write-to-file
Apply a write command, sending the output to a file.
write-update
Write subroutine UPDATE.
Note: All of the above commands work with the write-to-file command.

lifo
load-autosim
status-report

Table 8.1.8. Miscellaneous commands.


Print equations in reverse order (last in, first out).
Load autosim files into existing Lisp system.
Print temporary message on screen.

86

8.1 Commands

AUTOSIM 2.0

?
Print a short reference description of a command, function, or variable.
Usage
? {symbol }
help {symbol }
Description
If it exists, on-line documentation is printed on the screen for symbol. If symbol is a
command, the summary obtained with the ? command is intended to be a brief summary
of the command and its arguments. The summary is intended as a quick reference that
you can bring onto the screen faster than you can thumb through this guide or the
reference manual.
If symbol does not correspond to a command, function, or global, then all known
symbols containing symbol are listed. (This is equivalent to the Lisp apropos function.)
Although all AUTOSIM routines are called commands and functions in this
documentation, the on-line help identifies them according to how they are programmed in
Lisp, which is either as macros or functions.
Examples
? (? commands)
Main AUTOSIM commands.
Commands for building description of multibody system:
ADD-BODY ADD-GRAVITY ADD-LINE-FORCE ADD-MOMENT ADD-POINT
ADD-POSITION-CONSTRAINT ADD-SPEED-CONSTRAINT ADD-STRUT MOTION
NO-MOVEMENT
Commands for building Fortran simulation program:
ADD-OUT ADD-STANDARD-OUTPUT ADD-STATE-VARIABLE ADD-SUBROUTINE
ADD-TABLE ADD-VARIABLES
Commands to analyze or print:
? DYNAMICS EQUILIBRIUM FINISH HELP LINEAR PRINT-BODIES
PRINT-COORDINATES PRINT-FORCES PRINT-MOMENTS PRINT-RFS PRINT-SPEEDS
RESET WRITE-TO-FILE
Commands to set attributes of symbols and expressions:
IN-LB MKS SET-DEFAULTS SET-NAMES SETSYM SET-UNITS SI SMALL
Commands to install system information:
INSTALL-UNITS INSTALL-DIFFERENTIAL
NIL
? (? write-si)
WRITE-SI is neither a bound symbol nor the name of a function or macro.
APROPOS gives these matches:
*WRITE-SIM-MENUITEM*, Value: #<MENU-ITEM "Write Fortran Code">

87

8.1 Commands

AUTOSIM 2.0

WRITE-SIM-MINIMAL, Def: FUNCTION


WRITE-SIM, Def: FUNCTION
WRITE-SI
? (? write-sim)
FUNCTION: WRITE-SIM
===================
writes complete Fortran simulation program
WRITE-SIM ({STREAM {MINIMAL}})
This is typically an argument to the WRITE-TO-FILE macro. It
writes a Fortran MAIN program and all custom subroutines needed to
simulate a multibody system. Additional routines from the AUTOSIM
library are also written unless MINIMAL is given a non-NIL value

add-accelerations-to-output
Add accelerations to the list of output variables.
Usage
add-accelerations-to-output
Description
This command adds the derivatives of the independent speeds to the list of output
variables generated by a Fortran program. Code is generated by AUTOSIM to write
labels for these variables, and to write the variables themselves into the output file
produced by the simulation code. The speeds and their definitions can be viewed with the
command print-speeds.
Add-accelerations-to-output is used to very quickly define a set of output
variables. Use the add-standard-output command to add all of the usual output
variables at once. Use the add-out command to obtain more control over how the
output variables are defined and labeled.
See Also
add-out, add-standard-output, print-speeds, Section 5.6

add-body
Incorporate new body into multibody system.
Usage
add-body symbol

{:parent parent} {:mass mass} {:name string} {:inertiamatrix inertia-matrix} {:inertia-matrix-coordinatesystem matrix-coordinate-system}{:coordinate-system
coordinate-system} {:joint-coordinates joint} {:cmcoordinates c m} {:translate translate} {:bodyrotation-axes axes} {:parent-rotation-axis parentrotation-axis} {:reference-axis reference-axis} {:small88

8.1 Commands

AUTOSIM 2.0
a n g l e s small-angles} {:small-translations smalltranslations} {:no-rotation no-rotation}

Description
This command defines a rigid body, its coordinate system, its mass properties, and the
kinematics of a joint connecting it to a reference that is either (1) another body that has
already been added to the multibody system, or (2) the inertial reference, N. The
reference is called the parent of the new body. The add-body command has one
required argument, symbol, used to identify the new body.
Symbol is used by AUTOSIM to generate symbols for parameters and points
associated with the new body. For example, a point is created for the origin of the new
body, and that point is identified by a symbol that is created automatically by appending
the digit zero to symbol. If the body is F, then symbol created for the origin point is F0.
As a notational convenience, the new body will be called B in the following discussion
and tables. Symbols created by AUTOSIM are shown in italics, and the letter B would
be replaced by the body symbol. For example, the origin point is written B0.
Add-body automatically introduces the four points defined in Table 8.1.8.

Name
origin
joint point
center of mass
composite center
of mass

Table 8.1.8. Points defined by add-body.


Symbol
Definition
B0
origin of coordinate system of body B, fixed in B
BJ
point fixed in parent of B that coincides with BJ in
nominal configuration
BCM
center of mass of rigid body B
BCMC
point fixed in B for composite body introduced
(automatically) by AUTOSIM

The keyword arguments for add-body are defined in Table 8.1.9. The add-body
command is essential for using AUTOSIM. By using different combinations of
keywords, you can define many kinds of body movements. Also, you can introduce
massless bodies, point masses, and alternate coordinate systems for existing bodies.
The position of B relative to its parent is specified by arguments to add-body. In
most cases, B can move relative to the parent. The position in which there is no
movement is called the nominal configuration. Figure 8.1.1 shows an example two-body
system in the nominal configuration (a) and also two different positions, (b) and (c).
Body B can rotate relative to its parent A, which can rotate and translate relative to its
parent, the inertial reference, N. This example system could be described by two addbody commands as follows:
(add-body a :body-rotation-axes z :translate ([nx] [ny]))
(add-body b :parent a :body-rotation-axes 3 :parent-rotation-axis [nz]
:reference-axis "[ax] - .1*[ay]"
:joint-coordinates (L1 L2 0)
:cm-coordinates (0 L3 0))

89

8.1 Commands

AUTOSIM 2.0

Table 8.1.9. Keyword arguments for add-body.


Keyword
Default
Definition
:parent
N
body used to locate B and define its
movements
:name
B
string of text used in documentation
:mass
MB
scalar expression for mass of B
:inertia3x3 matrix:
moments and products of inertia for B about
matrix
((IB11 IB12 IB13) its mass center; can specify: 0, 3-element list
(IB12 IB22 IB23) of moments (products=0), external variable,
(IB13 IB23 IB33)) or Lisp-style expression
:inertiaB
body whose coordinate system is used to
matrixdefine directions of moments and products of
coordinateinertia
system
:coordinateparent (for BJ)
body whose coordinate system is used for
system
B (for BCM)
coordinates of points and direction vectors
:jointorigin of parent point BJ (or coordinates of point BJ ) that
coordinates
coincides with B0 in nominal configuration
:cmB0
mass center of B: coordinates or point that
coordinates
coincides with BCM in nominal configuration
:translate
NIL
list1 of 0 to 3 vector expressions or axis
indices2 defining directions of translational
movements of B0 relative to BJ
:bodyNIL
list1 of 0 to 3 axis indices2 indicating
rotation-axes
sequence of rotations of B relative to parent
:parentparent axis
vector fixed in parent (vectors not fixed in
rotation-axis corresponding to parent are transformed) or axis index2
defining direction of first axis of rotation of B
first body axis
:reference1 + first body axis vector fixed in parent (vectors not fixed in
axis
(in parent), in
parent are transformed) or axis index2
defining nominal configuration of B
modulo 3
:small-angles
list of NIL
list1 of same length as axes indicating
symbols
whether each rotation is small (T) or normal
(NIL)
:smalllist of NIL
list1 of same length as translate indicating
translations
symbols
whether each translation is small (T) or
normal (NIL)
:no-rotation
NIL
Boolean: T if B cannot rotate relative to
parent
1
Notes: If list has just one item, it need not be enclosed in parentheses.
2 Valid axis indices are X, Y, Z, and 1, 2, and 3.
The orientation of B relative to parent in the nominal configuration is determined by
three arguments: axes, parent-rotation-axis, and reference-axis. If both axes and parent-

8 10

8.1 Commands

AUTOSIM 2.0

A0

ax

ax A
B0
ny

ny
BCM
nx

nx

PA

bx

bx
(a)

(b)

ax

AJ

ny
PN
nx

(c)
Figure 8.1.1. Movements from the nominal configuration.
rotation-axis are not specified, then B does not rotate relative to parent, and the axes of
its coordinate system are in the same directions as the axes in parent. If axes and/or
parent-rotation-axis is specified, then a set of three unit-vectors is introduced for B. The
unit-vector with the first index in axes is positioned in the direction parent-rotation-axis.
For the example shown in the figure, all rotations occur about axes parallel to the unitvector nz. In the above description of body A, the specification of axes as with single
index Z sets parent-rotation-axis to the default: the corresponding unit-vector in N, nz.
The reference axis is defined by adding 1 to the rotation axis defined first item in axes
in modulo 3. (The pairs of rotation and reference axis indices are 1-2, 2-3, and 3-1; or ,
using XYZ symbols, X-Y, Y-Z, and Z-X) Thus, for the rotation axis of 3 for bodies A
and B in Figure 8.1.1, the reference axes are a x and bx . Because the :referenceaxis keyword was not used for body A, a x is oriented in the default direction of n x
when the system is in the nominal configuration. When body B is defined, the vector
specified is (a x .1 a y ). Thus, in the nominal configuration, the reference axis bx is
oriented as shown in Figure 8.1.1.a.
Point locations can be specified two ways in the add-body command. Coordinates
can be specified with 3-element lists of coordinates, as shown for this example.
Alternatively, the symbol for an existing point can be specified. If an existing point is
8 11

8.1 Commands

AUTOSIM 2.0

named, the new point in created to coincide with the named point when the system is in
the nominal configuration. For example, the center of mass of body B in the figure was
specified by the coordinates (0 L3 0), which, by default, are in the coordinate system of
B. If a point PA existed in A, or a point PN in N (see the figure), then either of those
symbols could have been provided to identify the location of point BCM. Point BCM
would coincide with the existing point only in the nominal configuration (see Figure
8.1.1.a).
To define an alternative coordinate system for an existing body, define the nominal
configuration using :parent-rotation-axis, :reference-axis, and :bodyrotation-axes. These three arguments can define the coordinate system for the new
body to have any conceivable relation to that of the parent. To prevent the new body from
being given rotational coordinates, set no-rotation to T. Be sure to set the mass and
inertia matrix to zero if you dont want mass associated with the new coordinate system.
To check the degrees of freedom associated with the new body, use the commands
print-body, print-bodies, print-coordinates, and print-speeds.
See Also
print-body, print-bodies, print-coordinates, print-speeds, Section
5.4

add-coordinates-to-output
Add coordinates to the list of output variables.
Usage
add-coordinates-to-output
Description
This command adds all of the multibody coordinates to the list of output variables
generated by a Fortran program. Code is generated by AUTOSIM to write labels for
these variables, and to write the variables themselves into the output file produced by the
simulation code. The coordinates and their definitions can be viewed with the command
print-coordinates.
Add-coordinates-to-output is used to very quickly define a set of output
variables. Use the add-standard-output command to add all of the usual output
variables at once. Use the add-out command to obtain more control over how the
output variables are defined and labeled.
See Also
add-out, add-standard-output, print-coordinates, Section 5.6

add-equation
Add an equation to the program to be generated by AUTOSIM.

8 12

8.1 Commands

AUTOSIM 2.0

Usage
add-equation where symbol exp {:comment string}
Description
This command adds an equation of the form symbol = exp to the simulation program in
the section identified by the symbol where. This command is similar to the addsubroutine command. The valid values for where are shown in Table 8.1.10.
The add-equation command should be used sparingly, if at all. It is only to
support calculations that are not derived by AUTOSIM, but which are needed to support
auxiliary state variables or external subroutines.
The main reasons for adding equations this way are:
1.

When the simulation is written for ACSL, force equations can be placed directly
in the derivative or discrete blocks where they are easily seen and
modified.

2.

Variables needed by external subroutines (specified with the add-subroutine


command) can be assigned initial values.

3.

Differential equations for auxiliary state variables (defined with the command
add-state-variable) can be inserted directly into the equations of motion.
(The alternative is to provide the name of a subroutine that computes derivatives
of the auxiliary state variables.)

Table 8.1.10. Places where equations can be added.


Keyword
Language
Location
Calculate
adsim
ADSIM
DYNAMIC
forces and moments, extra derivatives
derivative
ACSL
DERIVATIVE forces and moments, extra derivatives
derivative
Fortran
DIFEQN
forces and moments, extra derivatives
1
difeqn
Fortran
DIFEQN
forces and moments, extra derivatives
discrete
ACSL
DISCRETE
variables needed at discrete intervals
echo
Fortran
ECHO
data to be printed into an echo file
finish
Fortran
FINISH
variables needed at end of run
input
Fortran
INPUT
data associated with input keyword
init
ADSIM
INITIAL
initial values of extra variables
init
Fortran1
INIT
initial values of extra variables
init
MATLAB
initial values of extra variables
kinematics
Fortran
INITNR,
variables appearing in kinematical
DIFEQN
constraints
output
Fortran
OUTPUT
output variables
1
setdef
Fortran
SETDEF
default values of program variables
start
ACSL
before DERIV initial values of ACSL variables
update
Fortran1
UPDATE
variables needed once per time step
1 also used for the ACSL language

8 13

8.1 Commands

AUTOSIM 2.0

Example
The following inputs define a new state variable V whose derivative is VP, which is
defined (for this simple example) as SIN(T).
(add-state-variable v vp a)
(add-equation kinematics vp "sin(t)"
:comment "equation for auxiliary variable")

See Also
add-state-variable, add-subroutine, Sections 5.6, 6.4

add-forces-to-output
Add force magnitudes to the list of output variables.
Usage
add-forces-to-output
Description
This command adds the force magnitudes to the list of output variables generated by a
Fortran program. Code is generated by AUTOSIM to write labels for these variables, and
to write the variables themselves into the output file produced by the simulation code.
The forces and their definitions can be viewed with the command print-forces.
Add-forces-to-output is used to very quickly define a set of output variables.
Use the add-standard-output command to add all of the usual output variables at
once. Use the add-out command to obtain more control over how the output variables
are defined and labeled.
See Also
add-out, add-standard-output, print-forces, Section 5.6

add-gravity
Set up uniform gravitational field for multibody system.
Usage
add-gravity {:direction direction} {:gees symbol}
Description
This command defines a uniform gravitational field defined by the vector symbol
direction. Direction is the direction in which the field acts. If not specified with the
keyword :direction, it is set to nz . Symbol is the symbol used for a gravitational
constant. If not specified with the keyword :gees, it is set to the global variable,
*gees*. When a simulation code is written, the printed value of *gees* (nominally G)
is included as a parameter whose numerical value is determined by the units system. The
reset command removes the gravity field.

8 14

8.1 Commands

AUTOSIM 2.0

See Also
*gees*, reset, Section 5.5

add-hidden-parameters
Declare parameters that are hidden from the end user of a Fortran simulation program.
Usage
add-hidden-parameters { parameter}*
Description
Use this command to introduce auxiliary variables needed for external subroutines that
you want to be called from within subroutine INPUT. It is nearly identical to the
command add-parameters. Like add-parameters, it causes each parameter
symbol to be declared as floating-point Fortran variable in the INPARS COMMON
block. Further, it causes Fortran code to be generated to read each variable in the Fortran
subroutine INPUT. However, it does not cause code to be generated in subroutine ECHO.
Thus, the value of the variable is hidden from the user of the Fortran simulation program.
See Also
add-hidden-parameters , print-parameters, Section 6.3

add-line-force
Add force whose line of action has a known direction.
Usage
add-line-force symbol
{: n a m e s t r i n g } {:direction direction}
{:magnitude magnitude} {:point1 point1} {:point2
point2} {:x x} {:x0 x0} {:v v} {:no-forcem no-forcem}
Description
This command defines a force in the system that passes through a given point and whose
line of action has a specified direction. The required argument, symbol, is a symbol used
later to identify the force. The optional arguments are defined in Table 8.1.11. A force
with magnitude +magnitude is applied to the body containing point1, and a force with
magnitude magnitude is applied to the body containing point2. The force has the
specified direction, and the line of action of the force passes through point1. (However,
the line of action for the force does not necessarily pass through point2.) At least one of
the optional arguments point1 or point2 must be included in order for the force to affect
the system. Typically, many of the optional arguments are used.
All of the forces in the system can be printed with the command print-forces.
The magnitude of a specific force is obtained through the fm function.

8 15

8.1 Commands

AUTOSIM 2.0

Table 8.1.11. Keyword arguments for add-line-force.


Keyword
Default
Definition
:name
symbol
string of text used in documentation
:direction
nz
vector algebraic expression that defines the
direction in which the force acts on the body
associated with point1. (A force with equal
magnitude and opposite direction acts on the
body associated with point2.)
:magnitude
constant symbol scalar expression for the force magnitude
:point1
origin of N
point on line of action of force; force acts
with positive magnitude on the body in which
point1 is fixed
:point2
origin of N
force acts with negative magnitude on the
body in which point2 is fixed
:x
X
dummy variable; if used in magnitude,
AUTOSIM replaces it with the distance
between point1 and a plane containing point2
that is perpendicular to the specified direction
:x0
X0
dummy variable; if used in magnitude,
AUTOSIM replaces it with the nominal value
of the expression used to replace X
:v
V
dummy variable; if used in magnitude,
AUTOSIM replaces it with the speed point1
moves relative to a plane containing point2
that is perpendicular to the specified direction
:no-forcem
NIL
if T, AUTOSIM does not introduce an
intermediate variable for the force magnitude
Examples
To add a spring or damper, the dummy variable X can be used to represent the spring
deflection and the dummy variable V can be used to represent the deflection rate. The
sign convention for a spring acting between bodies associated with points p1 and p2 is
such that when p1 is on a body that is a descendent of the body associated with point p2,
then a spring equation has the form "-K*(x-x0)" and a damper equation has the form
"-D*v". Consider a linear damper in the pitch plane vehicle example.
(add-line-force fdf :name "front damper force"
:direction [sz] :magnitude "-cf*v"
:point1 af0 :point2 afj)

In the above example, point AF0 is a point on the front axle mass, and point AFJ is the
point of attachment on the vehicle body. Because the vehicle body is the parent of the
axle body, point AF0 is on a body that is a descendent of the body in which point AFJ is
attached.

8 16

8.1 Commands

AUTOSIM 2.0

See Also
add-strut, fm, print-forces, Section 5.5

add-moment
Add moment into multibody system model.
Usage
add-moment symbol {: n a m e string} {:direction direction} {:magnitude
magnitude} {:body1 body1 } {:body2 body2} {:no-forcem
no-forcem}
Description
This command introduces the moment of a pure couple between two bodies. (Moments
due to forces acting between bodies are derived automatically by AUTOSIM.) The
required argument, symbol, is a symbol used to identify the moment. The optional
arguments are defined below. Note that at least one of the optional arguments body1 or
body2 must be included in order for the moment to actually affect the system. The
optional arguments are defined in Table 8.1.12.
Table 8.1.12. Keyword arguments for add-moment.
Keyword
Default
Definition
:name
symbol
String of text used in documentation.
:direction
nz
vector algebraic expression that defines the
direction of the moment acting on body1.
:magnitude
constant symbol scalar expression for the moment magnitude.
:body1
N
Moment acts with positive magnitude on body1.
:body2
N
Moment acts with negative magnitude on body1.
:no-forcem
NIL
if T, AUTOSIM does not introduce an
intermediate variable for the force magnitude.

Example
The sign convention for a spring acting between bodies b1 and b2 is such that when b2 is
the parent body of b1, then the spring equation has the form "-K*rq(b1)". For example,
consider the spacecraft example from Appendix C of the Introductory Guide to
AUTOSIM. Body E is connected to body B by a hinge with two rotational DOF, about the
X and Z axes, with body B being the parent of body E. The following inputs add torsional
springs and dampers about the X and Z axes.
...
(add-body e :name "Boom" :parent b :Joint-coordinates (0 -L7 0)
:body-rotation-axes (z x) :small-angles (t t)
:cm-coordinates (0 -L8 0) :inertia-matrix (iex iey iex))
...
(add-moment btz :name "boom-torque Z" :body1 e :body2 b

8 17

8.1 Commands

AUTOSIM 2.0

:direction [bz] :magnitude "-ke*rq(e) - ce*ru(e)")


(add-moment btx :name "boom-torque X" :body1 e :body2 b
:direction [ex] :magnitude "-ke*rq(e,2) - ce*ru(e,2)")

See Also
fm, print-moments, Section 5.5

add-moments-to-output
Add moment magnitudes to the list of output variables.
Usage
add-moments-to-output
Description
This command adds the moment magnitudes to the list of output variables generated by a
Fortran program. Code is generated by AUTOSIM to write labels for these variables, and
to write the variables themselves into the output file produced by the simulation code.
The moments and their definitions can be viewed with the command print-moments.
Add-moments-to-output is used to very quickly define a set of output variables.
Use the add-standard-output command to add all of the usual output variables at
once. Use the add-out command to obtain more control over how the output variables
are defined and labeled.
See Also
add-out, add-standard-output, print-moments, Section 5.6

add-out
Define output variable for Fortran simulation code.
Usage
add-out expression short-name {:long-name long-name}{:gen-name genname}{:body body }{:units units }
Description
This command defines a variable that will be computed in the simulation code and
written into an output file. It only has an effect when a complete Fortran program is
generated. (Output variables are not copied into source code written for other languages.)
The required argument expression is a scalar algebraic expression. The second required
argument, short-name, is a string with up to 8-characters that names the variable. The
optional keyword arguments provide additional labeling information, as defined in Table
8.1.13. The program generated by AUTOSIM will put this information into the header of
the output file to facilitate automated post-processing.

8 18

8.1 Commands

AUTOSIM 2.0

Table 8.1.13. Keyword arguments for add-out.


Keyword
Default
Definition
:long-name
short-name
string of text with full name of expression
:gen-name
(based on units) string of text naming the generic type of the
variable expression
:body
N
string or symbol associated with expression
:units
(derived by
expression involving the symbols A, C, F, L, and
AUTOSIM)
T that defines the units of expression.
Note: strings should be no longer than 32 characters.
Use the add-standard-output command to add all of the usual output variables
at once.
Example
The following input defines an output variable for the pitch-plane vehicle model,
computed with the ROAD function defined for that example.
(add-out "road(dot([nx],pos(af0)))" "Z road" :body "road" :units L)

See Also
add-standard-outputs, print-outputs, Section 5.6

add-parameters
Declare parameters needed by external subroutines.
Usage
add-parameters {parameter}*
Description
Add-parameters is typically used to cause AUTOSIM to generate Fortran code to
read and echo parameters used for external subroutines in the INPUT or ECHO areas of
the simulation code. Another reason for using add-parameters is that AUTOSIM
generates code to read and echo all parameter symbols added this way. However,
AUTOSIM has no information about what each parameter signifies. Therefore, it is
usually a good idea to assign names to each parameter with set-names, the units with
set-units, and the default values with set-defaults.
If the parameters are intended to be elements of an array, then use the command
install-indexed-parameters instead.
All parameters are floating-point variables (REAL or REAL*8, depending on the
setting of *double-precision*) in the Fortran program.
See Also
*double-precision*, install-indexed-parameters, p r i n t parameters, set-defaults, set-names, set-units, Section 6.3

8 19

8.1 Commands

AUTOSIM 2.0

add-point
Define a point fixed in a body.
Usage
add-point symbol {:name string} {:body body} {:coordinates coordinates}
{:coordinate-system coordinate-system}
{:moving
moving}
Definition
This command defines a point in a body for use in describing forces, output variables,
etc. The required argument symbol is used to identify the point later. If the point already
exists, symbol is added to the list of symbols associated with the existing point.1 The
optional arguments are the following:
:name string is a string of text that describes the point. If the point already exists,
the string is added to the list of existing names for the point. If string is not
provided, symbol is used as the name.
:body body is the body/coordinate system in which the point is fixed. The default
is N.
:coordinates coordinates defines the coordinates of the point. coordinates can
have two possible forms: (1) a 3-element array, or (2), another point that already
exists. If coordinates is an array, the elements of the array are coordinates of the
new point as described in coordinate-system. The coordinates are converted from
coordinate-system to body such that a point defined by coordinates coincides
with the new point when the system is in the nominal configuration. If
coordinates is an existing point, the new point is created with coordinates such
that it coincides with the existing point when the system is in the nominal
configuration.
The default for coordinates is (0 0 0). Since a point already exists at the
origin of every body, a d d-point is really not very useful unless the
coordinates argument is provided.
:coordinate-system coordinate-system is a body (coordinate system) to use
for specifying the coordinates of the point. If coordinate-system is not the same
as body, the coordinates are converted by assuming the system is in its nominal
state (all generalized coordinates are zero). The default is body.
:moving moving is a Boolean whose default value is NIL. If moving is given a
non-NIL value, then the coordinates for the point can be variables, to define a
point that moves in body. If moving is NIL, then the nominal values of

AUTOSIM only permits one point per body with a given set of coordinates. If another point is added
to a body with the same coordinates as an existing point, the new symbolic name is attached to the old
point. AUTOSIM will recognize the new symbol, as well as all previous symbols, associated with the
point. The original symbol for the point is alway printed by AUTOSIM.

8 20

8.1 Commands

AUTOSIM 2.0

coordinates are used to define a point is fixed in body, with a position that
coincides with coordinates in the nominal configuration.
The definitions of all points in the multibody system can be printed by using the
print-points command. The command print-default-positions prints the
coordinates of all points, substituting default numerical values for all parameter symbols.
Examples
Consider the four-bar linkage example. Point P3 is defined as a reference, and then
copied to bodies A and C:
(add-point p3 :coordinates (xp3 yp3 0)
:name "pin between A and C")
(Point P3: Body N: (XP3 YP3 0): pin between A and C)
;;; add moving reference points
(add-point ap3 :body a :coordinates p3)
(Point AP3: Body A: (-PC(5) PC(6) 0): AP3)
(add-point cp3 :body c :coordinates p3)
(Point CP3: Body C: (-PC(7) PC(8) 0): CP3)

See Also
point, print-default-positions, print-points, Section 5.2

add-position-constraint
Apply a single constraint equation involving position.
Usage
add-position-constraint expression {:q coordinate }
Description
Add-position-constraint is used to apply a general position constraint when the
simpler commands motion and no-movement cannot be used. The effect is to remove
a generalized coordinate as an independent variable. After the coordinates are
renumbered, the old independent coordinate is redefined by AUTOSIM as a computed
coordinate. The required argument expression is an algebraic expression that is
identically zero when the constraint is satisfied. The optional argument coordinate is a
generalized coordinate that is eliminated by the constraint. If coordinate is not provided,
then add-position-constraint uses some programmed criteria to select one
automatically. If add-position-constraint cannot find a coordinate to eliminate,
an error message is printed to that effect. (If this happens, you must specify coordinate.)
Add-position-constraint prints the name of coordinate to the screen, and
returns with a replacement expression. If expression does not include coordinate, an error
message is printed.
When add-position-constraint is used to eliminate a coordinate, you must
use add-speed-constraint to apply a corresponding constraint in speed. If you do
not do this correctly, AUTOSIM will derive erroneous equations!
8 21

8.1 Commands

AUTOSIM 2.0

The commands motion and no-movement can be used to apply many constraints
in position. They are recommended over the add-position-constraint because
(1) they are easier to use, and (2) there is no danger of AUTOSIM deriving inconsistent
equations.
See Also
add-speed-constraint, motion, no-movement, Section 5.4

add-speed-constraint
Apply a single constraint equation involving speed.
Usage
add-speed-constraint expression {:u speed } {:category category}
Description
Add-speed-constraint is used to apply a speed constraint, to reduce the number of
DOF of the system by one by eliminating a generalized speed. The required argument
expression is an algebraic expression that is identically zero when the constraint is
satisfied. The optional argument speed is a generalized speed that is eliminated by the
constraint. If speed is not provided, then add-speed-constraint uses some
programmed criteria to select one automatically. In some cases, add-speedconstraint cannot find a speed to eliminate. An error message is printed to that effect.
(If this happens, then you must specify a speed using the option :u keyword.)
The optional argument category is either the symbol dependent (the default) or
removed. It is occasionally used to eliminate a moving body from the dynamics of the
system by specifying removed. Use this option if you included a body for the purpose of
defining a moving reference frame, whose rotation and rotational speed are prescribed
functions of time, and which has no associated mass or inertia. If category is the symbol
removed, then speed is completely eliminated from the equations of motion.
Add-speed-constraint prints the name of speed to the screen, and returns with
a replacement expression. If expression does not include speed , an error message is
printed.
The speed constraints that have been added to the system can be viewed at any time
using the print-constraints command.
Example
Define the speed of the vehicle in Appendix B of the Introductory Guide to AUTOSIM as
a constant:
? (add-speed-constraint "tu(u) - v")
Replace Abs. X trans. speed of U0
V

See Also
print-constraints, Section 5.4

8 22

8.1 Commands

AUTOSIM 2.0

add-speeds-to-output
Add speeds to the list of output variables.
Usage
add-speeds-to-output
Description
This command adds the independent speeds to the list of output variables generated by a
Fortran program. Code is generated by AUTOSIM to write labels for these variables, and
to write the variables themselves into the output file produced by the simulation code.
The speeds and their definitions can be viewed with the command print-speeds.
Speed variables that were removed by constraint equations are not added to the list of
outputs with this command.
Add-speeds-to-output is used to very quickly define a set of output variables.
Use the add-standard-output command to add all of the usual output variables at
once. Use the add-out command to obtain more control over how the output variables
are defined and labeled.
See Also
add-out, add-standard-output, print-speeds, Section 5.6

add-standard-output
Add state variables, forces, etc. to list of output variables.
Usage
add-standard-output
Description
This command adds all state variables, forces, moments, and accelerations (derivatives of
generalized speeds) to the list of output variables generated by a Fortran program. Use
the add-out command to obtain more control over how the output variables are defined
and labeled.
See Also
add-accelerations-to-output, add-coordinates-to-output, addforces-to-output, add-moments-to-output, add-speeds-to-output,
Section 5.6

add-state-variable
Introduce extra state variable.
Usage
add-state-variable symbol deriv units {:type type}

8 23

8.1 Commands

AUTOSIM 2.0

Description
The simulation code generated by AUTOSIM integrates derivatives of state variables. All
of the state variables pertaining to the multibody system are introduced automatically and
are handled completely by AUTOSIM. The add-state-variable command is used
to add a state variable that would not otherwise be included. Generally, this is done when
the multibody system includes a sub-system with its own dynamics. For example, a
controller might have dynamics involving voltages, or a hydraulic system might have
dynamics involving fluid flow and pressure.
The command has three required arguments. Symbol is a symbol to use for the new
coordinate. Deriv is a symbol to use for its derivative. Units is an expression for the units
of symbol.
Variables introduced with add-state-variable are included in the simulation
code in either (1) the array used for the generalized coordinates, or (2) the array used for
the generalized speeds. The choice of whether to call a new variable a coordinate or
speed is a matter of style and has no effect on the performance of the simulation code.
The optional argument type determines whether the new variable is considered to be a
coordinate or speed. If type is set to the symbol speed, the new variable is a speed. If set
to any other symbol, the new variable is a coordinate. The default is the symbol
coordinate.
Because AUTOSIM has no information about what the new variable represents, you
must provide information for computing a value for deriv. To do this, you need to add an
equation with the command add-equation, or, an external subroutine, as defined with
add-subroutine. (The where argument for either add-equation or addsubroutine should be either the symbol kinematics or difeqn.)
Example
The following inputs define a new state variable V whose derivative is VP, which is
defined as SIN(T).
(add-state-variable v vp a)
(add-equation kinematics vp "sin(t)"
:comment "equation for auxiliary variable")

See Also
add-equation, add-subroutine, Section 6.5

add-strut
Add force whose line of action passes between two known points.
Usage
add-strut symbol {:name string} {:magnitude magnitude} {:point1 point1}
{:point2 point2} {:x x} {:x0 x0} {:v v} {:no-forcem noforcem}

8 24

8.1 Commands

AUTOSIM 2.0

Description
Add-strut creates a force data object that represents a force that passes through a
two known points. (The direction of the force is derived by AUTOSIM.) The required
argument, symbol, is a symbol used to identify the force. The optional arguments are
defined Table 8.1.14. Note that at least one of the optional arguments point1 or point2
must be included in order for the force to actually affect the system. Typically, most of
the additional arguments are used.

Keyword
:name
:magnitude
:point1
:point2
:x

:x0

:v

:no-forcem

Table 8.1.14. Keyword arguments for add-strut.


Default
Definition
symbol
string of text used in documentation
constant symbol scalar expression for the force magnitude
origin of N
first point of application for the force, which
acts with +magnitude
origin of N
second point of application for the force,
which acts with magnitude
X
dummy variable; if used in magnitude,
AUTOSIM replaces it with the distance
between point1 and point2
X0
dummy variable; if used in magnitude,
AUTOSIM replaces it with the static distance
between point1 and point2
V
dummy variable; if used in magnitude,
AUTOSIM replaces it with the rate of change
of the distance between point1 and point2
NIL
if T, AUTOSIM does not introduce an
intermediate variable for the force magnitude

All of the forces in the system can be printed with the command print-forces.
The magnitude of a specific force is obtained through the fm function.
You should consider modeling a force element as having a known direction, rather
than known points, if the element acts in a direction that changes very little (e.g., a spring
in a vehicle suspension). This is because the expressions derived to connect two points in
space (via add-strut) are usually much more complex than a force with a known
direction (add-line-force). (If there is a question of the validity of the modeling
assumption, model it both ways and compare numerical results.)

8 25

8.1 Commands

AUTOSIM 2.0

Examples
To add a spring or damper, the dummy variable X can be used to represent the spring
deflection, the dummy variable X0 can be used for the static deflection, and the dummy
variable V can be used to represent the deflection rate. The sign convention for a spring
acting between bodies associated with points p1 and p2 is such that when p1 is on a body
that is a descendent of the body associated with point p2, then a spring equation has the
form "-K*(x-x0)" and a damper equation has the form "-D*v". Consider the springdamper element in the example four-bar linkage:
(add-strut fstrut :magnitude "-k*(x - x0) - v*d"
:point1 bp7 :point2 p2 :name "strut force")
FSTRUT: Strut force; Acts on B from the inertial reference through BP7
and pin between strut and N. Magnitude = -FM(1); Direction =
(z(56)*[ny] -z(54)*[bx] -z(53)*[by] + z(55)*[nx]).

Now use the interactive algebra to look at the magnitude of the force derived by
AUTOSIM:
? !"fm(fstrut)"
-FM(1)
? !"symexp(fm(fstrut))"
-(D*U(1)*(PC(10)*(-PC(9) + (XP6 -XP2)*C(3) + (YP6 -YP2)*S(3)) +
PC(9)*(PC(10) -(YP6 -YP2)*C(3) + (XP6 -XP2)*S(3)))/MAX(1.0E-20,
SQRT(ABS((YP6 -YP2)*(YP6 -YP2 -PC(10)*C(3) -PC(9)*S(3)) + (XP6 XP2)*(XP6 -XP2 -PC(9)*C(3) + PC(10)*S(3)) + PC(9)*(PC(9) -(XP6 XP2)*C(3) -(YP6 -YP2)*S(3)) + PC(10)*(PC(10) -(YP6 -YP2)*C(3) + (XP6 XP2)*S(3))))) -K*(SQRT(ABS((XP6 -XP2 -PC(9))**2 + (YP6 -YP2 PC(10))**2)) -SQRT(ABS((YP6 -YP2)*(YP6 -YP2 -PC(10)*C(3) -PC(9)*S(3)) +
(XP6 -XP2)*(XP6 -XP2 -PC(9)*C(3) + PC(10)*S(3)) + PC(9)*(PC(9) -(XP6 XP2)*C(3) -(YP6 -YP2)*S(3)) + PC(10)*(PC(10) -(YP6 -YP2)*C(3) + (XP6 XP2)*S(3))))))

See Also
add-line-force, print-forces, Section 5.5

add-subroutine
Introduce external subroutine.
Usage
add-subroutine where name arguments {:comment string} {:keyword keyword}
Description
Add-subroutine is used to describe an external subroutine that is called from the
program written by AUTOSIM. It is also used to describe multiple-valued functions
when the target language is ADSIM.
The argument where specifies where in the simulation code the subroutine is to be
called. The valid symbols that can be provided for where depend on the target language,
and are summarized in Table 8.1.15.
8 26

8.1 Commands

AUTOSIM 2.0

Table 8.1.15. Places where subroutines can be added.


Keyword
Language
Location
Purpose of added subroutine
adsim
ADSIM
DYNAMIC
calculate forces and moments
derivative
ACSL
DERIVATIVE calculate forces and moments
derivative
Fortran
DIFEQN
calculate forces and moments
1
difeqn
Fortran
DIFEQN
calculate forces and moments
discrete
ACSL
DISCRETE
calculate stuff at discrete intervals
echo
Fortran
ECHO
print data into an echo file
finish
Fortran
FINISH
calculate stuff at end of run
input
Fortran
INPUT
read input data associated with keyword
init
ADSIM
INITIAL
perform initializations before run
init
Fortran1
INIT
perform initializations after all inputs
init
MATLAB
perform initializations before run
kinematics
Fortran
INITNR,
calculate variables involving
DIFEQN
kinematical constraints
output
Fortran
OUTPUT
compute output variables
1
setdef
Fortran
SETDEF
assign default values to program
variables
start
ACSL
before DERIV initialize ACSL variables
1
update
Fortran
UPDATE
calculate stuff once per time step
1 also used for ACSL

Name is the name of the subroutine, and arguments is a list of scalar expressions. If
there is one argument the argument can be provided without enclosing it in a list. If there
are no arguments, arguments should be set to NIL. If string is provided, it is written
immediately before the subroutine CALL statement as a comment. The keyword
argument is required when the subroutine is called from echo or input. The simulation
code includes keyword with its own list of parameters.
Any symbols that appear in expressions in the argument list are assumed to be
parameters and will be included when AUTOSIM writes code to read input files and
write data into echo files. If any of the arguments to the subroutine are Fortran variables
that are not constant, they should be declared first with add-variables.
Numbers can be used as arguments if the subroutines do not modify the arguments. It
is important to distinguish between integer and floating-point numbers, because Fortran
subroutines require that the correct type be provided. If a number is written in
AUTOSIM without a decimal point, or with a trailing decimal point, it is written as an
integer. If it includes a decimal point in any location except the end, it is written as a real
number. For example, to specify the integer 2, enter 2 or 2. (the trailing decimal
point is ignored). To enter the floating-point number 2.0, use 2.0 (with a trailing zero).

8 27

8.1 Commands

AUTOSIM 2.0

AUTOSIM supports types of numbers that are not supported in Fortran, such a ratios,
e.g., 2/3. Do not enter any types of numbers with add-subroutine other than integers
and floating-point numbers.
Any strings specified as arguments are automatically converted to AUTOSIM
expressions. To specify an argument that is a Fortran string, make the first character of
the string a single quote.
If more than one subroutine is added to the same program module (DIFEQN,
KINEMATICS, etc.) with different add-subroutine commands, the subroutine calls
are made in the same order in which they were added. However, subroutines inserted into
the ECHO and INPUT modules are written in alphabetical order according to the
keyword. In the ECHO subroutine, the keyword is used to determine the location of the
external subroutine call. For example, if you add a subroutine to ECHO with a keyword
argument force, an information written by the subroutine would appear in the echo file
after all of the parameters whose names appear alphabetically before the word force,
and before all parameters whose name appear after the word force.
When you add a multiple-value function for use in an ADSIM program, list the
output variables first, then an equal sign, and then the input arguments. (See the example
below.)
If you need to define values for a variable passed as an argument to an external
subroutine, use the command add-equation to assign a value to it.

Example
The following two entries show how strings are interpreted with and without a quote
character:
(add-subroutine difeqn sub1 (1 arg2 "arg3*4/2"))
(add-subroutine difeqn sub2 (2 "'here is a message"))

The above two entries cause the following two lines of code to be included in subroutine
DIFEQN:
CALL SUB1(1, ARG2, 2.0*ARG3)
CALL SUB2(2, 'here is a message')

A multiple-value function in ADSIM is handled the same as an external subroutine in


Fortran or ACSL. Consider the spacecraft example from Appendix C of the Introductory
Guide to AUTOSIM. There is an external subroutine SETFIR whose Fortran argument list
is as follows:
C===================================================================
SUBROUTINE SETFIR(T, ERROR, DBAND, TMIN, THRUST, TOFF)
C===================================================================
C T
--> real
time
C ERROR --> real
error quantity used in control law below
C DBAND --> real
"dead band" for controller
C TMIN
--> real
minimum time for keeping rocket on
C THRUST <-- real
thrust from rocket

8 28

8.1 Commands
C

TOFF

<-> real

AUTOSIM 2.0
time to turn rocket off

Code to call this subroutine from a Fortran program is generated with a command such as
(add-subroutine update setfir
(t "gc*ru(b,1) + rq(b,1)" dband tmin thrustx toffx))

The above command leads to the Fortran statement:


CALL SETFIR(T, (Q(4) + GC*U(4)), DBAND, TMIN, THRUSTX, TOFFX)

When adding a routine to Fortran, there is no need to worry about whether arguments are
inputs or outputs. However, for ADSIM, it is necessary to specify that there are five
inputs (T, ERROR, DBAND, TMIN, TOFF) and two outputs (THRUST, TOFF).
Assuming that a multi-valued function has been written in ADSIM that returns values for
THRUST and TOFF, it would be described in the AUTOSIM input as
(add-subroutine adsim setfir
(thrustx toffx = t "gc*ru(b,1) + rq(b,1)" dband tmin toffx))

The ADSIM code would then include the following line:


THRUSTX, TOFFX = SETFIR(T, (Q(4) + GC*U(4)), DBAND, TMIN, TOFFX)

See Also
add-equation, add-variables, Section 6.3

add-to-erd-header
Add extra line to header of output file generated by Fortran program.
Usage
add-to-erd-header keyword {arg}*
Description
Add-to-erd-header generates code in subroutine OPNOUT to include an extra line
in the header of an output file. The reason for using this capability is to add information
to the file that would be useful in supported automated post-processing software.
Example
The following AUTOSIM input,
(add-to-ERD-header "SPEEDMPH" !"speed/88.0 / 12.0 * 60.0")

leads to the following two lines of code in the OPNOUT subroutine


WRITE(IFILE, '(A, G13.6, '', '')') 'SPEEDMPH',
&
5.681818181818182E-2*SPEED

which, in turn, leads to the following line in the header of the file written by the
simulation code:

8 29

8.1 Commands

AUTOSIM 2.0

SPEEDMPH 55.0000

add-variables
Declare variables .
Usage
add-variables where type {variable}*
Description
Add-variables is used mainly for two reasons: (1) to declare that a symbol varies
with time, as opposed to being a constant parameter, and (2) to define variables that
appear in external subroutines (added with the command add-subroutine) that
receive values from the subroutines.
The argument where specifies where in the simulation code the variables are
declared. Table 8.1.16 defines the valid symbols that can be provided for where. Most of
the values for where are simply the names of Fortran subroutines. Exceptions are noted in
the table.

Where
acsl-main
dyvars
difeqn
echo
finish
input
init
output
setdef
sypars
update

Table 8.1.16. Places where variables can be added.


Language
Location
Notes
ACSL
MAIN
declared at start of ACSL program
1
all
/DYVARS/ common block with multibody variables
2
Fortran
DIFEQN
Fortran
ECHO
Fortran
FINISH
Fortran
INPUT
2
Fortran
INIT
Fortran
OUTPUT
compute output variables
Fortran2
SETDEF
assign default values to program
variables
Fortran
/SYPARS/ common block with system parameters
2
Fortran
UPDATE

1 used for Fortran, ACSL, ADSIM, C, and MATLAB; 2used for both Fortran and ACSL

The argument type should a valid Fortran data type, such as INTEGER, REAL, etc.
Floating-point variables should be declared with the symbol real, in order to let
AUTOSIM write programs in single- and double-precision based on the global variable
*double-precision*. To prevent AUTOSIM from declaring the type based on the
setting of *double-precision*, use explicit types such as real*4 or real*8.

8 30

8.1 Commands

AUTOSIM 2.0

Symbols introduced with add-variables are recognized by AUTOSIM as being


variable, rather than constant. Thus, the time derivatives are not zero. They are set by
default to be the symbol ????. If the variables appear only as arguments to external
subroutines, their derivatives are of no interest, other than the fact they are not zero.
However, if the variable appears in a constraint equation (from add-positionconstraint or add-speed-constraint), AUTOSIM may need its derivative.
Also, you might apply dxdt to an expression containing a new variable, in which case
the correct derivative is needed. Use the command set-derivs to assign the correct
derivatives to variables in these cases.
One-dimensional arrays can be declared with add-variables. To declare an array,
variable should be a string with the form "name(dimension)", e.g., "A(100)".
Examples
Suppose we want to include variables x1 and x2 in the equations of motion, and that they
are computed by a hand-written subroutine EXTSUB(A, X1, X2, TEMP), where A is an
input angle, X1 and X2 are the outputs, and TEMP is an array with 10 elements.
(add-variables dyvars real x1 x2 "temp(10)")
(add-subroutine difeqn extsub ("rq(b)" x1 x2 temp))

Suppose we want to use the symbols TAUPF and PHIF in equations, and that their
derivatives are represented by the symbols DTAUPF and DHIPF.
(add-variables dyvars real taupf dtaupf phif phipf)
(set-derivs taupf dtaupf phif phipf)

See Also
add-parameters, add-subroutines, set-derivs, Sections 5.6, 6.5

dynamics
Derive equations of motion for multibody system.
Usage
dynamics {:formalism method} {:conditional-lud clud}
{:nonrecursive-lud nr}
Description
This command is used to derive the equations of motion for the multibody system with
some control over the methods used. If the default derivation method is desired, then this
command is not needed. It is applied automatically by the finish command.
This command should be invoked after the complete multibody system has been
described, including bodies, constraints, forces, moments, external subroutines, auxiliary
parameters, and auxiliary variables. However, it is possible to add output variables before
or after applying the dynamics command.

8 31

8.1 Commands

AUTOSIM 2.0

The exact nature of the analysis depends on the arguments provided. There are
presently four formulations that can be used to derive the equations of motion. In three of
these, implicit dynamical equations are derived with the matrix form:
.
Mu =f

(8.1)
.
where M is a mass matrix, u is an array of the derivatives of the independent speeds,
and f is called the force array. If the .elements of M and f are known, linear algebra can be
used to solve for the elements of u . Alternatively, the equations can be formed using a
recursive algorithm in which the matrix form of Eq. (8.1) is never constructed. Table
8.1.17 summarizes the four options, which are specified by the symbol method,
associated with the :formalism keyword.
Table 8.1.17. Four formalisms for the dynamical equations.
Method
1 numericallud

Dynamical Equations
Elements of M and f are
defined, subroutines LUD1
and BKSUB1
. are used to
solve for u numerically.

Discussion
This option usually involves the
fastest derivation of the equations.
If M is sparse, the equations are not
as efficient as options 3 and 4.
However, if clud is set T, the
difference is sometimes negligible.
2 order-n
Eq. (8.1) is never formed. A This option is subject to limits in
recursive, order(n)
topology and requires special
algorithm is used.
modeling of the system. It can take
longer to derive the equations than
the other methods, particularly for
small systems.
3 show-massElements of M and f are
This is identical to method 4,
matrix
identified in the equations, except that the elements of M and f
Eq. (8.1) is solved.
are identified in the generated code.
symbolically for u .
4 symbolic-lud Eq. (8.1) is solved.
This is the default method. If the
symbolically for u .
dimension of M is large, the
derivation may take a long time.

Three of the methods in the table are closely related. Methods 1, 3, and 4 use Kanes
equations for deriving the dynamical equations in the form of Eq. (8.1). The order-n
method uses an algorithm developed by Dr. Wehage at the U.S. Army Tank and
Automotive Command (TACOM). The order-n method, as programmed in version 2.0, is
subject to two restrictions: (1) there can be no constraints added via motion, nomovement, etc., and (2) each body must have a single degree of freedom relative to its
parent. The second restriction means that bodies with more than one degree of freedom
must be broken up into a set of massless bodies, as shown below in an example.

8 32

8.1 Commands

AUTOSIM 2.0

The argument clud (:conditional-lud) does not affect the formulation of the
equations of motion, but does influence the way in which the derivatives are computed
for all of the formalisms except order-n. When NIL, the equations are written such that
all computations involving variables are updated whenever the subroutine DIFEQN is
called. When clud is T, the Fortran code that decomposes the mass matrix is enclosed in
an IF-THEN block which is skipped if the generalized coordinates appearing in the mass
matrix have not changed much since the last time the decomposition was performed. For
small systems (n < 5) this has a small effect. However, for large systems, (n > 10), the
computation of the decomposed mass matrix takes up a larger portion of the overall
computational effort. The threshold for updating the mass matrix is determined by two
Fortran variables: UPDTA and UPDTD. UPDTA is the change in angle threshold,
nominally 0.01 rad. UPDTD is the threshold for translational displacement, and is
nominally 0.01. Both of these variables are assigned values in the subroutine SETDEF.
Generalized coordinates that appear in the mass matrix are monitored using a subroutine
DOLUD, which is called from UPDATE. The conditional LUD code is generated only
when the target language is Fortran or ACSL.
None of the four methods in the Table are best for all multibody systems. If youre
concerned with numerical efficiency, try several to find the best for a particular
multibody system. If computer memory is limited, then methods 3 and 4 may require
long derivation times for systems with many DOF. If the simulated conditions are such
that the mass matrix changes little, considerable improvements in efficiency can be
obtained by setting clud to T. At the same time, the improvements obtained by using a
symbolic LUD instead of a numerical LUD are diminished. Therefore, a good
combination to use for large systems, particularly as a first try, is to use method 1 from
Table 8.3 and also set clud T.
The argument nr (:nonrecursive-lud)
specifies whether the symbolically
.
uncoupled equations for u are recursive or nonrecursive. The recursive solution is used
when nl is NIL, the default, and is generally more efficient by a factor of 3. . The
nonrecursive solution (nr is T) is mainly of interest when explicit equations for u are
needed for some applications other than numerical simulation, such as stability analyses.
Example
Suppose body B is unrestricted in planar motions. That is, it can translate in two
directions, and rotate about an axis perpendicular to the plane. The simplest way to
describe it is
(add-body b :translate (1 2) :body-rotation-axes 3)
...
(finish)

If we want to use the order-n option, it is necessary to break up the body into three, where
the first two are massless:
(add-body
(add-body
(add-body
...
(dynamics

bpp :translate 1 :mass 0 :inertia-matrix 0)


bp :parent bpp :translate 2 :mass 0 :inertia-matrix 0)
b :parent bp :body-rotation-axes 3)
:formalism order-n)

8 33

8.1 Commands

AUTOSIM 2.0

(finish)

See Also
finish, Section 5.8

equilibrium
Derive equations needed to compute equilibrium position for system.
Usage
equilibrium
Description
This command causes AUTOSIM to perform an equilibrium analysis rather than a
dynamic analysis. The equilibrium command must precede the finish command.
A simulation program written after applying the equilibrium command is similar in
appearance to a dynamical simulation. It has the same program structure, subroutine
names, common blocks, input and output files, etc. The outputs are also generated as
functions of time. However, in the equilibrium simulation, time is used only as an
arbitrary independent variable for defining force histories. Response variables are not
dynamic, but are computed solely on the basis of the forces and torques applied to the
system.
Computationally, the equilibrium problem is more difficult than the dynamics
problem. There is not always an equilibrium position. The system model may be
unstable. Even for a stable system, the equilibrium computation requires the simultaneous
solution of a set of nonlinear algebraic equations. This type of calculation is sometimes
difficult unless specialized numerical analysis techniques are selected and employed.
If an equilibrium simulation program generated by AUTOSIM does not run, try
generating a dynamic program to determine that the system is indeed stable. As an
alternative to using an equilibrium simulation program, a dynamic simulation program
can be run with applied forces being varied so slowly that the simulation is quasi-static.
Details of the form of the equilibrium analysis are presented in Section 2.2. This
analysis option is implemented only for generating Fortran code.
Example
Perform an equilibrium analysis with the following commands
(equilibrium)
(finish)

See Also
Section 2.2, finish, Section 5.8

finish
Finish the analysis of the multibody system.
8 34

8.1 Commands

AUTOSIM 2.0

Usage
finish {:expand-zees expand}
Description
This command applies the final stage of the analysis used to form nonlinear equations of
motion. It derives nonlinear equations of motion and then inspects the equations. On
inspection, it identifies the expressions needed to compute output variables or derivatives
of state variables. It also identifies symbols that are needed as input parameters to solve
the equations. Only those symbols and equations that are significant are written into the
output.
The optional Boolean argument expand determines if intermediate variables (Zs) that
appear only once should be left in the equations, or expanded to be replaced by the
expressions that they represent. Setting expand to T produces fewer, more complicated
equations, and is sometimes marginally more efficient. The default value for expand-zees
is NIL. For complex systems, the default value is recommended.
Once this command is executed, the description of the multibody system is frozen
and no inputs are permitted that would involve modification of the equations of motion.
However, it is OK to modify names of variables and parameters, units, default values,
etc.
Unless the linear, dynamics, or equilibrium commands have been applied,
this command automatically applies the dynamics command.
See Also
dynamics, equilibrium, linear, Section 5.8

finish-update
Finishes processing of equations in Fortran subroutine UPDATE.
Usage
finish-update {where}
Description
This command is used to finish the equations in the UPDATE block of the multibody
equations. It is typically used before defining output variables that involve substantial
computation. Define them after calling FINISH-UPDATE, and the equations will all be
put in subroutine OUTPUT. The optional argument WHERE is either 'UPDATE or
'OUTPUT. The default is 'UPDATE, so you normally don't bother with it. (In the
unlikely event that you do provide a value for where, the name of the routine must be
preceded with a single quote character.)
Unless the linear, dynamics, or equilibrium commands have been applied,
this command automatically applies the dynamics command.
Example
Output variables such as kinetic energy and reaction moments can involve substantial
computation. To keep those calculation out of the integration loop, use the finish8 35

8.1 Commands

AUTOSIM 2.0

update command before defining them as outputs. Consider the kinetic energy for the
spacecraft system in Appendix C of the Introductory Guide to AUTOSIM.
(finish-update)
(add-output (ke) "K.E." :long-name "Kinetic Energy" :units "L*F")
(finish)

See Also
dynamics, equilibrium, finish, linear

in-lb
Set the units system to English in-lb-sec.
Usage
in-lb
Description
This command establishes the units for the multibody system as in-lb (all units are
derived from L=in, F=lb, and T=sec). There are several exceptions to a consistent
dynamics units system: masses are entered and echoed as lbm, related to lb-sec2 /in by
the gravitational factor G=386.2 in/sec 2; angles are entered and echoed as deg, related
to radians by 57.3 deg/rad; and acceleration is output in Gs, related to in/sec 2 by
G=386.2 in/sec2. The units system is summarized in Table 8.1.18.
Table 8.1.18 Summary of in-lb units system.
Units Expression
Name
Generic Name
L
in
Translation
A
deg
Angle
T
s
Time
F
lb
Force
C
counts
Counts
L/T
m/s
Speed
L/T**2
g''s
Acceleration
A/T
deg/s
Angular Speed
A/T**2
deg/s2
Angular Acceleration
F*L
N-m
Moment
F*L/A
in-lb/deg
F*L*T/A
in-lb-s/d
F*T**2/L
lbm
Mass
F*L*T**2
in-lb-s2
Inertia

8 36

Gain
1
DR
1
1
1
1
1/G
DR
DR
1
1/DR
1/DR
G
1

8.1 Commands

AUTOSIM 2.0

See Also
mks, si, Section 5.10

install-differential
Install definition of function differential.
Usage
install-units form1 form2 {:d d} {:echo echo}
Description
This command installs the information needed to derive partial derivatives and time
derivatives of a new function or symbol. If form1 is a symbol, then form2 is its
derivative. If form1 is a function, then both form1 and form2 are templates. All
arguments to the function in form1 must be dummy arguments, represented with symbols.
form2 is the derivative, written as a function of the dummy arguments. Differentials in
form2 are written as functions of d, where d is the symbol D unless the optional
keyword argument specifies a different symbol. (Use the D keyword in the extremely
unlikely event that you use a function named D and form2 involves your function D.)
If you want to see the Lisp code generated by AUTOSIM for the new differential
function, set the optional variable echo to T.
Example
Suppose the definition for the sine function were not installed in AUTOSIM. It could be
installed with the statement:
(install-differential "sin(x)" "d(x)*cos(x)" :echo t)
(LAMBDA (Y X D)
(MUL (MAKE-FUNC 'COS (NTH 0 (FUNC-ARGS Y)))
(FUNCALL D (NTH 0 (FUNC-ARGS Y)) X)))
"installed derivative for function SIN"

See Also
dxdt, partial, Section 6.6

install-func
Install new Lisp functions to work with make-func
Usage
install-func {symbol function}*
Description
Use the command install-func to install a new procedure in AUTOSIM as a
function to be recognized and applied in f-strings. When symbol is used as the name of a
function in an f-string, AUTOSIM applies function. (If the function is not installed, the
function call is written into the target language when the simulation code is generated.)

8 37

8.1 Commands

AUTOSIM 2.0

Given that all of the standard AUTOSIM functions are already installed, this utility
command is of use only if you have programmed a new function in Lisp.
Example
When the SIN function is encountered in an F-string, AUTOSIM applies the function
make-sine. If make-sine were not already installed, you could use the command
(install-func sin make-sin)

install-indexed-parameters
Install one-dimensional parameter arrays.
Usage
install-indexed-parameters id {parameter }*
Description
Use this command to define indexed parameters in your models. Section 2.1 describes
how indexed parameters appear to the user of an AUTOSIM-generated Fortran program.
Each symbol parameter is the name of an array in the /INPARS/ common block of the
Fortran program generated by AUTOSIM. The mandatory argument id is a hidden
parameter that can be used on input to identify the index of a parameter array element.
Example
The pitch-plane vehicle example has parameters CF and CR for damping coefficients in
the front and rear, KF and KR for front and rear spring rates, KTF and KTR for front and
read spring rates, MAF and MAR for front and rear axle masses, and WF and WR for
front and rear wheel loads. Suppose we want to replace them with indexed parameters D i,
Ki, KT i, MAi, and Wi, where i=1,2. One of the first lines in the input file defines the
sprung mass of the vehicle as "wf + wr - maf - mar". Using indexed parameters,
this would be written "w(1) + w(2) - ma(1) - ma(2)". By default, AUTOSIM
would treat the symbols W and MA as functions, with arguments 1 and 2. To override
this default behavior, we must first use the command i n s t a l l - i n d e x e d parameters to inform AUTOSIM that these symbols are parameter arrays.
(install-indexed-parameters id d k kt ma w)

See Also
Sections 2.1, 5.10

install-table
Install definition of linear interpolation or spline function.
Usage
install-table function title {:default default} {:echo echo} {:read read}
{:deriv deriv} {:npts npts} {:ntabs ntabs} {:table-

8 38

8.1 Commands

AUTOSIM 2.0
function table-function} {:common common} {:xunits
xunits} {:yunits yunits} { :keyword keyword} {:id i d }
{:values values}

Description
Install-table is used to automatically generate code for a Fortran function of the
form f(x), where f is a dependent variable and x is an independent variable. If the function
stores more than one table, then the form is f(x, i), where i is the number of the table. The
function is derived from a table of X-Y pairs of values. The name of the new function is
specified by the mandatory argument, function. A string of text printed in output files is
specified by the other mandatory argument, title. Table 8.1.18 defines the keyword
arguments. In the table, default symbols are based on function, which is written as F . For
example, if the new function is called ROAD, the name of the subroutine to set default
values is ROADDEF unless the optional keyword argument is specified.
Table 8.1.19. Keyword arguments for install-table.
Keyword
Default
Definition
:default
FDEF
name of subroutine to set default values of table
:echo
FECHO
name of subroutine to write table into echo file
:read
FREAD
name of subroutine to read table from input file
:deriv
NIL
name of function to computer the time derivative of F. If
NIL, no function is defined.
:npts
10
maximum number of points in table
:ntabs
1
number of tables that are accessed by F
:tableTABF
type of table. Options are: TABF, TABE, SPLINE, and
function
SPLINF.
:common
CF
name of Fortran COMMON block used to store table(s)
for F
:xunits
T
units of X values in table
:yunits
L
units of Y values in table
:keyword
function
keyword for input and output PARSFILEs
:values
((0 0) (1 1)) set of numbers to use as default values in table

The command install-table installs the auxiliary subroutines and creates a new
AUTOSIM command to work with write-sim and write-to-file. The new
command is named write-function. (E.g., if function is F, then the new command is
named write-f.)
There are four kinds of built-in table-lookup methods: tabe, tabf, spline, and
splinf. The first two interpolate between points linearly, and the latter two use a cubic
spline. With options tabe and spline, points lying outside the range of the table are
generated by extrapolating. With options tabf and splinf, points lying outside the
range of the table are generated by assuming a zero slope (they are flat). Figure 8.1.2

8 39

8.1 Commands

AUTOSIM 2.0

shows how the four methods compare when applied to the four-point table: ((1 1) (1.5
1.1) (2.5 2) (3 3)).
5
3
tabe
tabf
spline

splinf
2

3
2
1
1
0

0
0

2
3
4
0
1
2
Figure 8.1.2. Examples of four table functions.

Examples
The Introductory Guide to AUTOSIM includes several examples showing how
install-table is used. One of these is the pitch-plane vehicle model, in which the
road profile is a function of distance: ROAD(X). Suppose that we want not only the
vertical position of the road under a vehicle tire, but also its vertical rate. Install the table
function ROAD and an auxiliary function RP for the differential:
(install-table road "Road profile (Z coord. vs. X coord.)"
:table-function tabf :npts 1000 :deriv rp
:xunits l :yunits l :keyword road-profile
:values ((0 0) (1 .05) (2 .05) (3 0)))

The vertical position of the road as a function of the longitudinal position of point AF0 is
derived by AUTOSIM from the following description:
? !"road(dot([nx],pos(af0)))"
ROAD(Q(1) + Q(4)*S(3))

In addition, the vertical velocity of the road is derived by AUTOSIM from the following:
? !"dxdt(road(dot([nx],pos(af0))))"
(QP(1) + QP(3)*Q(4)*C(3) + QP(4)*S(3))*RP(Q(1) + Q(4)*S(3))

Note that the derivative involves the auxiliary function RP, as well as the vehicle speed
variables QP(1), QP(3), and QP(4).
See Also
Section 5.7

install-units
Install exception to existing units system.

8 40

8.1 Commands

AUTOSIM 2.0

Usage
install-units units {:name name} {:gain gain} {:gen-name generic-name}
Description
This command defines an exception to the existing units system, to specify that a certain
combination of units should be printed with a different name, converted by gain when
written as an output, or identified with a more specific generic-name.
AUTOSIM determines a property (name, gain, or generic-name) of a units expression
by first checking to see if the epxression has been installed directly with installunits. If it is, the associated property is returned. If not, the properties from those of the
symbol elements. For example, consider the expression F/L. Typically, this particular
units expression is not installed. If the name of this expression is derived by replacing the
symbol F is with the associated name (N), and the symbol L with the associated name
(m), to yield a name such as N/m. With gains, the gains for the individual symbols are
multiplied and divided to derive the gain for the entire expression.
The general approach in defining a new units system is to define properties of the
basic units symbols (L, F, A, etc.), and then define exceptions where gains or names can
not be derived.
Example
Add millimeters to the SI units system, which normally only recognizes m, N, kg, and
sec. To maintain a distinction between meters and millimeters, let meters remain as the
default unit of length, and call the mm unit MM.
(install-units "MM" :name "mm" :gain 1000 :gen-name "length")

After the symbol MM is installed, parameters can have their units set to MM. In a
simulation code generated by AUTOSIM, parameter values are automatically divided by
1000 when read in, and automatically multiplied by 1000 when written out.
See Also
units, Section 5.10

kinematics
Derive multibody kinematical equations.
Usage
kinematics
Description
You need to use kinematics only if you introduce subroutines in DIFEQN that
involve explicit references to derivatives of the generalized coordinates [QP(1), QP(2),
etc.]. Kinematics forms equations that compute these derivatives.
See Also
Section 5.8

8 41

8.1 Commands

AUTOSIM 2.0

large
Declare that one or more parameters are large.
Usage
large {symbol}*
Description
This command is used to declare that each symbol is large. This is occasionally applied
to large stiffness values that are multiplied with small deflections to obtain forces or
moments that are not small.
See Also
*small-order*, small, Section 5.10

lifo
Print an equation set in reverse order (last-in, first-out).
Usage
lifo eqs
Description
This command prints an equation set in reverse order. It is provided as a debugging tool,
to easily view the most recent equations in a large set.
Example
? (lifo *pre-comp*)
PC(4) = L -PC(3)
PC(3) = L*PC(1)*PC(2)
PC(2) = 1.0/(WR -MAF -MAR + WF)
PC(1) = WR -MAR
(PC(4) PC(3) PC(2) PC(1))

linear
Linearize the equations of motion for the multibody system.
Usage
linear {:u u} {:y y}
Description
This command derives equations of motion that are linearized to obtain the form
.
x = A x + B u
where x is an array of perturbations, u is an array of inputs, and A and B are matrices.
Also, a set of derived output variables y can be expressed as

8 42

8.1 Commands

AUTOSIM 2.0
y = C x + D u

where C and D are also matrices. The matrices A, B, C, and D can be functions of x and
u. These matrices represent the linearized system relative to an arbitrary operating point,
and thus the calculation of the matrix elements can involve nonlinearities. In this type of
analysis, the equations of motion consist of the computations used to set numerical values
of the elements of the matrices A, B, C, and D.
AUTOSIM derives the elements in the A, B, C, and D matrices by taking partial
derivatives of the nonlinear equations with respect to state variables. Thus, it is essential
that all functions appearing in the equations of motion have known partial derivatives.
(Use the install-differential command to install knowledge of external
functions, if needed.)
The set of state variables is obtained automatically using coordinates and speeds
introduced by AUTOSIM.
You must provide the set of inputs, if there are any, using the optional argument u. If
there is just one input, use it as the value of u. If there are more than one inputs, put them
in a list. There is a significant difference between the way input variables are described
for a linear and nonlinear analysis. In a nonlinear simulation, inputs are generally
functions of time determined by a function or table of values. For a linear analysis, inputs
are symbols that never appear in the A, B, C, and D matrices. It is essential that all input
variables be symbols, declared as variables with the add-variables command. (The
where argument for add-variables should be set to dyvars.)
The dependent variables y can be provided as a list of expressions. If a list is not
provided, AUTOSIM uses the independent speeds to create a y array. Note that the
dependent variables are defined as linear combinations of the state variables. This means
that only position- and speed-type variables are valid for y. (No accelerations!)
After the matrices are derived, the matrices are typically written in the MATLAB
language with the write-matlab command.
Example
Consider the pitch-plane vehicle model. The input for the nonlinear simulation is a road
profile, defined by the function ROAD(X) under the front and rear axles. For the linear
analysis, we instead introduce two symbols ZF and ZR for the vertical position of the
road under the two axles.
(add-variables dyvars real zf zr)
...
(linear :u (zf zr))

See Also
add-variables, write-matlab, Sections 3.1, 5.8

8 43

8.1 Commands

AUTOSIM 2.0

load-autosim
Load AUTOSIM compiled files into full Common Lisp system.
Usage
load-autosim source-path compile-path configure-file {:compile-extension
compile-extension} {:source-extension source-extension}
Description
This command is not included with AUTOSIM unless you obtain AUTOSIM in a form to
work with an independent Lisp system. It is used to install AUTOSIM on a new machine
as a part of an existing Lisp system, or to port AUTOSIM to a new machine.
Source-path is a string giving the pathname to the subdirectory or folder with source
code; compile-path is a string giving the pathname to the subdirectory or folder with
compiled code; configure-file is a string with the name of a file in source-path with
compiler-specific details; compile-extension is a string with extensions appended to
compiled file names (def=".fas"); and source-extension is an extension for source files
(def=".lsp"). Each source file is compiled if (1) it exists, and (2) either (a) its date is
newer than the corresponding compiled file, or (b) there is no compiled file.
If AUTOSIM is provided as a set of compiled object files, then provide an empty
string as the value for source-path. The source code is provided for this command, so it
can be modified as needed by a Lisp programmer.

mks
Set the units system to SI, but with degrees and gs.
Usage
mks
Description
This command establishes the units for the multibody system as mks (all units are derived
from L=meters, F=Newtons, and T=seconds). There are two exceptions to a consistent
dynamics units system: angles are in degrees, and acceleration is output in Gs, related
to m/sec2 by G=9.86 m/sec2. The units system is summarized in Table 8.1.20.
See Also
in, si, Section 5.10

8 44

8.1 Commands

AUTOSIM 2.0

Table 8.1.20. Summary of MKS units system.


Units Expression
Name
Generic Name
L
m
Translation
A
deg
Angle
T
s
Time
F
N
Force
C
counts
Counts
L/T
m/s
Speed
L/T**2
g''s
Acceleration
A/T
deg/s
Angular Speed
A/T**2
deg/s2
Angular Acceleration
F*L
N-m
Moment
F*T**2/L
kg
Mass
F*L*T**2
kg-m2
Inertia

Gain
1
DR
1
1
1
1
1/G
DR
DR
1
1
1

motion
Constrain a body degree of freedom to follow a prescribed motion.
Usage
motion q exp
Description
This command adds two constraint equations, one for speed and one for position, that
declare that
dexp
u = dt

q = exp

The motion command checks the body to ensure that the body has been described such
that there is a generalized speed for which
dq
=u
dt
If this is not true, then you must use some combination of the add-positionconstraint, add-speed-constraint, or no-movement commands.
The functions rq and rt should be used to specify q when using this command, to
prevent the potential error of specifying the wrong index when specifying q directly.
Example
To force body B to rotate with a prescribed sinusoidal motion, the following inputs might
be used.
(add-body b :parent-rotation-axis z)
(motion "rq(b)" "A*sin(2*@pi*freq*t)")

8 45

8.1 Commands

AUTOSIM 2.0

See Also
add-position-constraint, add-speed-constraint, no-movement, Section
5.4

no-movement
Eliminate movement between two points in one direction.
Usage
no-movement point1 point2 direction {:q q} {:u u}{:confirm confirm}
Description
This command modifies the multibody system kinematics such that there is no movement
between point1 and point2 in the direction direction. The command eliminates a
generalized speed and converts and independent coordinate to a computed coordinate.
The optional arguments q and u are used to specify exactly which coordinate (q) and
speed (u) are to be eliminated by the constraints. Except for very simple systems, both of
these optional arguments should be provided.
In the event that :q and :u are not specified, the command applies built-in rules to
try to select a coordinate and speed to eliminate. If the selection is unsuccessful, nomovement does nothing other than to print a message. If you do not specify the speed
and coordinate to eliminate, you can set the optional argument confirm to T to cause the
command to describe its choices and give you a chance to cancel. (If you not approve of
the variable selected by the command, no action is taken.) The default is NIL.
Example
In the four-bar linkage example, motions of the various bodies are in the X-Y plane.
After the three rigid bodies are added, all of the joints are accounted for except one
between bodies A and C. Specifically, there is a pin joint connecting the two bodies at
point AP3 (in body A) and point CP3 (in body C). The constraints of the joint are such
that there can be no movement between points AP3 and CP3 in the X and Y directions.
This information is communicated to AUTOSIM with two no-movement commands:
(no-movement ap3 cp3 [ny] :q "rq(a)" :u "ru(a)")
(no-movement ap3 cp3 [nx] :q "rq(c)" :u "ru(c)")

See Also
add-position-constraint, add-speed-constraint, Section 5.4

print-bodies
Print summaries of data from all bodies in the system.
Usage
print-bodies {short}

8 46

8.1 Commands

AUTOSIM 2.0

Description
If short is NIL (the default) the print-body command is applied to each body in the
system, except N. If short is T, a short summary is printed instead.
Example
Consider the four-bar linkage example:
? (print-bodies t)
A; parent=N; rot coord = Q(1)
B; parent=N; rot coord = Q(3)
C; parent=B; rot coord = Q(2)

See Also
print-body, Section 5.9

print-body
Print extensive summary for one body.
Usage
print-body body {stream}
Description
Print-body prints an extensive summary of all information pertaining to body,
including the coordinates and speeds introduced for its degrees of freedom, the unitvectors, its mass and inertia properties, a direction cosine matrix, etc. The optional
argument stream supports the command write-to-file.
The terms that are printed are defined in a journal article, Symbolic Vector/Dyadic
Multibody Formalism for Tree-Topology Systems. Journal of Guidance, Control, and
Dynamics, Vol. 14, No. 6, Nov/Dec 1991, 1240-1250, by M.W. Sayers.
Example
Following is a print-out obtained for body C in the four-bar linkage example:
Slots In Body C
parent
level
Name
recursive in rotation?
recursive in translation?
body mass
IC*
unit-vectors
rotational coordinates
rotational speeds
rotational directions
joint point (in parent)
mass center of composite body

wC

B
2
C
ROTOR
T
MC
IC (nZ nZ)
cX, cY, nZ
Q2
-Z31 U1
nZ
PC1, -PC2, 0
-PC3, PC4, 0
(1.0 -Z31) U1 nZ
8 47

8.1 Commands
vC0
direction cosine matrix

AUTOSIM 2.0
PC1 U1 bY + PC2 U1 bX
(C2 S2 0), (-S2 C2 0), (0 0 1.0)

To obtain the above table, a printout in RTF was obtained as follows:


? (rtf (print-body c))
\pard\plain \s254\qj\sb480\keepn \b\f20\fs28 Slots In Body C\par
\pard\plain \qj\sl280 \f20 parent\tab B\par
level\tab 2\par
...

The contents of the file rtf header were inserted in front of the printout, and the
resulting RTF text, saved as a plain text file, was opened in Microsoft Word and edited
manually. (The editing involved changing a tab setting.)
See Also
print-bodies, write-to-file, Section 5.9

print-constraints
Print replacement expressions for dependent speeds.
Usage
print-constraints {stream}
Description
Print-constraints prints replacement expressions for dependent speeds resulting
from speed constraints. It is used to determine which speeds were removed by
AUTOSIM, and to view the sorts of expressions introduced in place of the speeds. The
optional argument stream supports the command write-to-file.
Example
Consider the four-bar linkage example:
? (print-constraints)
MOTION CONSTRAINTS
==================
Abs. Z rot. speed of A: Z(33)*U(1)
Z rot. speed of C rel. to B: -Z(31)*U(1)

See Also
write-to-file, Section 5.9

8 48

8.1 Commands

AUTOSIM 2.0

print-coordinates
Print names and definitions of generalized coordinates.
Usage
print-coordinates {stream}
Description
Print-coordinates prints the names and definitions of all coordinates introduced by
AUTOSIM. The optional argument stream supports the command write-to-file.
Example
Consider the four-bar linkage example:
? (print-coordinates)
MULTIBODY COORDINATES
=====================
Q(1): (comp.) Abs. Z rot. of A (rad)
Q(2): (comp.) Z rot. of C rel. to B (rad)
Q(3): Abs. Z rot. of B (rad)
NIL
? (write-to-file print-coordinates "temp")
file "temp" created with PRINT-COORDINATES

See Also
write-to-file, Section 5.9

print-default-directions
Print global coordinates of local directions vectors using default numerical values.
Usage
print-default-directions {stream}
Description
This command is designed to help debug AUTOSIM input descriptions. It (1) derives the
global X, Y, and Z coordinates of the unit-vectors for each body in the system, (2)
replaces all parameters and variables with their default numerical values, and (3) prints a
table showing the numerical values for the X, Y, and Z coordinates. When all of the
coordinate systems are not parallel in the nominal configuration, this information can
quickly reveal problems in orientation. The optional argument stream supports the
command write-to-file.
In order for this command to provide representative information, you should set the
default values for all geometric parameters using the set-defaults command.
Example
Consider the four-bar linkage example:
? (print-default-directions)

8 49

8.1 Commands

AUTOSIM 2.0

Default orientations of all bodies in 4-bar linkage


BODY
LOCAL X
LOCAL Y
LOCAL Z
========================================================================
N
1.000 0.000 0.000
0.000 1.000 0.000
0.000 0.000 1.000
A
1.000 0.000 0.000
0.000 1.000 0.000
0.000 0.000 1.000
B
1.000 0.000 0.000
0.000 1.000 0.000
0.000 0.000 1.000
C
1.000 0.000 0.000
0.000 1.000 0.000
0.000 0.000 1.000
NIL
? (write-to-file print-default-directions "temp")
file "temp" created with PRINT-DEFAULT-DIRECTIONS

See Also
set-defaults, write-to-file, Section 5.9

print-default-positions
Print global and local coordinates of all points using default numerical values.
Usage
print-default-positions {stream {format-string}}
Description
This command is designed to help debug AUTOSIM input descriptions. It (1) derives the
relative and global X, Y, and Z coordinates all points in the system, (2) replaces all
parameters and variables with their default numerical values, and (3) prints a table
showing the numerical values for the X, Y, and Z coordinates. This information can
quickly reveal problems in orientation or position of reference points. The optional
argument stream supports the command write-to-file.
In order for this command to provide representative information, you should set the
default values for all geometric parameters using the set-defaults command.
Example
Consider the four-bar linkage example:
? (print-default-positions)
Default positions of all points in 4-bar linkage
Relative Position
Global Position
POINT BODY
X
Y
Z
X
Y
Z
========================================================================
A0
A
0.000
0.000
0.000
0.100
0.300
0.000
AP3
A
0.300
0.000
0.000
0.400
0.300
0.000
B0
B
0.000
0.000
0.000
0.000
0.000
0.000
BP7
B
0.300
0.000
0.000
0.300
0.000
0.000
C0
C
0.000
0.000
0.000
0.400
0.000
0.000
CCM
C
0.050
0.200
0.000
0.450
0.200
0.000
CCMC
C
0.050
0.200
0.000
0.450
0.200
0.000
CJ
B
0.400
0.000
0.000
0.400
0.000
0.000
CP3
C
0.000
0.300
0.000
0.400
0.300
0.000
CP5
C
0.100
0.210
0.000
0.500
0.210
0.000
O
N
0.000
0.000
0.000
0.000
0.000
0.000
P1
N
0.100
0.300
0.000
0.100
0.300
0.000
P2
N
0.300
0.500
0.000
0.300
0.500
0.000

8 50

8.1 Commands
P3
P4
P5
P6
P7
P8
""

N
N
N
N
N
N

AUTOSIM 2.0
0.400
0.450
0.500
0.000
0.300
0.400

0.300
0.200
0.210
0.000
0.000
0.000

0.000
0.000
0.000
0.000
0.000
0.000

0.400
0.450
0.500
0.000
0.300
0.400

0.300
0.200
0.210
0.000
0.000
0.000

0.000
0.000
0.000
0.000
0.000
0.000

? (write-to-file print-default-positions "temp")


file "temp" created with PRINT-DEFAULT-POSITIONS

See Also
set-defaults, write-to-file, Section 5.9

print-forces
Print summaries of all working forces in system.
Usage
print-forces {stream}
Description
Print-forces prints a summary of each force defined in the AUTOSIM input. The
optional argument stream supports the command write-to-file.
Example
Consider the four-bar linkage system.
? (print-forces)
FORCES
======
FSTRUT: Strut force; Acts on B from the inertial reference through BP7
and pin between strut and N. Magnitude = -FM(1); Direction =
(z(56)*[ny] -z(54)*[bx] -z(53)*[by] + z(55)*[nx]).
FSPIN: Acts on C from the inertial reference through CP5.
FM(2); Direction = [ny].
NIL
? (write-to-file print-forces "temp")
file "temp" created with PRINT-FORCES
NIL

See also
write-to-file, Section 5.9

print-kane
Print all Kane dynamics terms for one body.
Usage
print-kane body {stream}
8 51

Magnitude =

8.1 Commands

AUTOSIM 2.0

Description
Print-kane prints a summary of dynamics expressions associated with body. These
might be of interest to some dynamicists who are interested in the inner workings of
AUTOSIM. The terms are defined in a journal article, Symbolic Vector/Dyadic
Multibody Formalism for Tree-Topology Systems. Journal of Guidance, Control, and
Dynamics, Vol. 14, No. 6, Nov/Dec 1991, 1240-1250, by M.W. Sayers.
Example
Consider the four-bar linkage system.
? (print-kane c)
DYNAMICS TERMS FOR BODY C
=========================
recursive-r: ROTOR
recursive-t: T
w-a: U(1)*[nz]
w-ab: -Z(31)*U(1)*[nz]
w: Z(120)*[nz]
wis-a array: [nz], 0, 0
nhwis array: (1.0 -Z(31))*[nz]
nh-alpha-rem: -Z(118)*[nz]
ra*b0: PC(1)*[bx] -PC(2)*[by]
v*is-a array: 0, 0, 0
v*is bodies: C, N, C
nhv*is array: (Z(128)*[cx] + Z(130)*[cy])
nhv*is bodies: C
nh-acc-rem: PC(3)*Z(118)*[cy] + PC(4)*Z(118)*[cx] + Z(146)*[cx]
:
-Z(142)*[cy]
NIL

See also
write-to-file, Section 5.9

print-kanes
Print all Kane dynamics terms for the system.
Usage
print-kanes {stream}
Description
Print-kanes prints a summary of dynamics expressions associated with each body,
using the print-kane command. The optional argument stream supports the
command write-to-file.
See also
print-kane, write-to-file, Section 5.9

8 52

8.1 Commands

AUTOSIM 2.0

print-moments
Print summaries of all working moments (torques) in system.
Usage
print-moments {stream}
Description
Print-moments prints a summary of each moment you have introduced. The optional
argument stream supports the command write-to-file.
See Also
write-to-file, Section 5.9

print-outputs
Print summaries of all output variables.
Usage
print-outputs {stream}
Description
Print-outputs prints a summary of each output variable that you have introduced
with commands such as add-out or add-standard-outputs. The optional
argument stream supports the command write-to-file.
Example
Consider the four-bar linkage system.
? (print-outputs)
OUTPUT VARIABLES
================
Fspindle: Force (N), spindle force, Body input, exp=FM(2)
F strut: Force (N), strut force, Body strut, exp=-FM(1)
X5: Translation (m), X coordinate of pt 5, Body C, exp=Z(192)
Y5: Translation (m), Y coordinate of pt 5, Body C, exp=Z(195)
angle A: Angle (rad), abs. angle of A, Body A, exp=Q(1)
angle B: Angle (rad), abs. angle of B, Body B, exp=Q(3)
angle C: Angle (rad), abs. angle of C, Body C, exp=Z(196)
NIL
? (write-to-file print-outputs "temp")
file "temp" created with PRINT-OUTPUTS

See Also
add-out, add-standard-output, write-to-file, Section 5.9

print-parameters
Print summaries of all significant parameters in system.

8 53

8.1 Commands

AUTOSIM 2.0

Usage
print-parameters {stream}
Description
Print-parameters prints a description for each parameter that appears in the
simulation code. It shows the symbol, name, default value, and units for each parameter.
This command should not be used until after the finish command has been applied,
because the equations cannot be inspected until the analysis is complete.
The display of point names and symbols is affected by the global variable *printaliases*. When this variable is not NIL, all names associated with each point are
printed.
The optional argument stream supports the command write-to-file.
Example
Consider the four-bar linkage example:
? (print-parameters)
PARAMETERS
==========
D:
IC:
K:
:
MC:
XP1:
XP2:
XP3:
XP4:
XP5:
XP6:
XP7:
XP8:
YP1:
YP2:
YP3:
YP4:
YP5:
YP6:
YP7:
YP8:
NIL

coefficient in term in negative strut force (500 ?)


moment of inertia of C (1 kg-m2)
stiffness coefficient in term in negative strut force
(60000 N/m)
mass of C (10 kg)
X coordinate of pin between A and N (0.1 m)
X coordinate of pin between strut and N (0.3 m)
X coordinate of pin between A and C (0.4 m)
X coordinate of mass center of C (0.45 m)
X coordinate of point of force application (0.5 m)
X coordinate of pin between B and N (0 m)
X coordinate of pin between strut and B (0.3 m)
X coordinate of pin between B and C (0.4 m)
Y coordinate of pin between A and N (0.3 m)
Y coordinate of pin between strut and N (0.5 m)
Y coordinate of pin between A and C (0.3 m)
Y coordinate of mass center of C (0.2 m)
Y coordinate of point of force application (0.21 m)
Y coordinate of pin between B and N (0 m)
Y coordinate of pin between strut and B (0 m)
Y coordinate of pin between B and C (0 m)

? (write-to-file print-parameters "temp")


file "temp" created with PRINT-PARAMETERS

See Also
*print-aliases*, finish, write-to-file, Section 5.9

print-points
Print summaries of all points in system.

8 54

8.1 Commands

AUTOSIM 2.0

Usage
print-points {stream}
Description
Print-points prints a summary of each point introduced by AUTOSIM or by the
analyst. The display of point names and symbols is affected by the global variable
*print-aliases*. When this variable is not NIL, all names associated with each
point are printed. The optional argument stream supports the command write-tofile.
Examples
Consider the four-bar linkage example:
? (print-points)
POINTS
======
(Point
(Point
(Point
(Point
(Point
(Point
(Point
(Point
(Point
(Point
(Point
(Point
(Point
(Point
(Point
(Point
(Point
(Point
(Point

P8: Body N: (XP8 YP8 0): pin between B and C)


P7: Body N: (XP7 YP7 0): pin between strut and B)
P6: Body N: (XP6 YP6 0): pin between B and N)
P5: Body N: (XP5 YP5 0): point of force application)
P4: Body N: (XP4 YP4 0): mass center of C)
P3: Body N: (XP3 YP3 0): pin between A and C)
P2: Body N: (XP2 YP2 0): pin between strut and N)
P1: Body N: (XP1 YP1 0): pin between A and N)
O: Body N: (0 0 0): fixed origin)
CP5: Body C: (-PC(13) PC(14) 0): CP5)
CP3: Body C: (-PC(7) PC(8) 0): CP3)
CJ: Body B: (PC(1) -PC(2) 0): attachment point for C)
CCMC: Body C: (-PC(3) PC(4) 0): mass center of composite body C)
CCM: Body C: (-PC(3) PC(4) 0): mass center of C)
C0: Body C: (0 0 0): coord. origin of C)
BP7: Body B: (-PC(9) -PC(10) 0): BP7)
B0: Body B: (0 0 0): coord. origin of B)
AP3: Body A: (-PC(5) PC(6) 0): AP3)
A0: Body A: (0 0 0): coord. origin of A)

? (write-to-file print-points "temp")


file "temp" created with PRINT-POINTS

See Also
*print-aliases*, write-to-file, Section 5.9

print-rf
Print all reaction force and moment terms for one body.
Usage
print-rf body {stream}
Description
Print-rf prints a summary of reaction force and moment expressions associated with
body. These might be of interest to some dynamicists who are interested in the inner

8 55

8.1 Commands

AUTOSIM 2.0

workings of AUTOSIM. The terms are derived only if your input includes references to
the functions r f v e c t or rmvect, or if you explicitly invoke the commands
reaction-forces or reaction-moments.
Example
Consider the spacecraft example from the Introductory Guide to AUTOSIM. View the RF
data for body C:
? (print-rf c)
SLOTS IN RF:C
=============
parent:
children:
sumf:
ma:
:
fc:
:
:
:
summ:
mcrem:
mc:
:
:

rf:B
rf:D
0
MC*(UP(1)*C(4) + UP(2)*S(4))*[cx] + MC*(UP(2)*C(4)
-UP(1)*S(4))*[cy] + MC*UP(3)*[bz]
(MC*(UP(1)*C(4) + UP(2)*S(4)) + MD*(UP(1)*C(4)
+ UP(2)*S(4)-L3*Z(401)))*[cx] + (MC*(UP(2)*C(4)
-UP(1)*S(4)) -Z(408)*C(5)+ Z(415)*S(5))*[cy] +
-(-MC*UP(3) + Z(416) + Z(417))*[bz]
-(FORCEM(2)*[cx] -FORCEM(1)*[bz])
Z(90)*[bx] + Z(87)*[by] + IC*UP(3)*[bx] + IC*UP(4)*[by]
-(-Z(449)*[bx] + Z(447)*[cx] + Z(435)*[dz] -Z(444)*[by] +
Z(428)*[dy] + (L3*MD*(UP(1)*C(4) + UP(2)*S(4)
-L3*Z(401)) +FORCEM(1))*[bz])

See also
reaction-forces, reaction-moments, rfvect, rmvect, write-to-file,
Section 5.5

print-rfs
Print all reaction force and moment terms for the system.
Usage
print-rfs {stream}
Description
Print-rfs prints a summary of reaction force and moment expressions associated with
each body, using the print-rf command. The optional argument stream supports the
command write-to-file.
See also
print-rf, write-to-file, Sections 5.5, 5.9

print-speeds
Print names and definitions of independent generalized speeds.

8 56

8.1 Commands

AUTOSIM 2.0

Usage
print-speeds {stream}
Description
Print-speeds prints the names and definitions of the independent speeds introduced
by AUTOSIM. The optional argument stream supports the command write-tofile.
See Also
write-to-file, Section 5.9

print-symbols
Print summaries of all AUTOSIM symbols.
Usage
print-symbols {stream}
Description
Print-symbols is a debugging command that prints a summary of every symbol
appearing in your input or introduced by AUTOSIM. The optional argument stream
supports the command write-to-file.
Examples
Consider the four-bar linkage example (this print-out is abbreviated):
? (print-symbols)
C
C

SYMBOLS RECOGNIZED BY AUTOSIM


=============================
NSPEED: NIL
NCOORD: NIL
=: NIL
B: NIL
CP5: NIL
FSTRUT: NIL
FSPIN: NIL
IFILE: NIL
JTABLE(NTABS): NIL
NPTS(NTABS): NIL
NTABS: NIL
...
Q(1): Abs. Z rot. of A (rad)
D: coefficient in term in negative strut force
K: stiffness coefficient in term in negative strut force (N/m)
IC: moment of inertia of C (kg-m2)
MC: mass of C (kg)
YP8: Y coordinate of pin between B and C (m)
XP8: X coordinate of pin between B and C (m)
...
L: NIL
F: NIL
G: gravitational constant (m/s2)
DR: conversion: radians to degrees

8 57

8.1 Commands

AUTOSIM 2.0

STEP: simulation time step (s)


STARTT: simulation start time (s)
STOPT: simulation stop time (s)
IPRINT: number of time steps between output printing (counts)
NIL
?
? (write-to-file print-symbols "temp")
file "temp" created with PRINT-SYMBOLS
NIL

See Also
write-to-file, Section 5.9

reaction-forces
Derive reaction force vectors for part of the multibody system.
Usage
reaction-forces {body}
Description
Reaction forces are derived for all bodies in the system if the argument B is not provided.
If it is, the analysis starts with body B and continues for all children and descendants of B
in the topology. A reaction force for a body is the force vector remaining after subtracting
the effects of acceleration and all active forces. By its nature, it is not associated with a
particular point. Unless constraints have been added, the reaction force acts on body B
from its parent. The reaction force vector should be zero in the direction of any
translational DOF of body B. After the reaction-forces analysis, individual vectors
are accessed with the rfvect function.
This command is applied automatically by the rfvect and rmvect function. The
main reason for including this command in your AUTOSIM input file is to make it more
obvious that the reaction force analysis is being done.
The reaction force analysis requires that a dynamics analysis be performed first. If
this is not the case, the dynamics command is automatically applied.

reaction-moment
Derive reaction moment vectors for part of the multibody system.
Usage
reaction-moment {body}
Description
Reaction moments are derived for all bodies in the system if the argument B is not
provided. If it is, the analysis starts with body B and continues for all children and
descendants of B in the topology. A reaction moment for a body is the moment about its
origin remaining after subtracting the effects of acceleration, all active forces, and all
active moments. If there were no constraints added, the reaction moment of body B is
8 58

8.1 Commands

AUTOSIM 2.0

applied to B by its parent. The reaction moment vector should be zero in the direction of
any rotational DOF of body B. After the reaction-moments analysis, individual
vectors are accessed with the rmvect function.
This command is applied automatically by the rmvect function. The main reason for
including this command in your AUTOSIM input file is to make it more obvious that the
reaction moment analysis is being done.
The reaction moment analysis requires that a dynamics analysis be performed first. If
this is not the case, the dynamics command is automatically applied. It also requires
the reaction force analysis. If it has not been done, the reaction-force command is
automatically applied.

reset
Reset AUTOSIM data structures and erase all remnants of multibody system.
Usage
reset
Description
This command sets various global variables used by AUTOSIM to store equations to
their default values. The practical effect is that results of any analyses involving a
multibody system are lost. After reset, the entire system consists of one body, N,
containing one point, O.
Not all global variables are modified. For example, globals such as *q-symbol*,
*qp-symbol*, and others used to determine the appearance of the equations generated
by AUTOSIM are not affected. If these variables are changed, it is usually a good idea to
immediately invoke reset so the new values are correctly applied in the initializations.
You should be aware that if any AUTOSIM data were assigned to external variables
using the setsym command, then it is possible that much of the computer memory used
to represent the multibody system will remain in use. (The reason is that pointers to
AUTOSIM objects remain active.) If memory seems to be running tight and reset has
been used more than once, the two possible solutions are (1) to set all variables to NIL
that were used in setsym commands (other than AUTOSIM globals), or (2) quit
AUTOSIM and re-start.
See Also
Section 5.3

rtf
Print information in rich text format.
Usage
rtf {form}*

8 59

8.1 Commands

AUTOSIM 2.0

Description
This command temporarily sets the global variable *target-language* to RTF. If
form prints anything, the output is in the RTF format. The output should be saved into a
text file. When that file is opened in a word processor that understands RTF (e.g.,
Microsoft Word, Word Perfect), it is formatted.
In order for the text to be fully formatted, a header should be inserted at the start. An
appropriate header is provided in the file rtf header.
Example
One example of rtf is shown under the command print-body. As a second example,
the parameters for the pitch-plane vehicle example are obtained below in the RTF
context.
? (rtf (print-parameters))
\pard\plain \s254\qj\sb480\keepn \b\f20\fs28 Parameters\par
\pard\plain \qj\sl280 \f20
\pard\plain \qj\sl280 \f20 {\i C}{\fs20\dn4 F}
\tab damping coefficient in front damper force (1000 N-s/m)\par
...
{\i W}{\fs20\dn4 R}
\tab term in (scaled) mass of S (600 kg)\par
NIL

The above response shows a portion of the raw RTF printout. After saving the above
RTF and inserting text from the file rtf header, the text file is loaded into Microsoft
Word, where it appears as follows:
Parameters
damping coefficient in front damper force (1000 N-s/m)
CF
damping coefficient in rear damper force (1000 N-s/m)
CR
IYY (scaled) moment of inertia of S (2000 kg-m2)
stiffness coefficient in term in negative front spring force (26000 N/m)
KF
stiffness coefficient in term in rear spring force (26000 N/m)
KR
KTF stiffness coefficient in term in negative front tire force (180000 N/m)
KTR stiffness coefficient in term in negative rear tire force (180000 N/m)
L
negative X coordinate of attachment point for the rear wheel (2.6 m)
MAF (scaled) mass of AF (120 kg)
MAR (scaled) mass of AR (90 kg)
V
Abs. X trans. speed of SCMC (30 m/s)
term in (scaled) mass of S (800 kg)
WF
term in (scaled) mass of S (600 kg)
WR
See Also
*target-language*, Sections 1.8, 5.11

8 60

8.1 Commands

AUTOSIM 2.0

set-defaults
Assign default numerical values to parameters.
Usage
set-defaults {parameter value}*
Description
All parameters in the simulation code generated by AUTOSIM have default values. If the
analyst provides no information, all default values are normally 1.0. However, if
*target-language* is set to the symbol adsim, then the default values are 0 unless
specified explicitly. All state variables have default initial values of 0. Set-defaults
is used to assign different values to parameters and initial conditions. The numerical
values assigned here are used in the simulation code only if the end user does not provide
values as inputs.
Set-defaults is also used to specify the numerical values of universal constants
associated with the units system.
Example
(set-defaults xp1 .1 yp1 .3 xp2 .3 yp2 .5 xp3 .4 yp3 .3
xp4 .45 yp4 .2 xp5 .5 yp5 .21 xp6 0 yp6 0
xp7 .3 yp7 0 xp8 .4 yp8 0 mc 10 ic 1
k 60000 d 500 iprint 1 step .01 stopt 1)

See Also
print-parameters, Section 5.10

set-derivs
Assign derivatives to variables.
Usage
set-derivs {symbol derivative}*
Description
Use the command set-derivs to assign the correct derivatives to variables introduced
with the add-variables command. If one of these variables appears in a constraint
equation (from add-position-constraint, add-speed-constraint,
motion, or no-movement), AUTOSIM may need its derivative. Also, you might want
to apply dxdt or partial to an expression containing a new variable, in which case the
correct derivative is needed.
If a variable introduced in add-variables is not used in a constraint equation or a
derivative function, then its derivative is not needed.
Example
Suppose we want to use the symbols TAUPF and PHIF in constraint equations, and that
their derivatives are represented by the symbols DTAUPF and DHIPF.
(add-variables dyvars real taupf dtaupf phif phipf)

8 61

8.1 Commands

AUTOSIM 2.0

(set-derivs taupf dtaupf phif phipf)

See Also
add-variables, Section 6.6

set-names
Assign names to symbols.
Usage
set-names expression name {level}
Description
All parameters and variables in the simulation code generated by AUTOSIM have names,
used to generate comments and labels in source code. However, the names generated
automatically by AUTOSIM may not be as meaningful to the end user as names that the
analyst might have in mind. This command is used to override the name of parameters
and variables that appear in documentation and output files of the simulation code.
If expression is a symbol, name is assigned to it with priority over any existing
names. If expression is a more complicated expression, set-names is applied
recursively to all components of the expression.
A symbol actually has a list of associated strings, maintained in a special data
structure called a name. The optional argument level indicates the level of priority
associated with each string. Initially, level has its default value of 0. For each level of
recursion, level is incremented by 1. The new string, name, is added to the list of names.
When printed, the list is searched for the lowest level, and the associated string is used.
Example
? (set-names r "radius of crank")
"radius of crank"
? (set-names !"hi + by" "silly expression")
"silly expression"
? (get-name 'hi)
"term in silly expression"

See Also
get-name, name, print-parameters, Section 5.10

setsym
Assign values to external symbols.
Usage
setsym {symbol value}*
Description
AUTOSIM includes numerous global variables whose values define alternate analysis
options. Also, you may wish to assign expressions derived by AUTOSIM to external
8 62

8.1 Commands

AUTOSIM 2.0

variables for later use. Each argument symbol must be a symbol. The corresponding value
argument can be a string, symbol, number, or list. If symbol is an AUTOSIM global, the
type of data expected is checked with the type provided. For example, if symbol is
*multibody-system-name*, then setsym expects a string as the value. Any other
type of data causes an error message.
If symbol is not an AUTOSIM global, then a string provided as a value is parsed as an
f-string.
Examples
Consider the command
(setsym *degree* deg
*double-precision* nil
*multibody-system-name* "an example string"
*unit-vector-brackets* "[]"
*unit-vector-indices* "XYZ"
x "a-a*sin(x)")

The first five assignments are to AUTOSIM globals and the last is to an external symbol
x. The setsym command has installed the information that *multibody-systemname* should be assigned a plain string, but that x should be assigned an expression
obtained by parsing a string. The following interactive session shows the error checking
in setsym.
? (setsym *degree* "x*y")
Error in setsym: *DEGREE* is supposed to be a SYMBOL, not the
(SIMPLE-STRING 3) "x*y".
Aborted
? (setsym *unit-vector-brackets* [])
Error in setsym: *UNIT-VECTOR-BRACKETS* is supposed to be a STRING, not
the SYMBOL [].
Aborted
?

See Also
Section 5.3

set-units
Assign units to symbols in an expression.
Usage
set-units expression units {:override override}
Description
All parameters and variables in the simulation code generated by AUTOSIM have units.
However, there is not always enough information to deduce the units of some parameters
and external variables. This command is used to override units of parameters and
variables that appear in documentation and output files of the simulation code.

8 63

8.1 Commands

AUTOSIM 2.0

If expression is a symbol that already has units, the command has no effect unless
override is given a non-NIL value. If expression is a symbol that does not yet have
associated units, or if override has a non-NIL value, than the units of expression are set to
the expression units. The argument units should be an expression involving basic units
symbols such as L (length), F (force), A (angle), and T (time). (The actual symbols are
defined by the global variables *length*, *force*, *time*, *angle*, and
*counts*.) If expression is a more complicated expression, set-units is applied
recursively to all components of the expression.
The units for an expression can be obtained with the get-units and units
functions. The units of all model parameters are printed (along with names) with the
print-parameters command.
Example
Suppose a parameter K1 is a torsional spring rate. Because angles are actually
dimensionless (radian=arc length/radius), AUTOSIM often derives units that do not treat
angular units in the way that the end user might expect. Therefore, it is a good idea to set
the units of any parameters involving angles, such as torsional spring rate:
(set-units k1 "L*f/a")

See Also
*length*, *force*, *time*, * a n g l e * , *counts*, get-units, units,
print-parameters, Section 5.10

si
Set the units system to SI.
Usage
si
Description
This command establishes the units for the multibody system as SI (all units are derived
from L=meters, F=Newtons, and T=seconds). Angles are in radians. The gravitational
constant is G=9.86 m/sec2. The units system is summarized in Table 8.1.21.
See Also
mks, si, Section 5.10

8 64

8.1 Commands

AUTOSIM 2.0

Table 8.1.21. Summary of SI units system.


Units Expression
Name
Generic Name
L
m
Translation
A
rad
Angle
T
s
Time
F
N
Force
C
counts
Counts
L/T
m/s
Speed
L/T**2
m/s2
Acceleration
A/T
rad/s
Angular Speed
A/T**2
rad/s2
Angular Acceleration
F*L
N-m
Moment
F*T**2/L
kg
Mass
F*L*T**2
kg-m2
Inertia

Gain
1
1
1
1
1
1
1
1
1
1
1
1

small
Declare that one or more parameters are small.
Usage
small {symbol}*
Description
This command is used to declare that one or more symbols are small. This is commonly
applied to speeds that are small, but whose corresponding coordinates are not small.
See Also
*small-order*, large, Section 5.10

status-report
Write temporary message on screen indicating current activity.
Usage
status-report format-string {arg}*
Description
This command is only of interest if you are writing new AUTOSIM commands or
functions in Lisp. The command reports current AUTOSIM activities. The argument
format-string has the same meaning as a control string in a Lisp format form. The
optional arguments are printed according to format-string.
It is a good idea to use status-report at the start of any activity that takes more
than a tenth of a second to run, to keep the modeler informed of the progress.
8 65

8.1 Commands

AUTOSIM 2.0

Example
(status-report "adding tire ~a" id)

write-acsl
Generate complete simulation code in the ACSL language.
Usage
write-acsl {stream}
Description
This command causes AUTOSIM to generate a complete, ready-to-run simulation
program for use in ACSL (Advanced Continuous Simulation Language), from Mitchell
and Gauthier Associates (MGA), Inc., Concord, Massachusetts. The ACSL portion of the
program declares arrays and labeled COMMON blocks, and assigns default values to
model parameters. The design of the ACSL code is described in Chapter 3. The optional
argument stream supports the command write-to-file.
This command will apply the finish command if it has not yet been applied.
Example
(write-to-file write-acsl "sim.acsl")

See Also
finish, write-to-file, Sections 3.2, 5.11

write-adsim
Generate complete simulation code in the ADSIM language.
Usage
write-adsim {stream}
Description
This command causes AUTOSIM to generate a complete, ready-to-run simulation
program in native ADSIM for use on AD100 computers from Applied Dynamics
International, of Ann Arbor, Michigan. The design of the ADSIM code is described in
Chapter 3. The optional argument stream supports the command write-to-file.
This command will apply the finish command if it has not yet been applied.
Example
(write-to-file write-adsim "sim.adsim")

See Also
finish, write-to-file, Sections 3.3, 5.11

8 66

8.1 Commands

AUTOSIM 2.0

write-c
Generate a set of functions in the C language.
Usage
write-c {stream}
Description
This command causes AUTOSIM to generate a set of ready-to-run C functions with the
code needed to simulate the system model. The design of the C code is described in
Section 2.5. The optional argument stream supports the command write-to-file.
This command will apply the finish command if it has not yet been applied.
Example
(write-to-file write-c "sim.c")

See Also
finish, write-to-file, Sections 2.5, 5.11

write-difeqn
Generate routine DIFEQN with equations of motion.
Usage
write-difeqn {stream}
Description
This command writes the routine DIFEQN in the current target language. If you use the
commands write-sim, write-sim-minimal, or write-acsl, a subroutine is
written automatically in Fortran and you do not need to use this command directly. If you
use the command write-c, the routine is written as a C function, and again, you do not
need to use this command directly. The optional argument stream supports the command
write-to-file.
This command will apply the finish command if it has not yet been applied.
See Also
*target-language*, finish, write-acsl, write-c, write-sim, writesim-minimal, write-to-file, Sections 2.2, 2.5, 3.2, 5.11

write-dolud
Generate Fortran subroutine DOLUD to check for changes in mass matrix.
Usage
write-dolud {stream}

8 67

8.1 Commands

AUTOSIM 2.0

Description
This command writes the Fortran subroutine DOLUD, described in Section 2.2. If you
use the commands write-sim or write-sim-minimal, the subroutine is written
automatically and you do not need to use this command. The DOLUD subroutine is
needed only if the d y n a m i c s command is included in your input, with the
:conditional-lud argument set to T. The optional argument stream supports the
command write-to-file.
See Also
dynamics, write-sim, write-sim-minimal, write-to-file, Sections 2.3,
5.11

write-echo
Generate Fortran subroutine ECHO to write parameter values into file.
Usage
write-echo {stream}
Description
This command writes the Fortran subroutine ECHO, described in Section 2.2. If you use
the commands write-sim or write-sim-minimal, the subroutine is written
automatically and you do not need to use this command. The optional argument stream
supports the command write-to-file.
This command will apply the finish command if it has not yet been applied.
See Also
finish, write-sim, write-sim-minimal, write-to-file, Sections 2.3, 5.11

write-eqs
Generate RTF file with formatted equations.
Usage
write-eqs {stream}
Description
This command writes definitions, parameter values, and equations of motion in the RTF
language. If the output is saved as a text file, that file can be read into the Microsoft
Word word processor, where the contents appear with full formatting. (For example,
parameters and variables are shown in italics with subscripts.) The optional argument
stream supports the command write-to-file.
See Also
write-to-file, Section 5.11

8 68

8.1 Commands

AUTOSIM 2.0

write-eqs-doc
Generate documentation about multibody system.
Usage
write-eqs-doc {stream {comment}}
Description
This command writes definitions of state variables, bodies, and forces for the multibody
system. The optional argument stream supports the command write-to-file. If the
optional argument comment is T, the information is written in the form of comments in
the target language as specified by the global variable *target-language*. This
documentation is produced automatically by the commands write-acsl, writeadsim, and write-matlab.
See Also
*target-language*, write-acsl, write-adsim, write-matlab, writeto-file, Section 5.11

write-fct
Generate routine FCT to compute derivatives of the state variables.
Usage
write-fct {stream}
Description
This command writes the routine FCT in the current target language. If you use the
commands write-sim, write-sim-minimal, or write-acsl, a subroutine is
written automatically in Fortran and you do not need to use this command directly. If you
use the command write-c, the routine is written as a C function, and again, you do not
need to use this command directly. The optional argument stream supports the command
write-to-file.
FCT calls the routine DIFEQN, which computes the derivatives of the state variables.
See Also
*target-language*, finish, write-acsl, write-c, write-sim, writesim-minimal, write-to-file, Sections 2.3, 2.5, 3.2, 5.11

write-fct2
Generate Fortran subroutine for solving equilibrium equations.
Usage
write-fct {stream}

8 69

8.1 Commands

AUTOSIM 2.0

Description
This command writes the Fortran subroutine FCT for an equilibrium simulation program,
as described in Section 2.2. It uses the Newton-Raphson method to solve for an
equilibrium condition, based on the equations of motion. If you use the commands
write-sim or write-sim-minimal, the subroutine is written automatically and you
do not need to use this command. The optional argument stream supports the command
write-to-file.
See Also
write-sim, write-sim-minimal, write-to-file, Sections 2.3, 5.11

write-finish
Generate Fortran interface subroutine FCT.
Usage
write-fct {stream}
Description
This command writes the Fortran subroutine FINISH for a simulation program, as
described in Section 2.2. If you use the commands write-sim or write-simminimal, the subroutine is written automatically and you do not need to use this
command. The optional argument stream supports the command write-to-file.
This command will apply the finish command if it has not yet been applied.
See Also
finish, write-acsl, write-sim, write-sim-minimal, write-to-file,
Sections 2.3, 5.11

write-fortran-doc
Generate Fortran programming documentation for the simulation code.
Usage
write-fortran-doc {stream {minimal}}
Description
This command writes comments applicable to the structure of the Fortran simulation code
generated with the command write-sim. The documentation defines all of the bodies,
state variables, forces, moments, and subroutine modules. The optional argument stream
supports the command write-to-file. The optional argument minimal causes
documentation to be suppressed for library files when a value of T is provided.
See Also
write-sim, write-to-file, Section 5.11

8 70

8.1 Commands

AUTOSIM 2.0

write-help
Generate summary of on-line help for all AUTOSIM commands.
Usage
write-help {stream}
Description
This command writes the on-line documentation for all AUTOSIM commands, using the
? command. The optional argument stream supports the command write-to-file.
When printed, this information is about 35 pages in length.
See Also
?, write-to-file

write-help-globals
Generate summary of on-line help for all AUTOSIM global variables.
Usage
write-help {stream}
Description
This command writes all of the on-line documentation for AUTOSIM global variables
that you can safely change. The documentation is the same as obtained with the ?
command. The optional argument stream supports the command write-to-file.
See Also
?, write-to-file

write-init
Generate Fortran subroutine INIT to initialize variables.
Usage
write-init {stream}
Description
This command writes the Fortran subroutine INIT, described in Section 2.2. If you use
the commands write-sim, write-sim-minimal, or write-acsl, the subroutine
is written automatically and you do not need to use this command. The optional argument
stream supports the command write-to-file.
This command will apply the finish command if it has not yet been applied.
See Also
finish, write-acsl, write-sim, write-sim-minimal, write-to-file,
Sections 2.3, 5.11

8 71

8.1 Commands

AUTOSIM 2.0

write-initnr
Generate routine INITNR to compute coefficients needed for initialization.
Usage
write-initnr {stream}
Description
This command writes the routine INITNR in the current target language. If you use the
commands write-sim, write-sim-minimal, or write-acsl, a subroutine is
written automatically in Fortran and you do not need to use this command directly. If you
use the command write-c, the routine is written as a C function, and again, you do not
need to use this command directly. The optional argument stream supports the command
write-to-file.
The subroutine INITNR is needed only if you used the commands motion, nomovement, or add-position-constraint.
This command will apply the finish command if it has not yet been applied.
See Also
*target-language*, add-position-constraint, finish, motion, nomovement, write-acsl, write-sim, write-sim-minimal, write-to-file,
Sections 2.2, 2.3, 2.5, 3.2, 5.11

write-input
Generate Fortran subroutine INPUT to read values for parameters and initial conditions.
Usage
write-input {stream}
Description
This command writes the Fortran subroutine INPUT, described in Section 2.2. If you use
the commands write-sim or write-sim-minimal, the subroutine is written
automatically and you do not need to use this command. The optional argument stream
supports the command write-to-file.
This command will apply the finish command if it has not yet been applied.
See Also
finish, write-sim, write-sim-minimal, write-to-file, Sections 2.3, 5.11

write-inteqs
Generate Fortran subroutine INTEQS to integrate ordinary differential equations.
Usage
write-inteqs {stream}

8 72

8.1 Commands

AUTOSIM 2.0

Description
This command writes the Fortran subroutine INTEQS, described in Section 2.2. If you
use the commands write-sim or write-sim-minimal, the subroutine is written
automatically and you do not need to use this command. The optional argument stream
supports the command write-to-file.
This command will apply the finish command if it has not yet been applied.
AUTOSIM can generate a simple fixed-step integration subroutine or a more
sophisticated routine with options for stiff and non-stiff equations. The choice is
determined by the value of the global variable *stiff-integrator* at the time the
finish command is applied.
See Also
*stiff-integrator*, finish, write-sim, write-sim-minimal, writeto-file, Sections 2.3, 5.11

write-main
Generate main (calling program) for Fortran simulation code.
Usage
write-main {stream}
Description
This command writes the main Fortran program, described in Section 2.2. If you use the
commands w r i t e - s i m or write-sim-minimal, the program is written
automatically and you do not need to use this command. The optional argument stream
supports the command write-to-file.
This command will apply the finish command if it has not yet been applied.
See Also
finish, write-sim, write-sim-minimal, write-to-file, Sections 2.3, 5.11

write-matlab
Generate complete analysis code in the MatLab language.
Usage
write-matlab {stream}
Description
This command writes a complete input file for MATLAB, described in Chapter 4. It is
first necessary to execute the linear command. (If the linear analysis has not been
performed, the write-matlab command runs it if possible. If another analysis has
been performed, an error message is generated.)

8 73

8.1 Commands

AUTOSIM 2.0

The MATLAB file contains code to assign values to the parameters in the multibody
system and then compute the linear A, B, C, and D matrices, which are called MatrixA,
MatrixB, MatrixC, and MatrixD. After executing the file, properties of the system
can be obtained using MATLAB commands.
The optional argument stream supports the command write-to-file.
See Also
linear, write-to-file, Sections 4.2, 5.11

write-newtr1
Generate Fortran subroutine to apply Newton-Raphson method to find initial conditions.
Usage
write-newtr1 {stream}
Description
This command writes the Fortran subroutine NEWTR1, described in Section 2.2. If you
use the commands write-sim, write-sim-minimal, or write-acsl, the
subroutine is written automatically and you do not need to use this command. The
subroutine NEWTR1 is needed only if you used the commands motion, nom o v e m e n t , or add-position-constraint. The optional argument stream
supports the command write-to-file.
See Also
add-position-constraint, finish, motion, no-movement, write-acsl,
write-sim, write-sim-minimal, write-to-file, Sections 2.3, 5.11

write-opnout
Generate Fortran subroutine OPNOUT to create output file and write labels.
Usage
write-opnout {stream}
Description
This command writes the Fortran subroutine OPNOUT, described in Section 2.2. If you
use the commands write-sim or write-sim-minimal, the subroutine is written
automatically and you do not need to use this command. The optional argument stream
supports the command write-to-file.
See Also
write-sim, write-sim-minimal, write-to-file, Sections 2.3, 5.11

8 74

8.1 Commands

AUTOSIM 2.0

write-output
Generate Fortran subroutine OUTPUT to write output variables every time step.
Usage
write-output {stream}
Description
This command writes the subroutine OUTPUT, which is called periodically during the
simulation to write current values of all of the output variables into a file. If you use the
commands write-sim or write-sim-minimal, the subroutine is written
automatically and you do not need to use this command. The optional argument stream
supports the command write-to-file.
This command will apply the finish command if it has not yet been applied.
See Also
finish, write-sim, write-sim-minimal, write-to-file, Sections 2.3, 5.11

write-pederv
Generate Fortran subroutines PDRV1 and PEDERV to support the stiff integrator routine.
Usage
write-pederv {stream}
Description
This command writes the Fortran subroutines PDRV1 and PEDERV, needed to support
the stiff integrator in INTEQS. If you use the commands write-sim or write-simminimal, these subroutines are written automatically and you do not need to use this
command. The optional argument stream supports the command write-to-file.
This command will apply the finish command if it has not yet been applied.
AUTOSIM can generate a simple fixed-step integration subroutine or a more
sophisticated routine with options for stiff and non-stiff equations. The choice is
determined by the value of the global variable *stiff-integrator* at the time the
finish command is applied. If *stiff-integrator* is NIL, the simple integrator
is used, and subroutines PDRV1 and PEDERV are not needed.
When the more complex integration method is used, subroutine PDRV1 is called
every time step from UPDATE to compute Jacobian coefficients. Subroutine PEDERV is
used to access those coefficients. (PEDERV is called from within subroutine GEAR,
which is used by subroutine INTEQS.)
See Also
*stiff-integrator*, finish, write-sim, write-sim-minimal, writeto-file, Sections 2.3, 5.11

8 75

8.1 Commands

AUTOSIM 2.0

write-precmp
Generate routine PRECMP to pre-compute constants.
Usage
write-precmp {stream}
Description
This command writes the routine PRECMP in the current target language. If you use the
commands write-sim, write-sim-minimal, or write-acsl, a subroutine is
written automatically in Fortran and you do not need to use this command directly. If you
use the command write-c, the routine is written as a C function, and again, you do not
need to use this command directly. The optional argument stream supports the command
write-to-file.
This command will apply the finish command if it has not yet been applied.
See Also
*target-language*, finish, write-acsl, write-c, write-sim, writesim-minimal, write-to-file, Sections 2.3, 2.5, 3.2, 5.11

write-quasi
Generate Fortran subroutines QUASI and QUASI2 with equations for equilibrium
simulations.
Usage
write-quasi {stream}
Description
This command writes the Fortran subroutines QUASI and QUASI2, described in Section
2.2. If you use the commands write-sim or write-sim-minimal, the subroutine is
written automatically and you do not need to use this command. Subroutines QUASI and
QUASI2 are not needed unless the equilibrium command was included in the
AUTOSIM input. The optional argument stream supports the command write-tofile.
This command will apply the finish command if it has not yet been applied.
See Also
equilibrium, finish, write-sim, write-sim-minimal, write-to-file,
Sections 2.3, 5.11

write-setdef
Generate routine SETDEF that assigns default values.
Usage
write-setdef {stream}

8 76

8.1 Commands

AUTOSIM 2.0

Description
This command writes the routine SETDEF in the current target language. If you use the
commands write-sim, write-sim-minimal, or write-acsl, a subroutine is
written automatically in Fortran and you do not need to use this command directly. If you
use the command write-c, the routine is written as a C function, and again, you do not
need to use this command directly. The optional argument stream supports the command
write-to-file.
This command will apply the finish command if it has not yet been applied.
See Also
*target-language*, finish, write-acsl, write-c, write-sim, writesim-minimal, write-to-file, Sections 2.3, 2.5, 3.2, 5.11

write-sim
Generate complete Fortran simulation program.
Usage
write-sim {stream}
Description
This command writes the entire Fortran simulation program, except for routines that are
external to AUTOSIM. It calls all of the commands needed to write the necessary Fortran
subroutines, and also merges in all appropriate AUTOSIM library routines. If your input
description does not include any add-subroutine commands or references to external
Fortran functions, the program should be complete, and ready to compile and run.
The optional argument stream supports the command write-to-file.
This command will apply the finish command if it has not yet been applied.
The generated code includes comments throughout. Additional documentation,
describing the multibody system and listing all of the subroutines, is generated with the
command write-fortran-doc.
See Also
finish, write-fortran-doc, write-to-file, Sections 2.3, 5.11

write-sim-minimal
Generate custom-written parts of a Fortran simulation program.
Usage
write-sim-minimal {stream}
Description
This command writes all of the customized parts of a Fortran simulation program. It calls
all of the commands needed to write the necessary Fortran subroutines. However, it does

8 77

8.1 Commands

AUTOSIM 2.0

not merge in the AUTOSIM library routines. If you use this command to generate the
Fortran program, you will have to link to the AUTOSIM library functions.
The optional argument stream supports the command write-to-file.
This command will apply the finish command if it has not yet been applied.
The generated code includes comments throughout. Additional documentation,
describing the multibody system and listing all of the subroutines, is generated with the
command write-fortran-doc. The listing generated with write-fortran-doc
includes all of the library files that have to be linked to the custom code generated with
write-sim-minimal.
See Also
finish, write-fortran-doc, write-to-file, Sections 2.3, 5.11

write-to-file
Direct the output of an AUTOSIM write or print command to a file.
Usage
write-to-file command file-name
Description
Write-to-file directs the output of command to a file named file-name, which
should be a legitimate file name on the operating system of your computer. Any
command can be used as command if it has a single argument, stream. Most of the
printing and writing AUTOSIM commands can be used as arguments (see Tables 8.1.4
and 8.1.5).
Example
(write-to-file write-sim "sim.f")

See Also
Tables 8.1.4 and 8.1.5

write-update
Generate routine UPDATE.
Usage
write-update {stream}
Description
This command writes the routine UPDATE in the current target language. If you use the
commands write-sim, write-sim-minimal, or write-acsl, a subroutine is
written automatically in Fortran and you do not need to use this command directly. If you
use the command write-c, the routine is written as a C function, and again, you do not

8 78

8.1 Commands

AUTOSIM 2.0

need to use this command directly. The optional argument stream supports the command
write-to-file.
This command will apply the finish command if it has not yet been applied.
See Also
*target-language*, finish, write-acsl, write-c, write-sim, writesim-minimal, write-to-file, Sections 2.3, 2.5, 3.2, 5.11

8.2 Functions
You use functions in AUTOSIM mostly to define algebraic expressions involving a
multibody system model. All can be applied using Fortran-style syntax in an f-string.
The arithmetic operators (+, , /, *, **) are interpreted just as they are in Fortran.
Expressions of the form F(X) are interpreted one of three ways.
First, the symbol F may be recognized as an array, such that X is the index of F.
There are a little over a dozen arrays whose names are reserved by AUTOSIM.
(However, you can change those names if you like, by resetting the symbols assigned to
the globals described later and summarized in Table 8.3.3.) In addition, you can add
arrays with the commands add-variables and install-indexed-parameters.
If F(X) is not recognized as an array, it may correspond to a built-in AUTOSIM
function. Table 8.2.1 lists most of these functions. The AUTOSIM function may perform
symbolic operations on the arguments. For example, most will calculate a numerical
value if the argument is a number, but will generate a symbolic expression if the
argument is symbolic. You can add new Lisp functions to this list with the command
install-func.
If F(X) is not recognized at all, then AUTOSIM treats it as an unknown function, and
simply puts the expression as is into the equations. For example, if your input includes
the expression junk(A, B) as a force amplitude, AUTOSIM will generate equations that
are likely to include the term JUNK(A, B), and to declare JUNK, A, and B as floating
point variables.
In addition to the Fortran-style syntax, all of the AUTOSIM functions can also be
applied using conventional Lisp syntax. In most cases, the name of a function used in an
f-string is simply the name of the AUTOSIM function. There are a few exceptions,
however, because some of the most common functions already exist in Lisp as numerical
functions. These exceptions are listed in Table 8.2.2. For example, the addition function
in Lisp, +, only works with numbers. If you enter a statement such as (+ 2 3) you get 5,
as expected. However, if you enter (+ a b), you get an error because A and B are not
numbers. Instead, use the AUTOSIM f-string !"a + b" to get the symbolic expression A
+ B. Alternatively, you can apply the AUTOSIM add function using Lisp syntax: (add
'a 'b). In the following reference listings, the functions in Table 8.2.2 are listed
according to the names you use in f-strings.

8 79

8.2 Functions

AUTOSIM 2.0
Table 8.2.1. Algebra functions used in f-strings.

Special Symbols
' rest
if first character is ' then
treat rest as plain string
x
x
(neg)
x1 x2
x1 x2
(sub)
s*x
sx
(mul)
n
s**n
s
(make-power)
General Algebra
default(x)
substitute numerical
values for all symbols
.
dxdt(x)
x
func ({s}*)
If func is an unknown
symbol, this form is
assumed to be a function:
func(S1, S2, ..)
Vector Algebra
angle(v1 ,v2 {,v3})
angle between v1
and v2, sign determined
by v3 direction
cross(v1 ,v2) v1 v2
dir(v)
v / |v|
Multibody Properties
basis(body) basis dyadic of body
euler(body, i) ith euler angle for body
fm(f)
magnitude of force or
moment f
inertia(body) inertia dyadic of body
inertiac(body) inertia dyadic of
composite body
ke({body}) kinetic energy of body
and its descendents
mass(body) mass of body
massc(body) mass of composite body
origin(body) origin point of body
pos(p1 {, p2}) vector going from point
p2 to point p1
rfvect(body) reaction force vector for
body

@
x1 + x2
x/s
[]

partial(x, )
symexp ()

z(x)

expression assigned to
external symbol
x1 + x2
(add)
x/s
(div)
symbol is a unit-vector
when enclosed in braces
x/
expression assigned to
AUTOSIM symbol or
array element
intermediate variable to
replace x

dot(v1 ,v2 ) v1 v2
dplane(v1 ,v2 ) projection of vector v1
onto plane perpendicular
to v2
mag(v)
|v|
rmvect(body)

reaction moment vector


for body at its origin
rq(body {, i}) ith rotational coordinate
for body
ru(body {, i}) ith rotational speed for
body
relvel(p, body) relative velocity of p in
moving body
rot(body)
absolute rotational
velocity of body
tq(body {, i}) ith translational
coordinate for body
tu(body {, i}) ith translational speed for
body
vel(p1 {, p2}) abs. velocity of p1 minus
absolute velocity of p2

8 80

8.2 Functions

AUTOSIM 2.0

Table 8.2.2. Algebraic functions with different names for Fortran and Lisp syntax.
Fortran Name
Lisp Name
!
parse-string
*
mul
**
make-power
+
add
sub, neg
/
div
abs
make-abs
acos
make-acos
asin
make-asin
atan
make-atan
cos
make-cos
max
make-max
min
make-min
sign
make-sign
sin
make-sin
sqrt
ssqrt
tan
make-tan

AUTOSIM also includes some functions that are useful for interactively debugging
your inputs. They are listed in Table 8.2.3.

!
AUTOSIM expression obtained by reading a string
Usage
! string
parse-string string
Description
This function parses a string of text and returns the resulting algebraic expression. The
string should contain an algebraic expression written with Fortran-style syntax. A string
having text of this sort is called an F-string.
This function is applied automatically to all arguments of AUTOSIM commands and
functions that are expected to be algebraic expressions. You can use it by itself to
interactively derive expressions, by typing an exclamation mark followed immediately by
a string.
Parse-string reads an F-string in two steps. It first removes any spaces and
linefeeds from the string and converts all of the text to upper-case. Then, through a

8 81

8.2 Functions

AUTOSIM 2.0

Table 8.2.3. Miscellaneous functions.


Function
Description
(arg-body b)
argument check for a body
(arg-dir d)
argument check for a vector direction
(arg-exp e)
argument check for an expression
(arg-point p)
argument check for a point
(arg-string s)
argument check for a string
(body-cm-posb)
vector from origin to mass center of body
(body-cmb)
mass center of body or origin (if body is fixed)
(elapsed-time)
string giving time elapsed since last reset
(equal-exp x y)
Are two expressions algebraically equivalent?
(expand x)
multiply out any products of sums in x
(find-body b)
body that corresponds to symbol b
(find-point p)
point that corresponds to symbol p
(find-sym s)
AUTOSIM symbol that corresponds to symbol s
(find-uv uv)
unit-vector that corresponds to symbol uv
(gen-name u)
generic name for a units expression
(get-name obj)
name of an AUTOSIM object
(get-units x)
units expression for x
(make-func function {arg}*)
Function expression
(point-avep1 p2 )
list of coordinates for point between p1 and p2
(units-gain u)
scale factor for a units expression u
(units x)
printed name of units of x
sequence of find and replace operations, it replaces known functions with AUTOSIM
functions that have built-in rules for performing simplifications. Arithmetic operators (+,
, /, *, **) are also replaced. Table 8.2.1 lists the major functions that are recognized.
Normally, any symbols that appear in an F-string are assumed to represent parameters
or variables in the multibody system. However, it is sometimes convenient to assign an
expression to an external variable via the setsym command, and then include that
expression in an F-string. To do this, the name of the external variable should be
preceded with the character @.
Examples
? (setsym x "a+b")
(B + A)
? !"@x**2"
(B + A)**2

See Also
setsym

8 82

8.2 Functions

AUTOSIM 2.0

*
product of expressions
Usage
!"x1 * x2"
mul {x}*
Description
This function multiplies together all of its arguments, applies simplification techniques,
and returns a result. The arguments can be algebraic expressions or numbers. There is a
Lisp function * that only works with numerical arguments. To avoid using the Lisp
function, the AUTOSIM * function must be applied in an f-string.

**
expression raised to a numerical power
Usage
!"x**p"
make-power x p
Description
This function raises an expression to a power, applies simplification techniques, and
returns a result. The first argument, x, must be a scalar expression or a number. The
second argument, p, must be a number.

+
sum of expressions
Usage
!"x1 + x2"
add {x}*
Description
This function adds together all of its arguments, applies simplification techniques, and
returns a result. The arguments can be algebraic expressions or numbers.
When two expressions are added, their small-order properties are compared. If the
difference is greater than or equal to *small-order*, the smaller term is dropped.
This only applies to variables that have been declared small by the analyst either with a
:small-angles or :small-translations argument in add-body, or with the
small command.
There is a Lisp function + that only works with numerical arguments. To avoid
using the Lisp function, the AUTOSIM + function must be applied in an f-string.

8 83

8.2 Functions

AUTOSIM 2.0

Example
Note how the add function factors out coefficients and drops terms if they are small
relative to other terms in the summation.
? !"a + b*x + c*x**2"
(A + (B + C*X)*X)
? (small x)
SMALL
? !"a + b*x + c*x**2"
(A + B*X)
? !"b*x + c*x**2"
(B + C*X)*X

See Also
*drop-small-terms*, *small-order*, small

difference between two expressions


Usage
!"x - y"
sub x {y}*
neg x
Description
Sub multiplies each argument y by 1 and adds it to x. Neg multiplies x by 1. There is a
Lisp function - that only works with numerical arguments. To avoid using the Lisp
function, the AUTOSIM - function must be applied in an f-string.

/
quotient of two expressions
Usage
!"x / y"
div x y
Description
This function divides y into x, applies simplification techniques, and returns a result. The
arguments can be expressions or numbers, and the result will be an expression or number.
There is a Lisp function / that only works with numerical arguments. To avoid using
the Lisp function, the AUTOSIM / function must be applied in an f-string.

8 84

8.2 Functions

AUTOSIM 2.0

abs
absolute value of an expression
Usage
!"abs(x)"
make-abs x
Description
Make-abs checks the argument x for possible simplifications then returns an absolutevalue function. There is a Lisp function abs that only works with numerical arguments.
To avoid using the Lisp function, the AUTOSIM abs function must be applied in an fstring.

acos
arc cosine of an expression
Usage
!"acos(x)"
make-acos x
Description
Make-acos checks the argument x and applies an appropriate identity to derive an
expression equivalent to a cos 1 function. Rather than create an ACOS function,
AUTOSIM creates an expression involving the ASIN function, to increase the likelihood
of symbolic simplifications. There is a Lisp function acos that only works with
numerical arguments. To avoid using the Lisp function, the AUTOSIM acos function
must be applied in an f-string.
Examples
? !"acos(x)"
-(1.570796326794897 -ASIN(X))
? !"acos(cos(x))"
X
? !"acos(sin(x))"
-(1.570796326794897 -X)

angle
angle between two vectors
Usage
angle v1 v2 {v3 {tan}}
Description
The directions associated with vectors v1 and v2 are obtained, and an expression is
derived for the angle needed to rotate v1 to align it with v2. The result is usually an arc-

8 85

8.2 Functions

AUTOSIM 2.0

tangent function, unless the vectors are related by a simple rotation. The third argument,
if provided, is used to determine the sign of the angle. If v3 is not provided, the
expression for the angle will be adjusted so that there is not a minus sign. If v3 is
provided, the sign of the expression is determined by the rotation needed to align v1 with
v2, as viewed from the direction v3. If the rotation is counter-clockwise, the expression
for the angle is preceded by a minus sign. If the rotation is clockwise, there is no minus
sign.
The argument tan, if not NIL, indicates that the tangent of the angle should be
derived, rather than the angle.
Examples
Consider the spacecraft multibody system from Appendix C of the Introductory Guide to
AUTOSIM. It has four bodies: B (6 DOF), C (1 DOF), D (1 DOF), and E (2 DOF).
? !"angle([cy],[bx])"
(1.570796326794897 + Q(7))
? !"angle([cy],[nx])"
ATAN2((C(7) -Q(6)*S(7)), ABS(Q(6)*C(7) + S(7)))
? !"angle([cy],[nx],[cz])"
-ATAN2((C(7) -Q(6)*S(7)), ABS(Q(6)*C(7) + S(7)))
? !"angle([cy],[nx],[cz],t)"
(C(7) -Q(6)*S(7))/(Q(6)*C(7) + S(7))

arg-body
rigid body, obtained from the name of the body
Usage
arg-body b
Description
This function is used if you create new Lisp functions and commands that have a body b
as an argument. If b is a body object or NIL, it is returned. Otherwise, arg-body tries
to find an appropriate body. If b is a list, the list is evaluated and arg-body is applied
recursively to the result. If b is a symbol or sym, the function find-body is invoked.
If b cannot be associated with a body in the system, an error message is produced.
See Also
body, find-body

arg-dir
vector direction, obtained from a string or other type of Lisp object
Usage
arg-dir d

8 86

8.2 Functions

AUTOSIM 2.0

Description
This function is used if you create new Lisp functions and commands that have a
direction d as an argument. If d is a vector expression or NIL, it is returned. If d is a list,
the list is evaluated and arg-dir is applied recursively to the result. If d is a symbol or
sym, the function find-uv is invoked. Otherwise, an error message is produced.
See Also
expression, find-uv, uv

arg-exp
AUTOSIM expression, obtained from a string or other type of Lisp object
Usage
arg-exp x
Description
This function is used if you create new Lisp functions and commands that have an
expression x as an argument. If x is a NIL, a number, a string, an expression, or
an array, it is returned. If x is a list, the list is evaluated and arg-exp is applied
recursively to the result. If x is a s y m b o l , the function find-sym is invoked.
Otherwise, an error message is produced.
See Also
expression, find-sym

arg-point
AUTOSIM point, obtained from a string or other type of Lisp object
Usage
arg-point b
Description
This function is used if you create new Lisp functions and commands that have a point p
as an argument. If p is a point object or NIL, it is returned. Otherwise, arg-point
tries to find an appropriate point. If p is a list, the list is evaluated and arg-point is
applied recursively to the result. If p is a symbol or sym, the function find-point is
invoked. If p cannot be associated with a point in the system, an error message is
produced.
See Also
point, find-point

arg-string
string, obtained from another type of Lisp object

8 87

8.2 Functions

AUTOSIM 2.0

Usage
arg-string s
Description
This function is used if you create new Lisp functions and commands that have a string s
as an argument. If s is a NIL, it is returned. If s is a list, the list is evaluated and argstring is applied recursively to the result. If s is any type of data object other than NIL,
a list, or a string, it is printed to a string and the string is returned.
If s is a string, the string is searched for occurrences of ~\Newline (that is, the
character ~ followed immediately by a new line.) This is the continuation method
used for strings appearing in Lisp format control strings to continue a string over
several lines. Any such occurrences are removed. This processing is intended to be
exactly the same as done by format with control strings that cover more than one line.

asin
arc sine of an expression
Usage
!"asin(x)"
make-asin x
Description
Make-asin checks the argument x and applies identities if possible to simplify the
result. There is a Lisp function asin that only works with numerical arguments. To
avoid using the Lisp function, the AUTOSIM asin function must be applied in an fstring.
Examples
? !"asin(x)"
ASIN(X)
? !"asin(cos(x))"
(1.570796326794897 + X)
? !"asin(sin(x))"
X

atan
arc tangent of an expression
Usage
!"atan(x{, y})"
!"atan2(x{, y})"
make-atan x {y}

8 88

8.2 Functions

AUTOSIM 2.0

Description
Make-atan can have one or two arguments. In either case, it checks the argument(s)
and applies identities if possible to simplify the result. For example, if x has the form
sin(A) and y has the form cos(A), then the result is A. If there is one argument, the atan
object prints as a function whose name is ATAN. If there are two arguments, it prints as a
function whose name is ATAN2. There is a Lisp function atan that only works with
numerical arguments. To avoid using the Lisp function, the AUTOSIM atan function
must be applied in an f-string.
Examples
? !"atan(x)"
ATAN(X)
? !"atan(x, y)"
ATAN2(X, Y)
? !"atan2(x, y)"
ATAN2(X, Y)
? !"atan2(x)"
ATAN(X)
? !"atan(a*(1-c)*sin(x), (1-c)*cos(x)*a)"
X

basis
basis dyadic for a body
Usage
basis body
Description
Each coordinate system introduced by AUTOSIM has three axes defined by three
mutually orthogonal unit-vectors. A basis dyadic is defined as the sum of three dyads,
where each dyad is defined by writing one of the unit-vectors twice. For example, the
unit-vectors for the inertial reference are nx, ny, and nz, and the basis dyadic is (nx nx +
ny ny + nz nz). A basis dyadic is useful because the dot product of the basis dyadic and a
vector is equivalent to the vector, but when written out, involves only the unit-vectors
that were in the basis dyadic.
Example
Consider the spacecraft example. The angular velocity of body D and the basis dyadic of
D are obtained:
? !"rot(d)"
(U(4)*[bx] + U(8)*[cx] + U(5)*[by] + (U(6) + U(7))*[bz])
? !"basis(d)"
(([cx] [cx]) + ([dz] [dz]) + ([dy] [dy]))

8 89

8.2 Functions

AUTOSIM 2.0

Note that the angular velocity of D as derived by AUTOSIM is very simple, involving no
variables other than generalized speeds. However, it involves unit-vectors fixed in two
moving bodies: B and C. We can generate another expression for the rotational velocity
that involves only the unit-vectors fixed in D by taking the dot product of the angular
velocity with the basis dyadic:
? !"dot(basis(d), rot(d))"
((U(8) + U(4)*C(7) + U(5)*S(7))*[cx] + ((U(6) + U(7))*C(8) S(8)*(U(5)*C(7) -U(4)*S(7)))*[dz] + ((U(6) + U(7))*S(8) +
C(8)*(U(5)*C(7) -U(4)*S(7)))*[dy])

Alternatively, we can obtain an expression involving only the unit-vectors fixed in body
B:
? !"dot(basis(b), rot(d))"
((U(6) + U(7))*[bz] + (U(4) + U(8)*C(7))*[bx] + (U(5) + U(8)*S(7))*[by])

cos
cosine of an expression
Usage
!"cos(x)"
make-cos x
Description
Make-cos checks the argument and applies identities if possible to simplify the result.
There is a Lisp function cos that only works with numerical arguments. To avoid using
the Lisp function, the AUTOSIM cos function must be applied in an f-string.

cross
cross product between two vectors
Usage
cross v1 v2
Description
The vector cross-product between v1 and v2 is derived using information about how the
bodies in the system rotate relative to each other. v1 and v2 can be vectors or dyadics. It
is an error if either v1 or v2 are scalar.
Example
!"cross([dz],[bz])"
-(C(7)*S(8)*[bx] + S(7)*S(8)*[by])

8 90

8.2 Functions

AUTOSIM 2.0

default
result of substituting default numerical values for all symbols
Usage
default x
Description
Default replaces all scalar symbols (parameters and state variables) with numerical
values. Note that unless specified otherwise with the set-defaults command, the
default values for parameters are 1.0, and the default values for state variables are zero.
Numerical values of parameters are divided by scale-factors as needed for the current
units system. This function is useful for debugging the model description.
Example
? !"default(pc(3))"
-0.19999999999999998
? !"pos(scm)"
-(-Q(0)*[nx] -PC(22)*[sx] + L*[ux] -Q(0)*[ny] + HRC*[nz] -PC(25)*[sz])
? !"default(pos(scm))"
(1.460630038046328*[sx] -2.6*[ux] -0.3*[nz] -0.38315379514275055*[sz])
? !"default(dot(basis(n), pos(scm)))"
(-1.114285714285714*[nx] -0.5700000000000001*[nz])

See Also
set-default

dir
direction of a vector
Usage
dir x
Description
x
The direction of vector x is derived with the relationship: (dir x) |x| . The expression
involves the MAX function and a small number, to avoid a singularity when |x| is zero.
Example
!"dir(vel(scm))"
(V/MAX(1.0E-20, SQRT(ABS(V**2 + U(1)**2)))*[sx] + U(1)/MAX(1.0E-20,
SQRT(ABS(V**2 + U(1)**2)))*[sz])

dot
dot product between two vectors, two dyadics, or vector and dyadic

8 91

8.2 Functions

AUTOSIM 2.0

Usage
dot v1 v2
Description
The dot-product between v1 and v2 is derived using information about how the bodies in
the system rotate relative to each other. v1 and v2 can be vectors or dyadics. It is an error
if either v1 or v2 are scalar.
Example
Consider the velocity of the sprung mass from the pitch-plane vehicle example.
? !"vel(scm)"
(V*[sx] + U(1)*[sz])
? !"dot([nx], vel(scm))"
(V*COS(Q(3)) + U(1)*SIN(Q(3)))
? !"dot([ny], vel(scm))"
0
? !"dot([nz], vel(scm))"
(U(1)*COS(Q(3)) -V*SIN(Q(3)))

dplane
projection of vector onto plane
Usage
dplane v1 v2
Description
Vector v1 is projected onto the plane perpendicular to vector v2 . It is an error if either v1
or v2 are scalar or dyadic.
Description
Consider the pitch-plane vehicle example. The projection of the sx (fixed in body S) onto
the ground plane (perpendicular to nz) is obtained as follows:
? !"dplane([sx], [nz])"
([sx] + S(3)*[nz])

dxdt
time derivative of an expression
Usage
dxdt x {dummy}
Description
This function derives the time derivative of x, i.e., dx
dt

8 92

8.2 Functions

AUTOSIM 2.0

AUTOSIM includes rules for obtaining derivatives of all of the algebraic functions
described in this manual. You can also install rules for other functions using the
install-differential command.
Example
Consider the velocity and acceleration of the sprung mass from the pitch-plane vehicle
example.
? !"vel(scm)"
(V*[sx] + U(1)*[sz])
? !"dxdt(vel(scm))"
(U(1)*U(2)*[sx] + (UP(1) -V*U(2))*[sz])

elapsed-time
time elapsed since reset was performed
Usage
elapsed-time {reference}
Description
Produce a string giving the elapsed time since the reset command was invoked. This
uses the Common Lisp function get-internal-run-time.
Examples
? (elapsed-time)
"9 minutes, 53 seconds"

See Also
reset

equal-exp
Boolean result: are two AUTOSIM expressions algebraically equivalent?
Usage
equal-exp x y
Description
If you write new Lisp functions for AUTOSIM, you can use this function as a predicate
to check the algebraic equivalence of two expressions. Conventional Lisp predicates for
equality are not appropriate, because the expression structures contain information in
addition to the algebraic terms. Further, in some cases, using the Lisp equal function on
AUTOSIM expressions can cause the Lisp system to crash. (AUTOSIM structures can be
circular.)
Examples
? (setf x !"a*B" y !"a*b")
A*B
? (eq x y)

8 93

8.2 Functions

AUTOSIM 2.0

NIL
? (equal x y)
NIL
? (equalp x y)
T
? (dxdt x)
0
? (equalp x y)
NIL
? (equal-exp x y)
T

expand
expansion of expression, obtained by multiplying out any products of sums
Usage
expand x
Description
Normally, AUTOSIM keeps products and powers of sums in factored form. Use the
expand function if you want to see the sums multiplied out.
Examples
? (setsym x !"(a + b)**3")
(A + B)**3
? (expand x)
(3.0*A*B**2 + 3.0*B*A**2 + A**3 + B**3)

find-body
body that corresponds to a given symbol
Usage
find-body symbol {body}
Description
This function looks through the multibody system for a body that is associated with
symbol. The search is limited to body and its children. The default value for body is N.
This function returns the body or NIL if no body is found to match symbol. Find-body
is mainly for use inside new Lisp functions you might write. The arguments must be
quoted properly according to Lisp conventions.
See Also
arg-body, body

find-point
point that corresponds to a given symbol
8 94

8.2 Functions

AUTOSIM 2.0

Usage
find-point symbol
Description
This function looks through the multibody system for a point that is associated with
symbol. Points can have more than one identifying symbol, and all valid symbols are
searched for each point. Thus, find-point works with any valid alias for an existing
point. This function returns the point if one exists, or prints an error message if one
does not. Find-point is mainly for use inside new Lisp functions you might write. The
argument must be quoted properly according to Lisp conventions.
See Also
arg-point, point

find-sym
AUTOSIM symbol (sym) that corresponds to a given symbol
Usage
find-sym symbol
Description
This function looks through the list of syms to find the one the corresponds to symbol. If
the sym exists, it is returned. If not, a new sym is created, added to the list maintained by
AUTOSIM, and returned. Find-sym is mainly for use inside new Lisp functions you
might write. The argument must be quoted properly according to Lisp conventions.
See Also
arg-exp, sym

find-uv
unit-vector (uv) that corresponds to a given name.
Usage
find-uv symbol
Description
This function looks through the multibody system for a uv that is associated with symbol.
Usually, symbol is simply the printed representation of the uv. Be aware that the finduv function does not always return a uv with the same printed representation as the
provided symbol. Find-uv is mainly for use inside new Lisp functions you might write.
The argument must be quoted properly according to Lisp conventions.
See Also
uv

8 95

8.2 Functions

AUTOSIM 2.0

fm
magnitude of a force or moment
Usage
forcem symbol
Description
This function returns the magnitude of a force or moment introduced with the
commands add-line-force, add-strut, and add-moment. When used in an fstring, the name recognized for the function is determined by the global variable *fmsymbol*. Alternatively, the function name FM is always recognized.
Example
Consider the vehicle pitch-plane model.
(add-line-force fsf :name "front spring force" :direction [sz]
:magnitude "(wf - maf)*g/2 -kf*x"
:point1 af0 :point2 afj)
FSF: Front spring force; Acts on the front wheel from the sprung mass
through coord. origin of the front wheel. Magnitude = -FORCEM(1);
Direction = [sz].
? !"fm(x)"
-FORCEM(1)
? !"symexp(fm(fsf))"
-(0.5*G*(MAF -WF) + KF*Q(4))

See Also
*fm-symbol*, add-line-force, add-strut, add-moment

get-name
name of an expression
Usage
get-name x
Description
This function obtains the name associated with an expression x. Unless x is a symbol,
there is probably no associated name. If no name exists, NIL is returned.
Examples
? (get-name "q(1)")
"Rot. of C relative to N about axis #3."
? (get-name 'mr)
"mass of R"
? (get-name 'rm)
"NIL"

See Also
set-name, name

8 96

8.2 Functions

AUTOSIM 2.0

get-units
units of an expression
Usage
get-units x
Description
This function obtains the units for x in a generic form, namely, an expression involving
the symbols A (angle), L (length), F (force), T (time), and C (counts). This generic form
is independent of the units system used.
Very often, units derived by AUTOSIM will not follow conventions involving
angular units, which, in dynamical conventions, are dimensionless. Nonetheless, it is
often necessary to convert from radians to degrees, so angular units are manipulated to
the extent possible. If parameters or variables print with an inappropriate angular unit, the
set-units command should be used to assign the units manually.
Example
? (get-units "q(1)")
A
? (get-units 'mr)
F*T**2/L
? (get-units 'rm)
NIL

See Also
set-units, units

ke
kinetic energy of subsystem
Usage
ke {body}
Description
This function produces an expression for the kinetic energy of body and all its
descendants. When no argument is provided, the resulting expression gives the kinetic
energy for the entire system.
Example
!"ke()"
(0.5*(0.5*IYY*U(2)**2 + 0.5*(WR -MAF -MAR + WF)*(V**2 + U(1)**2)) +
0.25*MAF*((V + Q(4)*U(2))**2 + (U(1) + U(3) -PC(3)*U(2))**2) +
0.25*MAR*((V + Q(5)*U(2))**2 + (U(1) + U(4) + PC(4)*U(2))**2))

8 97

8.2 Functions

AUTOSIM 2.0

mag
magnitude (absolute value) of a vector
Usage
mag x
Example
!"mag(vel(rcmb))"
R*U(1)*SQRT(1 -PC(2)*C(1)*(2.0*C(2) -PC(2)*C(1)/L/(C(1)*C(2) S(1)*S(2)))/L/(C(1)*C(2) -S(1)*S(2)))

make-func
external function
Usage
!"function(arg1, arg2, ...)"
make-func function {arg}*
Description
Make-func creates a func object with the symbol provided as the function argument
being put in the function slot, and a list created from all of the arg arguments being put in
the args slot. Before creating the function, a list of installed functions is checked to see if
a symbolic procedure exists for function. If such a procedure is found, it is applied.
(Usually, specialized procedures are used to perform possible simplifications. For
example, the make-sin function checks to see if the argument is an inverse sine.)
See Also
func, install-func

max
maximum value from a set of expressions
Usage
!"max {x}*)"
make-max {x}*
Description
Make-max checks the arguments and applies identities if possible to simplify the result.
There is a Lisp function max that only works with numerical arguments. To avoid
using the Lisp function, the AUTOSIM max function must be applied in an f-string.
Example
The following shows how max works using numerical arguments
!"max(1,3,2)"
3

8 98

8.2 Functions

AUTOSIM 2.0

See Also
Section 7.1

min
minimum value from a set of expressions
Usage
!"min {x}*)"
make-min {x}*
Description
Make-min checks the arguments and applies identities if possible to simplify the result.
There is a Lisp function min that only works with numerical arguments. To avoid using
the Lisp function, the AUTOSIM min function must be applied in an f-string.
Example
The following shows how min works using numerical arguments
!"min(1,3,2)"
1

See Also
Section 7.1

nominal
nominal value for an expression
Usage
nominal x
Description
Nominal obtains an expression for x that applies when all coordinates and speeds are set
to zero.
Example
? !"dot([n1], pos(rcmb))"
(R*C(1) + PC(2)*(C(1)*C(2) -S(1)*S(2)))
? !"nominal(dot([n1], pos(rcmb)))"
(R + PC(2))

partial
partial derivative of expression

8 99

8.2 Functions

AUTOSIM 2.0

Usage
partial y {x}
Description
y
.. When applied
x
to intermediate variables, the function is applied recursively to the original expression.
This function derives the partial derivative of y with respect to x, i.e.,

The default value of x is T (time).


AUTOSIM includes rules for obtaining derivatives of all of the expression types that
are built in. You can install rules for other functions using the installdifferential command.
Example
Consider the pitch-plane vehicle example.
? !"vel(s0)"
(V*[sx] + (U(1) -PC(3)*U(2))*[sz])
? !"partial(vel(s0), v)"
[sx]
? !"partial(vel(s0), L)"
-PC(1)*PC(2)*U(2)*[sz]

Note that the partial function obtained a non-zero result for L, even though the
velocity expression did not explicitly include L. The reason is that the intermediate
symbol PC(3) was assigned to an expression involving L:
? !"symexp(pc(3))"
L*PC(1)*PC(2)

See Also
install-differential, Section 6.6

point
obtain point with given symbol
Usage
point p
Description
This function provides a point with symbol p. It is mainly used for debugging, because
the printed representation of a point shows its body and coordinates. Information for all
points in the system is obtained with the command print-points.
Note: there is also a data type point, listed in Section 8.4.
See Also
point (Section 8.4), print-points

8 100

8.2 Functions

AUTOSIM 2.0

point-ave
average coordinates of two existing points
Usage
point-ave p1 p2 {:body body} {:m1 m1} {:m2 m2}
Description
This function returns a list of three coordinates obtained by taking a weighted average of
the coordinates of points p1 and p2. Geometrically, the coordinates returned are for a
point on a line connecting p1 and p2. The location along the line is determined by the
weighting factors m1 and m2. Setting them to equal values (the default) results in the new
point being mid-way between p1 and p2. The coordinates are expressed in the coordinate
system body.
Example
Consider the four-bar linkage example. Body A (a link) is attached to ground at point P1,
and to body C at point AP3. Suppose we want to define a new point between the two,
twice as far from point P1 as point AP3.
? (point p1)
(Point P1: Body N: (XP1 YP1 0): pin between A and N)
? (point ap3)
(Point AP3: Body A: (-PC(5) PC(6) 0): AP3)
? (point-ave p1 ap3 :body a :m1 1 :m2 2)
(-0.6666666666666666*PC(5) 0.6666666666666666*PC(6) 0)
? (add-point pnew :body a
:coordinates (point-ave p1 ap3 :body a :m1 1 :m2 2))
(Point PNEW: Body A: (-PC(9) PC(10) 0): PNEW)

See Also
add-point, point

pos
position vector connecting two points
Usage
pos point1 {point2}
Description
Pos obtains a vector going from point2 to point1. If point2 is not provided, the default is
the origin of N. The arguments point1 and point2 must be either points or symbols that
are associated with points.
Example
Consider the four-bar linkage example.
? !"pos(cp3)"
(YP6*[ny] + PC(1)*[bx] -PC(7)*[cx] -PC(2)*[by] + XP6*[nx] + PC(8)*[cy])
? !"pos(cp3, c0)"

8 101

8.2 Functions

AUTOSIM 2.0

-(PC(7)*[cx] -PC(8)*[cy])

See Also
point

relvel
velocity of a point relative to a moving coordinate system
Usage
relvel point body
Description
Point is the point of interest, and body is a body in the multibody system used as a
moving reference. Relvel returns a vector that is the relative velocity of point in body.
The absolute veloctity of a point is obtained with the vel function.
Example
Consider the four-bar linkage example.
? !"vel(cp3)"
-(-PC(1)*U(2)*[by] -PC(2)*U(2)*[bx] + PC(7)*(U(2) + U(3))*[cy] +
PC(8)*(U(2) + U(3))*[cx])
? !"relvel(cp3, b)"
-(PC(7)*U(3)*[cy] + PC(8)*U(3)*[cx])
? !"relvel(cp3, c)"
0

See Also
vel

rfvect
reaction force vector acting on a body
Usage
rfvect body
Description
This is the sum of all forces that are not accounted for by active forces and acceleration
of the center of mass. The main purpose of this function is to help generate output
variables. A scalar component of interest can be obtained using a dot product.
The rfvect function invokes a dynamics analysis followed by a reaction-force
analysis. It should not be used until the multibody system has been completely built.
AUTOSIM derives an expression for the force vector for body by subtracting the
inertial effects and all forces added by using the add-line-force and add-strut
commands. The physical meaning of this vector depends on the layout of the mechanical
8 102

8.2 Functions

AUTOSIM 2.0

system. An AUTOSIM input without the commands motion, no-movement, addspeed-constraint, and add-position-constraint describes a tree
topology. In a tree topology, the reaction force vector for body is due solely to the joint
connecting body to its parent. In other systems, in which one or more of the generalized
speeds are eliminated by the introduction of a constraint, the force vector is the sum of
the reaction force between body and its parent and possibly a reaction force due to
whatever physically causes the constraints.
Example
Consider the spacecraft example from the Introductory Guide to AUTOSIM.
? !"rfvect(c)"
(Z(814)*[bz] + Z(815)*[cx] + Z(818)*[cy])

See Also
rmvect

rmvect
reaction moment vector acting on a body about its origin
Usage
rmvect body
Description
This is the sum of all moments that are not accounted for by active forces, moments,
acceleration of the center of mass, and change in angular momentum. The main purpose
of this function is to help generate output variables. A scalar component of interest can be
obtained using a dot product.
The rmvect function invokes a dynamics analysis followed by a reaction-force
analysis and a reaction moment analysis. It should not be used until the multibody system
has been completely built.
AUTOSIM derives an expression for the moment vector for body by subtracting the
inertial effects, all forces added by using the add-line-force and add-strut
commands, and all moments added with the add-moment command. The physical
meaning of this vector depends on the layout of the mechanical system. An AUTOSIM
input without the commands motion, no-movement, add-speed-constraint,
and add-position-constraint describes a tree topology. In a tree topology, the
reaction moment vector for body is due solely to the joint connecting body to its parent.
In other systems, in which one or more of the generalized speeds are eliminated by the
introduction of a constraint, the moment vector is the sum of the reaction moment
between body and its parent and possibly a reactions due to whatever physically causes
the constraints.
Example
Consider the spacecraft example from the Introductory Guide to AUTOSIM.

8 103

8.2 Functions

AUTOSIM 2.0

? !"rmvect(c)"
-(Z(839)*[dy] -Z(849)*[by] -Z(851)*[bx] + Z(847)*[dz] + Z(853)*[bz] +
Z(856)*[cy] -Z(864)*[cx])
? !"dot([cx],rmvect(c))"
(Z(864) + Z(851)*C(7) + Z(849)*S(7))

See Also
rfvect

rot
rotational velocity vector for a body
Usage
rot body
Examples
Consider the four-bar linkage example.
? !"rot(c)"
(U(2) + U(3))*[nz]

rq
rotational coordinate (Q) associated with a given body
Usage
rq b {i}
Description
RQ returns the ith rotational coordinate associated with a given body (the default for i is
1). The result is either a generalized coordinate, or zero, if the body does not have the
specified rotational degree of freedom.
Example
? !"rq(a)"
Q(2)

See Also
ru, tq, tu

ru
rotational speed (U) associated with a given body

8 104

8.2 Functions

AUTOSIM 2.0

Usage
ru b {i}
Description
RU returns the ith rotational speed associated with a given body (the default for i is 1).
The result is one of three possibilities: (1) a generalized speed, (2) an expression used to
replace a generalized speed due to a constraint on the rotation (added with add-speedconstraint), or (3) zero, if the body does not have the specified rotational degree of
freedom.
Example
Consider the four-bar linkage example.
? !"ru(a)"
Z(33)*U(1)
? !"ru(b)"
U(1)
? !"ru(c)"
-Z(31)*U(1)

See Also
rq, tq, tu

sign
y
sign of an expression: |x| |y|
Usage
!"sign(x{, y})"
make-sign x{, y}
Description
Make-sign checks the argument and applies identities if possible to simplify the result.
There is a Lisp function sign that only works with numerical arguments. To avoid
using the Lisp function, the AUTOSIM sign function must be applied in an f-string.
When the function is applied to numerical arguments,
Example
The following shows how sign works using numerical arguments
!"sign(2, -5)"
-2

See Also
Section 7.1

sin
sine of an expression

8 105

8.2 Functions

AUTOSIM 2.0

Usage
!"sin(x)"
make-sin x
Description
Make-sin checks the argument and applies identities if possible to simplify the result.
There is a Lisp function sin that only works with numerical arguments. To avoid using
the Lisp function, the AUTOSIM sin function must be applied in an f-string.

square
product of an expression with itself
Usage
square x

sqrt
square root of an expression
Usage
!"sqrt(x)"
ssqrt x
Description
Ssqrt checks the argument and applies identities if possible to simplify the result. There
is a Lisp function sqrt that only works with numerical arguments. To avoid using the
Lisp function, the AUTOSIM sqrt function must be applied in an f-string.

symexp
expression assigned to symbol
Usage
symexp x
Description
Given an equation of the form x = y, this function returns y given x. The argument x
should be a symbol or indexed symbol.
Example
? !"symexp(pc(3))"
(-XP4 + XP6 + PC(1))
? !"symexp(pc(1))"
(XP8 -XP6)

8 106

8.2 Functions

AUTOSIM 2.0

tan
tangent of an expression
Usage
!"tan(x)"
make-tan x
Description
Make-tan checks the argument and applies identities if possible to simplify the result.
There is a Lisp function tan that only works with numerical arguments. To avoid using
the Lisp function, the AUTOSIM tan function must be applied in an f-string.

tq
translational coordinate (Q) associated with a given body
Usage
tq b {i}
Description
TQ returns the ith translational coordinate associated with a given body (the default for i is
1). The result is either a generalized coordinate, or zero, if the body does not have the
specified translational degree of freedom. The reference remains valid, even if the
coordinate is removed from the equations of motion.
See Also
rq, ru, tu

tu
translational speed (U) associated with a given body
Usage
tu b {i}
Description
TU returns the ith translational speed associated with a given body (the default for i is 1).
The result is one of three possibilities: (1) a generalized speed, (2) an expression used to
replace a generalized speed due to a constraint on the translation, or (3) zero, if the body
does not have the specified translational degree of freedom.
See Also
rq, ru, tq

8 107

8.2 Functions

AUTOSIM 2.0

units
text string with units of expression, using current units system
Usage
units x
Example
? (units (rot c))
"deg/s"

See Also
get-units, set-units, in-lb, mks, si

vel
difference in absolute velocity vectors for two points
Usage
vel point1 {point2}
Description
Vel obtains the absolute velocity of point1 and the absolute velocity of point2 and
subtracts the two. If point2 is not provided, the default is the origin of N (whose velocity
is identically zero). The arguments point1 and point2 must be either points or symbols
that are associated with points. The difference in absolute velocities of two points is not
the same as the relative velocity of one point with respect to the body containing the
other. (Use the function relvel to obtain relative velocity.)
Examples
Consider the four-bar linkage example.
? !"vel(cp3)"
-(-PC(1)*U(1)*[by] -PC(2)*U(1)*[bx] + PC(7)*(1.0 -Z(31))*U(1)*[cy] +
PC(8)*(1.0 -Z(31))*U(1)*[cx])
? !"vel(cp3, c0)"
-(PC(7)*(1.0 -Z(31))*U(1)*[cy] + PC(8)*(1.0 -Z(31))*U(1)*[cx])
? !"relvel(cp3, c)"
0

See Also
relvel

z
intermediate variable Z(i) or new intermediate variable to replace an expression
Usage
zi

8 108

8.2 Functions

AUTOSIM 2.0

Description
This function behaves in two ways, depending on whether i is an integer or a more
complex expression. I i is an integer, the function searches through the Z indexed
symbols and returns the AUTOSIM object that prints as Z(i). This is mainly used to
reference Z variables in f-strings. If i is an other type of expression, this function
introduces an intermediate variable, installs it immediately into the equations, and returns
the new variable. The name for this function that is recognized in an f-string is the
symbol assigned to the global variable *z-symbol*. (That symbol is Z, unless you
change it.) The definitions of all intermediate variables introduced with this function are
kept in equation sets assigned to the global variable *time-eqs* (for expressions that
are directly or indirectly functions of time) and *pre-comp* (for expressions that are
constant).
The expression assigned to an intermediate variable can be obtained with the function
symexp.
Example
? !"z(dxdt(a*sin(b*t)))"
Z(3)
? *time-eqs*
Z(1) = B*T
Z(2) = COS(Z(1))
Z(3) = PC(1)*Z(2)
? *pre-comp*
PC(1) = B*A

See Also
*pre-comp*, *time-eqs*, *z-symbol*, symexp

8.3 Globals
AUTOSIM includes many settings and analysis options. These options are defined by
the current values of global system variables. Global variables are also used by
AUTOSIM to maintain information about the multibody system being analyzed.
AUTOSIM global variable names all begin and end with an asterisk. Tables 8.3.1
through 8.3.5 list all of the globals that are safe for you to modify. Each of these variables
is described in an individual listing in this section. Table 8.3.6 lists a few more variables
that cannot be changed but which can provide useful information about the status of the
multibody system.

8 109

8.3 Globals

AUTOSIM 2.0

Table 8.3.1. Global string variables.


Global
Description
*compiler*
directory with compiler-specific Fortran code
*c=*
comment separator used in Fortran subroutines
*fortran-implicit*
statement written at start of each Fortran routine
*include-path*
pathname to include directory
*multibody-system-name*
name of current multibody system
*unit-vector-brackets*
bracket characters used to write unit-vectors
*unit-vector-indices*
indices used to write unit-vectors

Global
*absolute-drop*
*combine-masses*
*conserve-memory*
*double-precision*
*drop-small-terms*
*expand*
*expand-pcs*
*fast-computedcoordinates*
*int-vars*
*no-pcs*
*no-zees*
*print-aliases*
*safe-divide*
*safe-sqrt*
*stiff-integrator*
*use-x-derivativein-forces*
*verbose*

Table 8.3.2. Global Boolean variables.


Def. Condition
NIL
Unconditionally drop small terms as they appear?
NIL
Combine masses to create composite bodies?
T
Periodically clear temporary results from memory?
NIL
Write Fortran code in double precision?
T
Drop terms when added to larger terms?
NIL
Expand products of sums as they occur?
NIL
Expand intermediate symbols for a constant?
T
Use approximation to update computed coordinates in
a dynamical simulation?
T
Introduce intermediate symbols to simplify equations?
NIL
Disable the use of intermediate constants?
NIL
Disable the use of intermediate variables?
NIL
Show all names and symbols of objects?
NIL
Check all denominators for zero in generated code?
NIL
Check sign of all square roots in generated code?
NIL
Use multi-step, multi-order stiff integrator in Fortran?
NIL
Use derivative of dummy X in forces?
T

Thoroughly comment equations?

8 110

8.3 Globals

AUTOSIM 2.0

Table 8.3.3. Global symbol variables.


Global
Default Description
C
*cos-symbol*
array of cosines of generalized coordinates
ERRF
*errf-symbol*
array of error residuals
FM
*fm-symbol*
array of force and moment magnitudes
GFA
*force-array-symbol*
array of generalized forces
JAC
*jac-symbol*
Jacobian matrix
M
*mass-matrix-symbol*
mass matrix
PC
*pc-symbol*
array of constants that are pre-computed
Q
*q-symbol*
array of generalized coordinates
QP
*qp-symbol*
array of derivatives of generalized coordinates
S
*sin-symbol*
array of sines of generalized coordinates
FORTRAN output language for generated code
*target-language*
U
*u-symbol*
array of generalized speeds
UP
*up-symbol*
array of derivatives of generalized speeds
X
*x-symbol*
dummy variable for deflection
X0
*x0-symbol*
dummy variable for nominal deflection
V
*v-symbol*
dummy variable for deflection rate
Z
*z-symbol*
array of intermediate variables
ZI
*zi-symbol*
array of intermediate variables in INITNR

Global
*angle*
*counts*
*degree*
*force*
*gees*
*length*
*time*

Table 8.3.4. Global units-symbols variables.


Default
Description
A
angular units (e.g., deg, rad)
C
integer units (e.g., counts, cycles)
DR
conversion coefficient: deg/rad (57.3)
F
force units (e.g., lb, N)
G
gravitational constant (e.g., 386.2, 9.80665)
L
length units (e.g., in, ft, m, mm)
T
time units (e.g., sec)

Table 8.3.5. Global list variables.


Global
Description
*echo-header*
strings to write at start of echo file
*extra-lines-in-erd-header*
extra lines put into header of output file
*screen-header*
strings to write on screen when program starts
*universal-constants*
unit-dependent constants

8 111

8.3 Globals

Global
*analysis*
*bodies*
*force-array*
*force-eqs*
*forces*
*known-speeds*
*initnr-eqs*
*linear-a*
*linear-b*
*linear-c*
*linear-d*
*mass-matrix*
*moments*
*number-of-adds*
*number-of-funcs*
*number-of-muls*
*pre-comp*
*points*
*speed-array*
*symbols*
*time-eqs*

AUTOSIM 2.0
Table 8.3.6. Protected variables.
Type
Description
symbol the most recent analysis performed
body
inertial reference
array
array of generalized forces for nonlinear dynamics
equations equations for forces and moments
list
list of forces in multibody system
array
array of speeds for nonlinear kinematical equations
equations equations for subroutine INITNR
matrix matrix A after linear analysis
matrix matrix B after linear analysis
matrix matrix C after linear analysis
matrix matrix D after linear analysis
matrix mass matrix for nonlinear dynamics
list
list of moments in multibody system
number number of add and subtract operations in equations
number number of functions and subroutines in equations
number number of multiply and divide operations in equations
equations equations for pre-computed constants
list
list of points in multibody system
matrix kinematical speed matrix
list
list of all AUTOSIM symbols
equations equations for variables

*absolute-drop*
Boolean
Definition
*absolute-drop* determines which of two strategies are used to drop small terms
that are beyond a threshold. (State variables are considered small if certain options are
used with the add-body command. Any symbol can be made small with the small
command.)
You can change the value of *absolute-drop* at various stages in a symbolic
analysis to fine-tune the analysis strategy. When *absolute-drop* is NIL (the
default), terms are dropped when they added to another term that is larger by an amount
greater than or equal to *small-order* (normally, 2). However, when *absolutedrop* is not NIL, the small terms are dropped immediately if the small-order value
is greater than or equal to *small-order*. This value has an influence only when (1)
some terms have been declared as small using optional arguments in add-body or with
the small command, and (2) the Boolean global *drop-small-terms* is T.

8 112

8.3 Globals

AUTOSIM 2.0

Example
Consider the following interactive session involving a small symbol X:
? (small x)
SMALL
? *absolute-drop*
NIL
? *small-order*
2
? !"x**2 + x"
(1 + X)*X
? !"x**2 + 1"
1
? (setsym *absolute-drop* t)
T
? !"x**2 + x"
X
?

See Also
*drop-small-terms*, *small-order*, add-body, large, small

*analysis*
protected symbol
Description
This identifies the most recent major analysis. For example, after a reset, it is set to the
symbol reset. After the finish command, this is set to finished-equilibrium,
finished-full-dynamics, or finished-linear-dynamics.

*angle*
units symbol
Description
*angle* is set to symbol that represents units of angle in a units expression. The default
representation is A. The printed name of units involving angles depends on the units
system.
See Also
get-units, set-units

*bodies*
inertial reference body

8 113

8.3 Globals

AUTOSIM 2.0

Description
*body* is set to the inertial reference body data structure. Because the body data type
is a tree, all rigid bodies in the multibody system can be accessed from *body* via the
children slot. The current body structure assigned to *bodies* is cleared by the
reset command, and a replaced by a new structure with no children.
See Also
body, reset

*combine-masses*
Boolean
Description
If this variable is set to T, masses of separate rigid bodies are combined when possible to
create composite bodies. If masses are combined, the equations of motion may be
simpler. However, if reaction forces and moments are used to define output variables,
they are based on the reactions due to the composite bodies and may not be what is
expected. Thus, if you are interested in reaction forces or moments, it is generally a good
idea to set this variable to NIL.
See Also
Section 7.2

*compiler*
string
Description
This is the name of a subdirectory with include files tailored for a specific Fortran
compiler. These files are used instead of the standard files in the includes directory,
specified by the *include-path* global. When AUTOSIM goes to access an include
file, it checks to see if the file exists in the directory identified by *compiler*. If that
file exists, it is used. If the file does not exist, then the file from the includes directory is
used.
This string should end with the directory delimiter character for your machine. For a
UNIX machine or IBM PC, use the slash character / as a delimiter, e.g., "f77/". For a
Macintosh, use the colon character :, e.g., "absoft:".
Example
Suppose the includes directory on an IBM PC is in C:\AUTOSIM\includes and the
exception files for the Microsoft Fortran compiler are in C:\AUTOSIM\includes\msf:
? *include-path*
"C:/AUTOSIM/includes/"
? *compiler*
"msf/"

8 114

8.3 Globals

AUTOSIM 2.0

See Also
*include-path*

*conserve-memory*
Boolean
Description
This controls whether AUTOSIM should conserve memory or keep many intermediate
results for potential debugging purposes. When *conserve-memory* is not NIL,
memory-hogging data structures are cleared as soon as they are no longer needed for the
analysis. Unless you are looking at AUTOSIM structures that are not normally viewed,
keep this variable set to T.

*cos-symbol*
symbol
Description
This names an array used in the simulation code to store COS functions of generalized
coordinates. It is nominally C. If you change this symbol, you should start a new analysis
with the reset command to properly initialize AUTOSIM.
See Also
reset, Section 2.4

*counts*
units symbol
Description
*counts* is set to symbol that represents integer units in a units expression. The default
representation is C. The printed name of units involving counts depends on the units
system.
See Also
get-units, set-units

*c=*
string
Description
This string is printed before and after subroutine and function statements that are
generated by AUTOSIM. This string can be set blank (i.e., ""), or to a commented string
that ends with an endLine character.
8 115

8.3 Globals

AUTOSIM 2.0

Example
? *c=*
"C======================================================================
"

*degree*
symbol
Description
*degree* is set to a symbol that represents a degree/radian conversion. It normally is
printed as DR. If you change this symbol, you should start a new analysis with the
reset command to properly initialize AUTOSIM. This global is a member of a list
assigned to another global: *universal-constants*.
See Also
*universal-constants*, reset

*double-precision*
Boolean
Description
*double-precision* determines whether Fortran floating-point declarations are in
single-precision or double-precision. When using the add-variables command,
always use the symbol real for floating point. When *double-precision* is NIL,
the variables are declared with type REAL. Otherwise, the variables are declared with
type REAL*8 (in ACSL, DOUBLEPRECISION). The value of * d o u b l e precision* can be changed at any time before Fortran code is generated. (The current
setting is always used when generating Fortran source code.)
See Also
add-variables

drop-small-terms*
Boolean
Definition
*drop-small-terms* determines whether small terms are dropped during algebraic
operations. If *drop-small-terms* is NIL, then no simplifications are made by
dropping small terms. If the variable is T, then simplifications are made. The rules used
to determine how an expression is simplified depend on the values of *absolutedrop* and *small-order*
Example
Consider the following interactive session:
8 116

8.3 Globals

AUTOSIM 2.0

? (setsym *drop-small-terms* t)
T
? (small x)
SMALL
? !"x**2 + 1"
1
? (setsym *drop-small-terms* nil)
NIL
? !"x**2 + 1"
1 + X**2
?

See Also
*absolute-drop*, *small-order*, small

*echo-header*
list
Description
*echo-header* is a list of strings to write in the echo file produced by the simulation
code. This list appears as a sequence of WRITE statements in subroutine ECHO. If
*echo-header* is NIL (the normal value after reset), a header is created when a
simulation program is written using the string in *multibody-system-name*. The
setsym command is used to assign a list of strings to a variable.
Example
? (setsym *echo-header*
("This file was created for the four-bar linkage model"
"this version created September 1, 1992"
"University of Michigan"))
("This file was created for the four-bar linkage model" "this version
created September 1, 1992" "University of Michigan")

See Also
*multibody-system-name*, reset, setsym

*erff-symbol*
symbol
Description
This names the array of constraint errors in subroutine INITNR. It is nominally ERRF. If
you change this symbol with setsym, the reset function must be applied before the
next analysis is started.
See Also
reset, Section 2.4

8 117

8.3 Globals

AUTOSIM 2.0

*expand*
Boolean
Description
*expand* determines whether products of sums are fully expanded in routine algebraic
manipulations. The normal value is NIL. AUTOSIM sets this variable is set to T for short
periods of time to perform certain algebraic operations. If you set it to T, the equations
obtained are much more complex than normal.
Example
Consider the following interactive session:
? !"(A+B)*(A+2*B+F+G)"
(2.0*B + F + G + A)*(B + A)
? (setsym *expand* t)
T
? !"(A+B)*(A+2*B+F+G)"
(2.0*B**2 + B*F + B*G + 3.0*B*A + F*A + G*A + A**2)

*expand-pcs*
Boolean
Description
*expand-pcs* determines whether intermediate variables introduced for constants are
fully expanded. When the expansion is enabled, all PC terms are nonrecursive, involving
only parameters of the multibody system. This leads to expressions for the PCs that can
be inspected and understood. Sometimes, the expansions enable algebraic simplifications
that would otherwise not be made. However, the symbol manipulation is slowed down as
a result. For systems that are moderately complex, huge expressions can be generated.
The recommended value is NIL. It can be set T for simple systems, if the equations
are going to be studied or published.
This setting has no effect unless the global *int-vars* is T and the global *nopcs* is NIL.
See Also
*int-vars*, *no-pcs*

*extra-lines-in-ERD-header*
list
Description
*extra-lines-in-ERD-header* is a list of strings to write in the header of the
output file produced by the simulation code. (The output file normally has the format of
an ERD file, which is why the function is named as it is.) This list appears as a sequence

8 118

8.3 Globals

AUTOSIM 2.0

of WRITE statements in subroutine OPNOUT. If *extra-lines-in-ERD-header*


is NIL (the normal value after reset), only the standard header is created.
See Also
add-to-erd-header, write-opnout

*fast-computed-coordinates*
Boolean
Description
*fast-computed-coordinates* determines whether a a fast approximation is
used to update computed coordinates in a dynamical simulation. If this is NIL, then a full
Newton-Raphson iteration is used each time (see Sections 2.2 and 2.3). If it is T, then the
approximation described in Section 2.3 is used. The variable *fast-computedcoordinates* is considered during the analysis applied with the final command. At
any other time, the value has no effect on the analysis.
See Also
Sections 2.2, 2.3, 7.2, final command

*fm-symbol*
symbol
Description
This names an array used in the simulation code to store forces and moments. It is
nominally FM. If you change this symbol, you should start a new analysis with the
reset command to properly initialize AUTOSIM. This symbol is also recognized in fstrings as a function (nominally, fm) that provides the magnitude of a force or moment.
See Also
fm, reset, Section 2.4

*force*
units symbol
Description
*force* is set to symbol that represents units of force in a units expression. The default
representation is F. The printed name of units involving force depends on the units
system.
See Also
get-units, set-units

8 119

8.3 Globals

AUTOSIM 2.0

*force-array*
protected array
Description
*force-array* is set to the array whose elements are the right-hand sides (relative to
the equal sign) of the implicit dynamical equations,
.
Mu =f
.
where u is a 1-dimensional array of the derivatives of the generalized speeds. The
matrix M and the array f are computed by the command dynamics unless the order-n
option is used, and are assigned to the globals *mass-matrix* and *force-array*,
respectively. The number of elements in *force-array* is the number of degrees of
the multibody system.
See Also
*mass-matrix*, dynamics

*force-array-symbol*
symbol
Description
This names an array used in the simulation code to store generalized force array if certain
values are specified for the optional :formalism keyword in the dynamics command.
It is nominally GFA. If you change this symbol, you should start a new analysis with the
reset command to properly initialize AUTOSIM.
See Also
dynamics, reset, Section 2.4

*force-eqs*
protected equation structure
Description
*force-eqs* is set to an equation set that contains the assignments of all force and
moment amplitudes. Before the finish command is executed, it contains the
magnitudes without the introduction of intermediate variables. During the finish
command, these equations are processed and the results are merged into the general
equation set contained in the equation set assigned to the global *time-eqs*.
See Also
*time-eqs*, eqs

8 120

8.3 Globals

AUTOSIM 2.0

*forces*
protected list
Description
*forces* is a list of all of the forces in the multibody model. The elements of this list
are all AUTOSIM force objects. They can be printed using the command printforces.
See Also
force, print-forces

*fortran-implicit*
string
Description
*fortran-implicit* is a string inserted at the start of each Fortran subroutine. For
example, if your compiler supports the IMPLICIT NONE declaration, this can be
inserted at the start of each subroutine. It may also be useful to enable certain compiler
options, such as support for floating-point hardware, large arrays, etc. This string can be
set blank (i.e., ""), string with one or more lines that ends with an endLine character.
Example
This is how you would include an IMPLICIT NONE directive at the start of each
Fortran subroutine generated by AUTOSIM. Note the string ends with a newline
character. The appearance in the function FCT is then shown.
? (setsym *fortran-implicit*
"
IMPLICIT NONE
")
"
IMPLICIT NONE
"? (write-fct)
C=======================================================================
SUBROUTINE FCT(T, Y, YP)
C=======================================================================
C This subroutine is an interface between a calling program with state
C variables in array Y and their coordinates in YP, and the subroutine
C DIFEQN with its state variables in arrays Q and U, and their
C derivatives in arrays QP and UP.
C
IMPLICIT NONE
REAL
T, Y, YP
...

*gees*
symbol

8 121

8.3 Globals

AUTOSIM 2.0

Description
*gees* is set to an AUTOSIM symbol that represents the gravitational constant. It
normally is printed as G. If you change this symbol, you should start a new analysis
with the reset command to properly initialize AUTOSIM. This global is a member of a
list assigned to another global: *universal-constants*.
See Also
*acceleration-due-to-gravity*, *universal-constants*, addgravity, reset

*include-path*
string
Description
This is the name of a subdirectory with the include files needed by AUTOSIM to write a
Fortran simulation program. When AUTOSIM goes to access an include file, it
concatenates the string assigned to *include-path* with a file name to obtain a
complete path name.
This string should end with the directory delimiter character for your machine. For a
UNIX machine or IBM PC, use the slash character / as a delimiter, e.g.,
"c:/autosim/includes/". For a Macintosh, use the colon character :, e.g., "Hard
disk:AUTOSIM:includes:".
The includes directory may include other directories with sets of exception files,
tailored for specific compilers. Another global, *compiler*, is used to identify which
one of these is also to be searched as include files are needed.
See Also
*compiler*

*initnr-eqs*
protected equation structure
Description
*initnr-eqs* is set to an equation set that contains the equations appearing in the
subroutine or function INITNR.
See Also
eqs, Section 2.2

*int-vars*
Boolean

8 122

8.3 Globals

AUTOSIM 2.0

Description
*int-vars* determines whether intermediate variables are introduced as the multibody
system is analyzed. The normal value is T. If this is set to NIL, then the equations are left
completely in terms of original parameters and state variables. For anything except an
extremely simple system, setting *int-vars* to NIL will result in much more
complicated equations, which will take much longer to derive, and which will possible
use up all your computer memory without ever finishing.
In some of the procedures used within AUTOSIM, this variable is temporarily turned
off. If processing is aborted, it is important to return to the top-level break-loop in Lisp
to revert to the intended value of this and other global variables.

*iprint*
symbol
Description
This names the Fortran print interval simulation variable defined in the common block
/SYPARS/. If you change this symbol, you should start a new analysis with the reset
command to properly initialize AUTOSIM.
See Also
reset, Section 2.4

*jac-symbol*
symbol
Description
This names the Jacobian array in subroutine INITNR. It is nominally JAC. If you change
this symbol, you should start a new analysis with the reset command to properly
initialize AUTOSIM.
See Also
reset, Section 2.4

*known-speeds*
protected array
Description
*known-speeds* is set to the array whose elements are the right-hand sides (relative
to the equal sign) of the implicit kinematical equations,
.
Sq =v

8 123

8.3 Globals

AUTOSIM 2.0

.
where q is a 1-dimensional array of the derivatives of the generalized coordinates. The
matrix S and the array v are computed by the kinematics command and assigned to
the globals *speed-matrix* and *known-speeds*, respectively. The number of
elements in *known-speeds* is the number of generalized coordinates for the
multibody system.
See Also
*speed-matrix*, kinematics

*length*
units symbol
Description
*length* is set to symbol that represents units of length in a units expression. The
default representation is L. The printed name of units involving length depends on the
units system.
See Also
get-units, set-units

*linear-a*
protected matrix
Description
Matrix A after a linear analysis by the linear command.
See Also
linear

*linear-b*
protected matrix
Description
Matrix B after a linear analysis by the linear command.
See Also
linear

*linear-c*
protected matrix

8 124

8.3 Globals

AUTOSIM 2.0

Description
Matrix C after a linear analysis by the linear command.
See Also
linear

*linear-d*
protected matrix
Description
Matrix D after a linear analysis by the linear command.
See Also
linear

*mass-matrix*
protected matrix
Description
*mass-matrix* is set to a square matrix whose elements are coefficients on the lefthand side (relative to the equal sign) of the implicit dynamical equations,
.
Mu =f
.
where u is a 1-dimensional array of the derivatives of the generalized speeds. The
matrix M and the array f are computed by the command dynamics unless the order-n
option is used, and are assigned to the globals *mass-matrix* and *force-array*,
respectively. The number of elements in *force-array* is the number of degrees of
the multibody system.
See Also
*force-array*, dynamics

*mass-matrix-symbol*
symbol
Description
This names the mass matrix in the simulation code if certain values are specified for the
optional :formalism keyword in the dynamics command. It is nominally M. If you
change this symbol, you should start a new analysis with the reset command to
properly initialize AUTOSIM.
See Also
dynamics, reset, Section 2.4
8 125

8.3 Globals

AUTOSIM 2.0

*moments*
protected list
Description
*moments* is a list of all of the moments in the multibody model. The elements of this
list are all AUTOSIM moment objects. They can be printed using the command printmoments.
See Also
moment, print-moments

*multibody-system-name*
string
Description
*multibody-system-name* is a string that you can set to name the multibody
system. The name appears in some of the documentation generated for the simulation
code, and in the default values for the header printed on the screen by a Fortran program
(see *screen-header*) and at the top of echo files generated by a Fortran simulation
program (see echo-header*).
See Also
*echo-header*, *screen-header*

*no-pcs*
Boolean
Description
*no-pcs* determines whether intermediate variables are introduced for constants. The
normal value is NIL. If this is set to T, then the equations are left completely in terms of
original parameters. For anything except an extremely simple system, setting *no-pcs*
to T will result in much more complicated equations, which will take much longer to
derive.
In some of the procedures used within AUTOSIM, this variable is temporarily turned
on. If processing is aborted, it is important to return to the top-level break-loop in Lisp
to revert to the intended value of this and other global variables.
This setting has no effect if the global *int-vars* is set to NIL.
See Also
*int-vars*

8 126

8.3 Globals

AUTOSIM 2.0

*no-zees*
Boolean
Description
*no-zees* determines whether intermediate variables are introduced for variables. The
normal value is NIL. If this is set to T, then the significance of the state variables is
clearer from inspection. For simple systems, equations obtained with *no-zees* set T
are sometimes simpler than when *no-zees* is NIL. However, for complex system,
setting *no-zees* to T nearly always results in much more complicated equations,
which take much longer to derive.
During normal processing within AUTOSIM, this variable is often turned on. If
processing is aborted, it is important to return to the top-level break-loop in Lisp to
revert to the intended value of this and other global variables.
This setting has no effect when the global *int-vars* is set to NIL.
See Also
*int-vars*

*number-of-adds*
protected number
Definition
This variable is set to the total number of add and subtract operations required in the
loop to calculate derivatives of the state variables.

*number-of-funcs*
protected number
Definition
This variable is set to the total number of function and subroutine calls (including sines
and cosines) required in the loop to calculate derivatives of the state variables.

*number-of-muls*
protected number
Definition
This variable is set to the total number of multiply, divide, and exponent operations
required in the loop to calculate derivatives of the state variables.

8 127

8.3 Globals

AUTOSIM 2.0

*pc-symbol*
symbol
Description
This names an array used in the simulation code to store constant expressions that are
precomputed. It is nominally PC. If you change this symbol, you should start a new
analysis with the reset command to properly initialize AUTOSIM. The equations
defining these expressions are assigned to the global *pre-comp*.
See Also
*pre-comp*, reset, Section 2.4

*points*
protected list
Description
*points* is a list of all of the points in the multibody model. The elements of this list
are all AUTOSIM point objects. They can be printed using the command printpoints.
See Also
point, print-points

*pre-comp*
protected equation structure
Description
*pre-comp* is set to an equation set that contains the assignments of all constants
computed from parameters. These computations are made during the start of the
simulation (i.e., they are precomputed) rather than being made in the simulation loop.
The symbol used for the new intermediate terms is determined by the global *pcsymbol*. You can view the equations by typing in *pre-comp*.
Example
For the example four-bar linkage, *pre-comp* has the value:
? *pre-comp*
PC(1) = XP6 -XP8
PC(2) = YP6 -YP8
PC(3) = XP1 -XP3
PC(4) = YP1 -YP3
PC(5) = -XP6 + XP3
PC(6) = -YP6 + YP3
PC(7) = -XP6 + XP5
PC(8) = -YP6 + YP5
PC(9) = XP6 -XP1
PC(10) = YP6 -YP5

+
+
+
+

PC(1)
PC(2)
PC(1)
PC(2)

8 128

8.3 Globals

AUTOSIM 2.0

PC(11) = YP6 -YP1

See Also
*pc-symbol*, eqs

*print-aliases*
Boolean
Description
*print-aliases* determines whether all aliases in a name structure are printed. The
normal value is NIL. If this is set to T, then point symbols and some names are printed
with all of the names that have been encountered. This capability is sometimes helpful for
debugging your AUTOSIM inputs. Otherwise, the value should be set NIL.

*q-symbol*
symbol
Description
This names an array used in the simulation code to store the generalized coordinates. It is
nominally Q. If you change this symbol, you should start a new analysis with the reset
command to properly initialize AUTOSIM.
See Also
reset, Section 2.4

*qp-symbol*
symbol
Description
This names an array used in the simulation code to store the derivatives of the
generalized coordinates. It is nominally QP. If you change this symbol, you should start a
new analysis with the reset command to properly initialize AUTOSIM.
See Also
reset, Section 2.4

*safe-divide*
Boolean

8 129

8.3 Globals

AUTOSIM 2.0

Description
1
When not NIL, all numerical divides of the form x are printed with the form
1
, where is the value assigned to the global *epsilon*. This
sign(max(, abs(x)), x)
prevents a numerical divide by zero. Equations generated by AUTOSIM are always
printed using the current value of *safe-divide*: you do not have to repeat an
analysis to generate new equations after changing that value of *safe-divide*.
See Also
Sections 2.4, 7.2, *epsilon*

*safe-sqrt*
Boolean
Description
When not NIL, all numerical square roots of the form sqrt(x) are printed the form
sqrt(abs(x)). This prevents an illegal argument when numerical precision limits might
result in xhaving a very small negative value. Equations generated by AUTOSIM are
always printed using the current value of *safe-sqrt*: you do not have to repeat an
analysis to generate new equations after changing that value of *safe-sqrt*.
See Also
Sections 2.4, 7.2

*screen-header*
list
Description
*screen-header* is a list of strings to write on the screen when the simulation code
starts. This list appears as a sequence of WRITE statements in the MAIN program
module. If *screen-header* is NIL (the normal value after reset), a header is
created when a simulation program is written using the string assigned to the global
*multibody-system-name*. The setsym command is used to assign a list of
strings to a variable.
Example
? (setsym *screen-header*
("Welcome to the four-bar linkage simulation program!"
"this version created September 1, 1992"
"University of Michigan"))
("Welcome to the four-bar linkage simulation program!" "this version
created September 1, 1992" "University of Michigan")

See Also
*multibody-system-name*, reset, setsym

8 130

8.3 Globals

AUTOSIM 2.0

*sin-symbol*
symbol
Description
This names an array used in the simulation code to store SIN functions of generalized
coordinates. It is nominally S. If you change this symbol, you should start a new analysis
with the reset command to properly initialize AUTOSIM.
See Also
reset, Section 2.4

*small-order*
number
Description
*small-order* establishes the threshold for throwing out small terms. When two
expressions are added, their small-order properties are compared. If the difference is
greater than or equal to *small-order*, the smaller term is dropped. The default
value of *small-order* is two. That is, second-order (and smaller) terms are dropped.
This only applies to variables that have been declared small by the analyst either with a
:small-angles or :small-translations argument in add-body, or with the
small command. The simplifications are not made if the global *drop-smallterms* is NIL.
Example
Consider the following interactive session, generating power series expansions for the
cosine function.
? (small x)
SMALL
? (setsym *expand* t *small-order* 4)
4
? !"cos(x)"
(1.0 -0.5*X**2)
? (setsym *small-order* 6)
6
? !"cos(x)"
(1.0 -0.5*X**2 + 4.166666666666666E-2*X**4)
?

See Also
*absolute-drop*, *drop-small-terms*, add, add-body, large, small

*speed-matrix*
protected matrix

8 131

8.3 Globals

AUTOSIM 2.0

Description
*speed-matrix* is set to a square matrix whose elements are coefficients on the lefthand side (relative to the equal sign) of the implicit kinematical equations,
.
Sq =v
.
where q is a 1-dimensional array of the derivatives of the generalized coordinates. The
matrix S and the array v are computed by the kinematics command and assigned to
the globals *speed-matrix* and *known-speeds*, respectively. The number of
elements in *known-speeds* is the number of generalized coordinates for the
multibody system.
See Also
*known-speeds*, kinematics

*startt*
symbol
Description
This names the Fortran simulation start time, contained in the common block /SYPARS/.
If you change this symbol, you should start a new analysis with the reset command to
properly initialize AUTOSIM.
See Also
reset, Section 2.4

*step*
symbol
Description
This names the Fortran simulation integration step size, contained in the common block
/SYPARS/. If you change this symbol, you should start a new analysis with the reset
command to properly initialize AUTOSIM.
See Also
reset, Section 2.4

*stiff-integrator*
Boolean
Description
*stiff-integrator* determines the type of integration subroutine installed in a
Fortran simulation program. If NIL, a fixed-step, second-order Runge-Kutta (RK2)

8 132

8.3 Globals

AUTOSIM 2.0

integrator is used. This integrator is well suited for many applications involving
discontinuities, or systems in which the response if the result of a continuous forcing
excitation. If T, an integration subroutine is installed that has the RK2 method, an
ADAMS multi-step, multi-order algorithm and two GEAR multi-step, multi-order
algorithms for stiff systems.
The *stiff-integrator* setting is used during the execution of the finish
command to set up subroutines needed for the integrator. Changes to the *stiffintegrator* setting have no effect after the finish command has been applied, until
after the next reset.
See Also
finish, reset

*stopt*
symbol
Description
This names the Fortran simulation stop time, contained in the common block /SYPARS/.
If you change this symbol, you should start a new analysis with the reset command to
properly initialize AUTOSIM.
See Also
reset, Section 2.4

*symbols*
protected list
Description
*symbols* is a list of all of the AUTOSIM symbols (sym objects) that have been
created since the last reset. The function find-sym manages this list. They can be
printed with the command print-symbols.
See Also
print-symbols, sym

*target-language*
symbol
Description
*target-language* determines how some of the AUTOSIM data objects are printed
with functions such as print-bodies, print-coordinates, etc. In the present
version, the valid values for this variable are: fortran, acsl, adsim, c, and rtf.

8 133

8.3 Globals

AUTOSIM 2.0

*time*
units symbol
Description
*time* is set to symbol that represents units of time in a units expression. The default
representation is T. The printed name of units involving time depends on the units
system.
See Also
get-units, set-units, Section 2.4

*time-eqs*
protected equation structure
Description
*time-eqs* is set to an AUTOSIM data structure that contains the equations used to
compute (1) the derivatives of the independent generalized speeds, (2) variables defined
in the UPDATE subroutine block, and (3) output variables. Most of the array elements
appear in the /DYVARS/ common block when the target language is Fortran or ACSL.
You can view the equations by typing in *time-eqs*. The printed appearance of
the equations depends on the current setting for *target-language*. To see the most
recent equations, use the lifo command.
Example
*time-eqs*
S(1)
S(2)
S(3)
C(1)
C(2)
C(3)
C

=
=
=
=
=
=

SIN(Q(1))
SIN(Q(2))
SIN(Q(3))
COS(Q(1))
COS(Q(2))
COS(Q(3))

define terms for constraint equations


Z(1) = PC(3)*C(1)
Z(2) = PC(4)*S(1)
Z(3) = Z(1) -Z(2)
...

See Also
*target-language*, lifo

*u-symbol*
symbol

8 134

8.3 Globals

AUTOSIM 2.0

Description
This names an array used in the simulation code to store the generalized speeds. It is
nominally U. If you change this symbol, you should start a new analysis with the reset
command to properly initialize AUTOSIM.
See Also
reset, Section 2.4

*unit-system*
symbol
Description
*unit-system* is symbol that indicates which units system is currently in effect. It is
set by the si, mks, and in-lb commands.
See Also
in-lb, mks, si

*unit-vector-brackets*
string
Description
This variable is set to a 2-character string containing the bracket characters that will be
used to print unit vectors. When interpreting an f-string input, AUTOSIM always
recognizes [, ], <, and > as unit-vector brackets. It also recognizes the two characters in
the string *unit-vector-brackets*. The indices of the unit-vector are printed
according to the global *unit-vector-indices*.
Example
Consider the following interactive session involving the reading and printing of nx.
? !"[n1]" ; square brackets identify unit-vector
[nx]
? !"<n1>" ; so do angle brackets
[nx]
? !"{n1}" ; curly brackets are just part of a scalar symbol
{N1}
? (setsym *unit-vector-brackets* "{}")
"{}"
? !"[n1]" ; now the unit-vector prints with curly brackets
{nx}

See Also
*unit-vector-indices*

8 135

8.3 Globals

AUTOSIM 2.0

*unit-vector-indices*
string
Description
This variable is set to a 3-character string containing the index characters that will be
used to print unit vectors. When interpreting an f-string input, AUTOSIM always
recognizes 1, 2, 3, X, Y, and Z as unit-vector indices. It also recognizes the three
characters in the string *unit-vector-indices*. The surrounding brackets of the
unit-vector are printed according to the global *unit-vector-brackets*.
Example
Consider the following interactive session involving the reading and printing of nx.
? !"[n1]" ; index 1 works
[nx]
? !"[nx]" ; so does index X
[nx]
? !"[ni]" ; but not index i
Error(FIND-UV): invalid index: [NI]
Aborted
? (setsym *unit-vector-indices* "IJK")
"IJK"
? !"[n1]" ; 1 and X still work, but it prints using IJK
[ni]
? !"[ni]" ; indices IJK work for inputs now
[ni]

See Also
*unit-vector-brackets*

*universal-constants*
list
Description
*universal-constants* is a list of constants that will be included as Fortran
parameters in some of the subroutines written by AUTOSIM. This list normally consists
of the global variables *degree* and *gees*.
Example
With in-lb units, the list *universal-constants* has the value (G DR) and
leads to the following PARAMETER statement:
PARAMETER

(G = 386.2, DR = 57.29577951308232)

See Also
*gees*, *degree*

8 136

8.3 Globals

AUTOSIM 2.0

*up-symbol*
symbol
Description
This names an array used in the simulation code to store the derivatives of the
generalized speeds. It is nominally UP. If you change this symbol, you should start a new
analysis with the reset command to properly initialize AUTOSIM.
See Also
reset, Section 2.4

*use-x-derivative-in-forces*
Boolean
Description
This variables determines the type of replacement expression substituted for V in the
force magnitude provided with the commands add-line-force and add-strut. If
NIL, the dummy variable V is replaced with a relative velocity expression that contains
generalized speeds and no derivatives. If T, the replacement expression is the derivative
of the replacement expression for X, the dummy variable for deflection.
Why a choice? For linear analyses, the force equation should not contain derivatives
of state variables. Therefore, when describing a model for linear analysis, this variable
should be set NIL. For nonlinear simulations, simpler expressions are sometimes
obtained using the derivative of the deflection.
Example
Consider a body with 6 DOF, and a linear damping force applied to the origin in the nz
direction.
(reset)
(add-body s :translate (x y z) :body-rotation-axes (x y z)
:cm-coordinates (cmx cmy cmz))
(add-line-force f1 :direction [nz] :point1 s0 :magnitude "-d*v")

If the value of *use-x-derivative-in-forces* is NIL, the expression derived by


AUTOSIM for the force magnitude is
-d ((u3 -cmy u4 + cmx u5) c4 c5 + (u2 + cmz u4 -cmx u6) (c6 s4 + c4 s5 s6) + (u1 -cmz u5 +
cmy u6) (-c4 c6 s5 + s4 s6))
However, if the value of *use-x-derivative-in-forces* is T, the expression for
the force magnitude is
.
-d q 3
In this case, the expression involving the coordinate derivative is algebraically simpler.

8 137

8.3 Globals

AUTOSIM 2.0

See Also
add-line-force, add-strut, *v-symbol*

*verbose*
Boolean
Description
*verbose* determines whether the equations of motion generated by AUTOSIM are
fully commented.

*x-symbol*
symbol
Description
This defines the default dummy variable that can optionally be used in the add-lineforce and add-strut commands to represent displacement between two points. It has
a nominal value of X. This variable can be changed at any time. It is used only in the
add-line-force and add-strut commands, and the current value is employed only
if the :x keyword argument is not used.
See Also
add-line-force, add-strut, Section 2.4

*x0-symbol*
symbol
Description
This defines the default dummy variable that can optionally be used in the add-lineforce and add-strut commands to represent the nominal (static) displacement
between two points. It has a nominal value of X0. This variable can be changed at any
time. It is used only in the add-line-force and add-strut commands, and the
current value is employed only if the:x0 keyword argument is not used.
See Also
add-line-force, add-strut, Section 2.4

*v-symbol*
symbol
Description
This defines the default dummy variable that can optionally be used in the add-lineforce and add-strut commands to represent the rate of displacement between two
8 138

8.3 Globals

AUTOSIM 2.0

points. It has a nominal value of V. This variable can be changed at any time. It is used
only in the add-line-force and add-strut commands, and the current value is
employed only if the :v keyword argument is not used.
See Also
add-line-force, add-strut, Section 2.4

*z-symbol*
symbol
Description
This names an array used in the simulation code to store variable expressions. It is
nominally Z. If you change this symbol, you should start a new analysis with the reset
command to properly initialize AUTOSIM. The equations defining these expressions are
assigned to the global *time-eqs*. The new terms are not introduced unless the global
*int-vars* is T and *no-zees* is NIL.
See Also
*int-vars*, *no-zees*, *time-eqs*, reset, Section 2.4

*zi-symbol*
symbol
Description
This names an array in the simulation code to store intermediate variables in the
subroutine INITNR, used to determine an initial configuration for systems with computed
coordinates. It is nominally ZI. If you change this symbol with the setsym command,
the reset function must be applied before the next analysis is started.
See Also
reset, Section 2.4

8.4 Data Types


This section is of interest only if you are writing new Lisp code to extend AUTOSIM.
If you are not programming in Lisp, you dont need to be concerned with any of the stuff
that follows. On the other hand, if you are programming in Lisp, it may be helpful to
know the names of the data types used in AUTOSIM, and a few details of their structure.
AUTOSIM is written in an object-oriented programming style in the Common Lisp
language as defined in the first edition of Common Lisp: the Language by Guy Steele
(Digital Press, 1984). It uses Lisp structures to define new types of data objects. Table
8.4.1 lists all of the new structure types defined within AUTOSIM. The data types are
divided into three categories: those supporting the computer algebra, those describing the

8 139

8.3 Globals

Type
atan
body
call
cos
declaration
dyad
eqs
expression
force
forcem
func
indexed-sym
kane
matrix-sym
maxmin
moment
name
node
outvar
point
power
prod
rf
sign
sin
sum
sym
trig
uv

AUTOSIM 2.0
Table 8.4.1. AUTOSIM data types.
Parent
Category Description
func
algebra
arc-tangent function
node
multibody rigid body, reference frame, coord. system
code
external subroutine or equations
trig
algebra
cosine function
code
declaration of variables, arrays, parameters
expression
algebra
dyad
code
set of assignment statements (equations)
algebra
symbolic algebraic expression
forcem
multibody force
multibody force or moment
expression
algebra
external function
sym
algebra
indexed symbol (1-D array element)
multibody set of variables associated with a body
indexed-sym
algebra
double-indexed symbol (matrix element)
func
algebra
min or max function
forcem
multibody moment
code
printed name of specific object
multibody tree structure
code
output Fortran simulation variable
multibody point in multibody system
expression
algebra
expression raised to a numerical power
expression
algebra
product of number and list of expressions
node
multibody set of reaction force variables for a body
func
algebra
sign function
trig
algebra
sin function
expression
algebra
sum of expressions and number
expression
algebra
AUTOSIM symbol
func
algebra
trig function
expression
algebra
unit-vector

multibody system, and those describing numerical analysis code. Some data types
inherits from another type of structure, listed in the table in the parent column. The data
types shown in bold typeface are described in more detail in the alphabetical listings that
follow.
Each structure has a set of slots that contain data associated with the structure. A
function exists to access each slot. The access functions are named by appending the slot
name to the type data, e.g., the function body-symbol returns the data in the symbol
slot of a body structure. The contents of these slots can be inspected and used in Lisp
functions that you write, but you should not change them. Each access function takes a
single argument, which must be an object of the appropriate type. For example, bodysymbol expects an argument that is of the body data type.

8 140

8.3 Globals

AUTOSIM 2.0

In the following listing, the most important slots are listed and defined. You can also
view the slots of a structure interactively in AUTOSIM using the Lisp inspect
function.

body
An object that represents (1) a moving reference frame, (2) a coordinate system fixed in
that reference frame, and (3) a rigid body with mass properties, also fixed in the reference
frame.
Description
A body structure has slots that contain many sorts of information about the body. Some
of these are listed and defined in Table 8.4.2. A body is created with the command addbody. All of the bodies in the model are linked through parent and children slots. The
body representing the inertial reference is assigned to the global *bodies*, and all
bodies in the multibody model can be accessed through the children slot of *bodies*.
An easy way to view most of the slots of a particular body is with the command
print-body. A printout for all bodies is obtained with the command print-bodies.
See Also
*bodies*, add-body, arg-body, find-body, print-bodies, print-body

call
a call to an external routine or an externally defined equation
Description
A call is a data type used to represent external code, either as a call to an external
subroutine (Fortran) or function (C, ADSIM), or as an equation introduced explicitly by
the modeler. A few of slots of a call are listed in Table 8.4.3. A call object is created
by the add-subroutine and add-equation commands. The printed representation
of a call depends on the current value of the global *target-language*. In the
case of a Fortran subroutine, the call prints as a CALL statement. In the case of an
external C function, it prints as a lone function statement. If created by the addequation command, the name slot is assigned the symbol equation, and the call is
printed like an assignment equation. All of the call objects are placed on a list assigned
to the global variable *external-subroutines*. They are copied from that list into
appropriate equation sets during the analysis initiated with the finish command.
See Also
*external-subroutines*, *target-language*, add-equation, addsubroutine, finish

8 141

8.3 Globals

Slot Name
symbol
name
parent
children
uvs
cos-matrix
level
0-point
joint-point
cm-point
cmc-point
basis

AUTOSIM 2.0
Table 8.4.2. Some of the slots in a BODY.
Type
Definition
symbol
symbol for user to reference the body.
string
description of body.
body
parent body in tree topology.
list
list of bodies that have this body as their parent.
array
3 unit-vectors that define 1-2-3 axis directions of
coordinate system.
array
direction cosine matrix relating the unit-vectors of
this body to those of its parent.
number
level of the body in tree.
point
origin of coordinate system of this body.
point
point in parent body that coincides with the 0-point
when all generalized coordinates are zero.
point
center of mass of this body alone.
point
center of mass of composite body.
expression basis dyadic (dotting a vector with this dyadic
projects the vector into the basis of this body).
expression mass of body alone.
expression mass of composite body.
expression inertia dyadic for composite body.
array
inertia matrix for this body alone.

mass
mass-c
inertia
inertiamatrix
cmarray
3-element array of coordinates of mass center of this
coordinates
body alone.
rotationlist
directions associated with rotational degrees of
directions
freedom of body with respect to its parent
translationlist
directions associated with translational degrees of
directions
freedom of body with respect to its parent
translational
list
directions associated with translational generalized
-speedspeeds introduced for body
directions
rotationlist
generalized coordinates for joint rotations
coordinates
rotationlist
generalized speeds associated with body
speeds
translationlist
generalized coordinates for joint translations
coordinates
translationlist
generalized speeds associated with body
speeds
Note: the fixed children of body B are children whose mass centers are fixed in B
and whose masses can therefore be lumped with the inertial properties of B.
8 142

8.3 Globals

AUTOSIM 2.0
Table 8.4.3. Some of the slots in a CALL.
Type
Definition
symbol
(1) name of external routine, or, (2) equation
symbol
location of external code
list
(1) list of arguments to subroutine, or, (2) symbol
and expression for equation: symbol = expression
string
text of comment printed before external code
symbol
keyword to locate code used in ECHO or INPUT
subroutines generated by AUTOSIM
number
no. of columns to indent external code (default=0)

Slot Name
name
where
args
comment
keyword
indent

declaration
a declaration of variables, parameters, or arrays
Description
A declaration is a data type used to represent definitions of variables, parameters, or
arrays. It is normally created by the add-variables command. Some of the slots are
listed in Table 8.4.4. A declaration object is created by the add-variables
command. The printed representation of a declaration depends on (1) the current
value of the global *target-language*, (2) the type of expressions in the list vars,
and (3) whether type is a symbol or list. All of the declaration objects are placed on a
list assigned to the global variable *declarations*. They are printed at the starts of
subroutines and functions generated by AUTOSIM.

Slot Name
where
type
vars

Table 8.4.4. Some of the slots in a DECLARATION.


Type
Definition
symbol
location of declaration
symbol or list type of data being declared
list
list of variables or parameters being declared

If all elements in the list vars are simple symbols, then the declaration is printed
as one statement in the target language. If some are indexed-syms, then they are also
dimensioned in the printed representation. In Fortran and ACSL, two statements are
printed: a type declaration and a DIMENSION statement.
If type is a list, where the second element is the symbol parameter, then the
variables are printed as parameters. The values are obtained by the current default
numerical values assigned to the variables.
See Also
*declarations*, *target-language*, add-variables

8 143

8.3 Globals

AUTOSIM 2.0

eqs
a set of assignment statements
Description
An eqs is the fundamental form of data used to store equations in AUTOSIM. An eqs
prints as a set of equations in the target computer language, typically Fortran. All of the
equations that go into the simulation code are stored in a few global variables that point
to eqs structures. A few of these are listed in Table 8.4.3.

Slot Name
list
root-sym

Global
*force-eqs*
*initnr-eqs*
*pre-comp*
*time-eqs*

Table 8.4.5. Some of the slots in an EQS.


Type
Definition
list
list of syms and calls
symbol
symbol used for new intermediate variables created
for the eqs (e.g., Z, PC)
Table 8.4.6. Some global equation structures.
Description
equations for forces and moments
equations in subroutine INITNR
equations for pre-computed constants
equations for variables

expression
a symbolic (i.e., non-numeric) algebraic entity that is manipulated by AUTOSIM
Description
The computer algebra capabilities of AUTOSIM support numbers and symbols. All
symbolic expressions are data types based on the expression structure. Some of the
slots in an expression are listed in Table 8.4.7.

8 144

8.3 Globals

Slot Name
const-or-var
dxdt
name
small-order
sort-code
type
units

AUTOSIM 2.0
Table 8.4.7. Some of the slots in an EXPRESSION.
Type
Definition
symbol
identifies whether expression is constant or variable
expression derivative of expression
name
name of expression
number
order of smallness of expression
number
number used to sort expressions
symbol
identifies whether expression is scalar or vector
expression expression involving units symbols

force
a force in the multibody model
Description
A force object has slots containing information about a force in the model. Some of the
slots are listed in Table 8.4.8. Force objects are created by the commands add-lineforce and add-strut. All forces in a model are stored in a list assigned to the global
variable *forces*.

Slot Name
symbol
name
direction
magnitude
body1
body2
vector
point1
point2

Table 8.4.8. Some of the slots in a FORCE.


Type
Definition
symbol
symbol used to identify force
name
name of force
expression vector defining direction of force line of action
expression scalar defining force magnitude
body
body upon which force acts with positive magnitude
body
body upon which force acts with negative magnitude
expression vector expression: direction magnitude
point
point on line of action
point
point on line of action

See Also
*forces*, add-line-force, add-strut

func
object that represents an external function

8 145

8.3 Globals

AUTOSIM 2.0

Description
A func is a type of expression that is used to represent a function that is not applied
symbolically, but is written into the simulation code where it can later be applied
numerically. Table 8.4.9 lists some of the slots in a func.

Slot Name
function
args
const-or-var
dxdt
name
small-order
sort-code
type
units

Table 8.4.9. Some of the slots in a FUNC.


Type
Definition
symbol
function name
list
list of arguments to function
symbol
identifies whether expression is constant or variable
expression derivative of expression
name
name of expression
number
order of smallness of expression
number
number used to sort expressions
symbol
identifies whether expression is scalar or vector
expression expression involving units symbols

See Also
expression

sym
object that represents a scalar indexed symbol or array element
Description
An indexed-sym is a type of sym that is used to represent an array element in the
target language. Table 8.4.10 lists the slots in an indexed-sym structure. The first two
slots are specific to the indexed-sym data type, the next three slots are inherited from
the sym data type, and the others are inherited from the expression data type.

8 146

8.3 Globals

Slot Name
i
category
symbol
exp
default
const-or-var
dxdt
name
small-order
sort-code
type
units

AUTOSIM 2.0
Table 8.4.10. Some of the slots in an INDEXED-SYM.
Type
Definition
number or
index
expression
symbol
symbol
printed representation of symbol
expression expression assigned to symbol
number
default value of symbol
symbol
identifies whether expression is constant or variable
expression derivative of expression
name
name of expression
number
order of smallness of expression
number
number used to sort expressions
symbol
identifies whether expression is scalar or vector
expression expression involving units symbols

See Also
expression, sym

moment
a moment in the multibody model
Description
A moment object has slots containing information about a moment in the model. Some
of the slots are listed in Table 8.4.11. Moment objects are created by the command
add-moment. All moments in a model are stored in a list assigned to the global variable
*moments*.

Slot Name
symbol
name
direction
magnitude
body1
body2
vector

Table 8.4.11. Some of the slots in a FORCE.


Type
Definition
symbol
symbol used to identify moment
name
name of moment
expression vector defining direction of moment
expression scalar defining momentmagnitude
body
body upon which moment acts with positive magnitude
body
body upon which momentacts with negative magnitude
expression vector expression: direction magnitude

See Also
*moments*, add-moment

8 147

8.3 Globals

AUTOSIM 2.0

name
object that contains a set of strings.
Description
One of the strings in the object is printed whenever the name appears. Name objects are
used in place of symbols and strings when an object might have several symbols or
strings that are all valid. As possible names are created by AUTOSIM, they are added to
the list in the name. Each string has an associated index. The name object contains a
single slot, names, that contains a list. Each element of the list is a cons of a numerical
index and a string. For example, the names value for the point o is
((2 . "NJ") (2 . "N0") (1 . "fixed origin"))
The printed representation of the name depends of the value of the global *printaliases*. When *print-aliases* is NIL, the string with the lowest index is
printed. For example, the printed name of point o is fixed origin.
The name of an expression or other AUTOSIM data object can be set using the
command set-names, or retrieved using the function get-name.
See Also
*print-aliases*, get-name, set-names

point
object that represents a point associated with a body.
Description
A point is one of the basic building blocks used in AUTOSIM to represent a multibody
system. Points required by AUTOSIM for the most basic analyses are introduced
automatically with the add-body command. Additional points of interest can be
added with the add-point command. Table 8.4.12 lists some of the slots of a point
data structure.

Slot Name
body
coordinates
name
symbol

Table 8.4.12. Some of the slots in a POINT.


Type
Definition
body
body associated with point
list
list of three coordinates of point
name
name of point (for documenations)
name
name of point (for AUTOSIM commands)

A point includes a symbol and a name. Both are set to name structures, so that the
same point can be identified with different names and symbols.

8 148

8.3 Globals

AUTOSIM 2.0

All points in the system can be viewed with the function print-points. The
point function is used to obtain the point corresponding to a given symbol, and a
function called arg-point is used in Lisp functions to check arguments when a point
is expected. All of the points are automatically put into a list assigned to the global
*points*.
See Also
*points*, add-point, add-body, arg-point, find-point, name, printpoints

power
object that represents a scalar expression raised to a numerical power
Description
A power is a type of expression that is used to represent a scalar expression raised to
a numerical power. Table 8.4.13 lists the slots in a power structure. The first two slots
are specific to the power data type, and the others are inherited from the expression
data type.

Slot Name
base
power
const-or-var
dxdt
name
small-order
sort-code
type
units

Table 8.4.13. Some of the slots in a POWER.


Type
Definition
expression printed representation of symbol
number
exponent of power
symbol
identifies whether expression is constant or variable
expression derivative of expression
name
name of expression
number
order of smallness of expression
number
number used to sort expressions
symbol
identifies whether expression is scalar or vector
expression expression involving units symbols

See Also
expression

prod
object that represents a product of a number and one or more expressions
Description
A prod is a type of expression that is used to represent a scalar or vector product.
Table 8.4.14 lists some of the slots. The first two slots are specific to the prod data type,
and the others are inherited from the expression data type.

8 149

8.3 Globals

Slot Name
coef
factors
const-or-var
dxdt
name
small-order
sort-code
type
units

AUTOSIM 2.0
Table 8.4.14. Some of the slots in a PROD.
Type
Definition
number
numerical coefficient for product
list
list of expressions that are factors in the product
symbol
identifies whether expression is constant or variable
expression derivative of expression
name
name of expression
number
order of smallness of expression
number
number used to sort expressions
symbol
identifies whether expression is scalar or vector
expression expression involving units symbols

See Also
expression

sum
object that represents a sum of one or more expressions
Description
A sum is a type of expression that is used to represent a scalar or vector sum. Table
8.4.15 lists some of the slots. The first slot is specific to the sum data type, and the others
are inherited from the expression data type.

Slot Name
terms
const-or-var
dxdt
name
small-order
sort-code
type
units

Table 8.4.15. Some of the slots in a SUM.


Type
Definition
list
list of terms in summation
symbol
identifies whether expression is constant or variable
expression derivative of expression
name
name of expression
number
order of smallness of expression
number
number used to sort expressions
symbol
identifies whether expression is scalar or vector
expression expression involving units symbols

See Also
expression

sym
object that represents a scalar symbol

8 150

8.3 Globals

AUTOSIM 2.0

Description
A sym is a type of expression that is used to represent a scalar symbol. Table 8.4.16
lists the slots in a sym structure. The first three slots are specific to the sym data type,
and the others are inherited from the expression data type.

Slot Name
symbol
exp
default
const-or-var
dxdt
name
small-order
sort-code
type
units

Table 8.4.16. Some of the slots in a SYM.


Type
Definition
symbol
printed representation of symbol
expression expression assigned to symbol
number
default value of symbol
symbol
identifies whether expression is constant or variable
expression derivative of expression
name
name of expression
number
order of smallness of expression
number
number used to sort expressions
symbol
identifies whether expression is scalar or vector
expression expression involving units symbols

A sym is not the same as a Lisp symbol. A function find-sym is used to obtain the
sym associated with a given Lisp symbol. For example, the form (find-sym 'a)
returns the sym A. All of the AUTOSIM functions and commands automatically apply
find-sym to their arguments when an expression is expected. Hence, the distinction
between a s y m and a symbol is significant only when manipulated AUTOSIM
expressions with standard Lisp operators or when programming in Lisp. Assignment
statements are stored as sym structures with the right-hand side of the assignment in a
slot called exp. To get the expression, if there is one, use the Lisp accessor function symexp. Note that sym-exp will signal an error if you use it with anything but a sym as an
argument.
A list of all of the sym objects is assigned to the global *symbols*. The list can be
printed using the command print-symbols.
See Also
*symbols*, arg-exp, expression, find-sym, print-symbols

uv
object that represents a unit-vector, fixed in one of the bodies of the system
Description
A uv is a type of expression that is used to represent a unit-vector. Some of the slots
are shown in Table 8.4.17. Uvs are created when a new body is introduced with the
command add-body. However, if any of the axes of the coordinate system of the new
body are aligned with the axes of the parent, the uv of the parent is kept. That is, there
will never be two uvs that are by definition always parallel.
8 151

8.3 Globals

AUTOSIM 2.0

Unit-vectors are printed using the name of the body, the enclosing braces defined in
the string assigned to the global *unit-vector-brackets*, and the ith element of
the string assigned to the global *unit-vector-indices*.

Slot Name
body
i
crossproducts
dot-products
const-or-var
dxdt
name
small-order
sort-code
type
units

Table 8.4.17. Some of the slots in a UV.


Type
Definition
body
body in which the uv is defined
number
1, 2, or 3
hash-table table of vector cross products involving this uv
hash-table
symbol
expression
name
number
number
symbol
expression

table of vector dot products involving this uv


identifies whether expression is constant or variable
derivative of expression
name of expression
order of smallness of expression
number used to sort expressions
identifies whether expression is scalar or vector
expression involving units symbols

A function called find-uv is used to obtain the sym with the same printed
representation as a Lisp symbol. For example, the form (find-uv '[nx]) returns
the uv nx. All of the AUTOSIM functions and commands automatically apply find-uv
to their arguments when a uv or vector is expected and a Lisp symbol is encountered.
See Also
*unit-vector-brackets*, *unit-vector-indices*, add-body,
expression, find-uv

8 152

AUTOSIM 2.0

INDEX

! function, 881
* function, 883
** function, 883
*absolute-drop*, 8112
*analysis*, 8113
*angle*, 8113
*bodies*, 8113
*c=*, 8115
*combine-masses*, 8114
*compiler*, xii, 237, 8114
*conserve-memory*, 8115
*cos-symbol*, 237, 8115
*counts*, 8115
*degree*, 237, 8116
*double-precision*, 235, 8116
*drop-small-terms*, 8116
*echo-header*, 236, 8117
*erff-symbol*, 8117, 237
*expand*, 8118
*expand-pcs*, 235, 8118
*extra-lines-in-ERD-file*, 236, 8118
*fast-computed-coordinates*, 235, 8
119
*fm-symbol*, 237, 8119
*force*, 8119
*force-array*, 8120
*force-array-symbol*, 237, 8120
*force-eqs*, 8120
*forces*, 8121
*fortran-implicit*, 8121
*gees*, 237, 8121
*include-path*, xii, 8122

*initnr-eqs*, 8122
*int-vars*, 8122
*iprint*, 237, 8123
*jac-symbol*, 237, 8123
*known-speeds*, 8123
*length*, 8124
*linear-a*, 8124
*linear-b*, 8124
*linear-c*, 8124
*linear-d*, 8125
*mass-matrix*, 8125
*mass-matrix-symbol*, 237, 8125
*moments*, 8126
*multibody-system-name*, 236, 8126
*no-pcs*, 235
*no-pcs*, 8126
*no-zees*, 235, 8127
*number-of-adds*, 8127
*number-of-funcs*, 8127
*number-of-muls*, 8127
*pc-symbol*, 237, 8128
*points*, 8128
*pre-comp*, 8128
*print-aliases*, 8129
*q-symbol*, 237, 8129
*qp-symbol*, 237, 8129
*safe-divide*, 235, 8129
*safe-sqrt*, 235, 8130
*screen-header*, 236, 8130
*sin-symbol*, 237, 8131
*small-order*, 8131
*speed-matrix*, 8131

I1

Index

AUTOSIM 2.0

*startt*, 237, 8132


*step*, 237, 8132
*stiff-integrator*, 235, 8132
*stopt*, 237
*stopt*, 8133
*symbols*, 8133
*target-language*, 8133
*time*, 8134
*time-eqs*, 8134
*u-symbol*, 237, 8134
*unit-system*, 8135
*unit-vector-brackets*, 236, 8135
*unit-vector-indices*, 236, 8136
*universal-constants*, 8136
*up-symbol*, 237, 8137
*use-x-derivative-in-forces*, 8137
*v-symbol*, 8138
*verbose*, 235, 8138
*x-symbol*, 8138
*x0-symbol*, 8138
*z-symbol*, 237, 8139
*zi-symbol*, 237, 8139

add-hidden-parameters command, 815


add-line-force command, 516, 27, 815
add-moment command, 516, 29, 817
add-moments-to-output command, 534,
818
add-out command, 534, 818
add-parameters command, 819
add-point command, 516, 820
add-position-constraint command, 516,
22, 821
add-speed-constraint command, 516,
22, 822
add-speeds-to-output command, 534,
823
add-standard-output command, 534, 8
23
add-state-variable command, 823
add-strut command, 516, 28, 824
add-subroutine command, 826
add-to-erd-header command, 829
add-variables command, 531, 830
ADSIM Code
arrays, 37
computed coordinates, 36
generated by AUTOSIM, 36
writing, 540
algebraic equations
linear, 212
nonlinear, 213
angle function, 885
angular orientation, 514
angular velocity, 514
arg-body function, 886
arg-dir function, 886
arg-exp function, 887
arg-point function, 887
arg-string function, 887
asin function, 888, 888
AUTOSIM
analysis options, 12
commands for building model, 516
commands, 84
data types, 8140
documentation, xi
fuctions supporting commands, 720
functions, 880

+ function, 883
- function, 884
/ function, 884
? command, xi, 87
abs function, 885
acos function, 885
ACSL Code
arrays, 34
common blocks, 35
computed coordinates, 35
generated by AUTOSIM, 32
generated Fortran subroutines, 33
writing, 540
add-accelerations-to-output command,
534, 88
add-body command, 516, 18, 88
add-coordinates-to-output command, 5
34, 812
add-equation command, 531, 812
add-forces-to-output command, 534, 8
14
add-gravity command, 516, 814
I2

Index

AUTOSIM 2.0

generating a program, 540


getting started, xii
modeling with, 53
novel features, ix
sequence of commands, 515
specifying the analysis, 535
syntax, 515
auxiliary coordinate systems, 519
auxiliary variables, 531

contact, 74
continuous simulation languages, 117
continuous simulation, 110
coordinate system, 56
coordinate-system keyword, 820
cos function, 890
cross product function, 16, 890
customizing a program, 538
debugging, 536
declaration data type, 8143
default function, 891
default values, 538
degree of freedom, 510, 78
DIFEQN subroutine, 228
differential algebraic equations (DAEs),
220
dir function, 891
documentation guide, xi
dot product function, 15, 891
dplane function, 892
DR constant, 237
dxdt function, 892
dyad, 58
dyadic, 58
dynamical equations , 111
dynamics analysis, 110
dynamics command, 536, 831
DYVARS common block, 233, 34, 3
4, 5

basis dyadic, 58
basis function, 889
batch operation, 210, 32
body
data type, 8141
definition, 58
describing, 518
body-rotation-axes keyword, 518, 19
C array, 233, 37, 41, 34, 7
C Code
arrays, 241
generated by AUTOSIM, 239
list of functions, 239
writing, 540
call data type, 8141
CALL statement in Fortran 3
category keyword, 822
center of mass point, 59
circular dependencies, 532, 76
closed kinematical loops, 511
cm-coordinates keyword, 519
collisions, 74
combining masses, 710
common blocks, 35
Common Lisp, 712
composite bodies, 519, 710
computational speed, 77
computed coordinates, 19, 214, 520,
821
computer algebra
functions, 880
interactive, 517
settings, 711
conditional LUD, 78
constraints, 510, 710

ECHO subroutine, 224


elapsed-time function, 893
END keyword, 27
ENDTABLE keyword, 27
eqs data type, 8144
equal-exp function, 893
equilibrium analysis, 113
equilibrium command, 536
equilibrium simulation, 834
ERD file, 23, 10
ERRF array, 233, 37, 41, 34
Eulers Equations, 112
examples
4-bar linkage, 17
spacecraft, 17
I3

Index

AUTOSIM 2.0

vehicle ride model, 16


expand function, 894
expression data type, 8144
extra coordinates, 520
extra speeds, 521

using, 23
writing, 540
friction, 7- 2
func data type, 8145
G constant, 237
generalized coordinates , 520
generalized force array, 78
generalized speeds , 521, 78
get-name function, 896, 897
GFA array, 237
gravity, 527

find-body function, 894


find-point function, 894
find-sym function, 895
find-uv function, 895
finish command, 536, 834
finish-update command, 536, 835
flexible bodies, 75
fm function, 896
force
adding, 526
data type, 8145
definition, 512
line of action, 512
non-working, 529
reaction, see force, non-working
working, 527
force data object, 825
FORCEM array, 233, 37, 41, 34, 7
formalism keyword, 536, 832
FORMAT keyword, 210, 39
format Lisp form, 718
formatted text, 848
Fortran Code
arrays, 233
Booleans that control appearance of,
235
changing the design, 234
common blocks, 234
compiler dependencies, 237
core equations, 225
defining output variables, 533
dynamical, 227
equilibrium, 230
flow chart, 221
initilizing, 223
kinematical, 227
program design, 221
reading inputs, 223
routines, 222
setting default values, 223

help, xi, 87
holonomic constraints, 512
in-lb command, 538, 836
include files, 236
independent coordinates , 520, 21
independent speeds , 521
indexed keywords, 28
indexed-sym data type, 8146
inertia tensor, 514
inertia-matrix keyword, 519
INIT subroutine, 223
INPARS common block, 234, 35
INPUT subroutine, 223
install-differential command, 68, 837
install-func command, 837
install-indexed-parameters command, 5
38, 39, 838
install-table command, 534, 838
install-units command, 540, 840
integration method, 872
intermittent contact, 74
intern Lisp form, 718
IPRINT, 237
JAC array, 233, 37, 41, 34
Jacobian matrix, 214, 18
joints
constraints, 510
guidelines for describing, 523
point location, 59

I4

Index

AUTOSIM 2.0

ke (kinetic energy function), 897


kinematical equations, 111
kinematical loops, 511
kinematics analysis, 110
kinematics command, 536, 841

name data type, 8148


names, 538
Newtons second law, 111
Newton-Raphson iteration, 213, 24
NEWTR1 subroutine, 223
no-movement command, 516, 22, 846
no-rotation keyword, 519
nominal configuration, 59, 89
nominal function, 899
nonholonomic constraints, 512, 22
numerical integration
implicit and explicit methods, 218
options with AUTOSIM, 219
order of integator, 216
step size, 216
stiff equations, 217
variable step, 216

large command, 538, 842


lash, 74
let* Lisp form, 717
lifo command, 842
limitations in Lisp functions, 719
linear analysis, 118, 42
linear command, 536, 842
Lisp, 712
load-autosim command, 844
lower-upper triangular decomposition
(LUD), 212, 78
M array, 237
m-files (MATLAB), 43
mag function, 898
make-func function, 898
make-sign function, 8105
make-sin function, 8105
mass keyword, 519
mass matrix, 78
mass, 514
massless reference frame, 59
MATLAB Code
generated by AUTOSIM, 43
matrices, 43
writing, 540
max function, 898
Microsoft Word, 848
min function, 899
mks command, 538, 844
moment
adding, 529
definition, 513
non-working, 529
reaction see moment, non-working
working, 527
motion command, 516, 21, 845
moving reference frames, 519
Multiple-Valued Functions 3

on-line help, xi, 87


OPNFIL subroutine, 224
OPNOUT subroutine, 239, 40
order-n dynamics formulation, 79
ordinary differential equations (ODEs),
215
origin , 518
origin point, 59
output data file, 210, 39
OUTPUT subroutine, 228, 38
output variables, 534
parent body, 59
parent keyword, 518
parent-rotation-axis keyword, 519
parse-string function, 881
PARSFILE
file format, 23
keyword, 27
reference, 26
partial function, 899
PC array, 233, 37, 41, 34, 7
plot file, see ERD file
point
data type, 8148
definition, 13
definition, 55

I5

Index

AUTOSIM 2.0

function, 8100
standard body points, 59
point mass, 58, 19
point-ave, 8101
pos function, 8101
position vectors, 14
power data type, 8149
PRCMP common block, 234, 35
PRECMP subroutine, 223
print-bodies command, 537, 846
print-body command, 537, 847
print-constraints command, 537, 848
print-coordinates command, 537, 849
print-default-directions command, 537,
849
print-default-positions command, 537,
850
print-forces command, 537, 851
print-kane command, 537, 851
print-kanes command, 537, 852
print-moments command, 537, 853
print-outputs command, 537, 853
print-parameters command, 537, 853
print-points command, 537, 854
print-rf command, 537, 855
print-rfs command, 537, 856
print-speeds command, 537, 856
print-symbols command, 537, 857
printing results of analysis, 536
prod data type, 8149
programming, 712
projection of vector onto plane, 892

rot function, 8104


rq function, 8104
rtf (rich text format) command, 537, 8
59
rtf (rich text format) example, 848
ru function, 8104
S array, 233, 37, 41, 34, 7
set-defaults command, 538, 861
set-derivs command, 538, 68, 861
set-names command, 538, 862
set-units command, 538, 863
SETDEF subroutine, 223
setsym command, 538, 862
si command, 538, 864
sign function, 8105
SIMFILE, 210
sin function, 8105
small command, 538, 865
small-angles keyword, 519
small-translations keyword, 519
sqrt function, 8106
square function, 8106
ssqrt function, 8106
STARTT, 237
state variables
categories, 520
controlling definitions of, 524
definition, 18
status-report command, 865
STEP, 237
stiff systems, 217, 74, 7
STOPT, 237
sum data type, 8150
sym data type, 8150
symbolic computation see computer
algebra
symbolic LUD, 78
symbol properties , 538
symexp function, 8106
syntax of AUTOSIM, 515
SYPARS common block, 234

Q array, 233, 37, 41, 34, 7


QP array, 233, 37, 41, 34, 7
reaction-forces command, 536, 858
reaction-moment command, 858, 536
reference frame, 56
reference-axis keyword, 519
relvel function, 8102
reset command, 536, 859
rfvect function, 530, 8102
rich text format (RTF), 119
rigid body, 58
rmvect function, 530, 8103

table block in a PARSFILE, 27


tabular functions
installing, 534
I6

Index

AUTOSIM 2.0

types of, 535


tan function, 8107
tensors, 55
tq function, 8107
translate keyword, 518
tree topology, 510
tu function, 8107
typeset equations, 119

write-initnr command, 872, 541


write-input command, 541, 872
write-inteqs command, 541, 872
write-mac-file command, 540
write-main command, 541, 873
write-matlab command, 541, 873
write-newtr1 command, 541, 874
write-opnout command, 541, 874
write-output command, 541, 875
write-pederv command, 541, 875
write-precmp command, 541, 876
write-quasi command, 541, 876
write-setdef command, 541, 876
write-sim command, 541, 877
write-sim-minimal command, 541, 8
77
write-to-file command, 541, 878
write-update command, 541, 878
writing code, 541

U array, 233, 37, 41, 34, 7


unit vectors , 13
units
dynamics, 13
function, 8107
properties of, 539
setting units system, 538
setting, 538
user, 13
UP array, 233, 37, 41, 34, 7
UPDATE subroutine, 228, 29
uv data type, 8151

Y array, 233
YP array, 233

vectors
definition, 55
direction, 55
dot product, 15, 6
position, 14
unit, 13
vel function, 8108

Z array, 233, 37, 41, 34, 7


Z function, 8108
ZI array, 233, 37, 41, 34

write-acsl command, 541, 866


write-adsim command, 541, 866
write-c command, 541, 867
write-difeqn command, 541, 867
write-dolud command, 541, 867
write-echo command, 541, 868
write-eqs command, 541, 868
write-eqs-doc command, 541, 869
write-fct command, 541, 869
write-fct2 command, 541, 869
write-finish command, 541, 870
write-fortran-doc command, 541, 870
write-help command, 541, 871
write-help-globals command, 541, 8
71
write-init command, 541
I7