33 tayangan

Diunggah oleh tyanfeng

auto sim

- 04-01006
- 9780387238173-c1
- Shifrin L. Mathematica Programming.. an Advanced Introduction (Draft, 2008)(408s)_SC
- Bdc Recording
- Dso Activation Time Improvemnt
- BAB03- The Cont Blocks Lib
- Flowers
- matlab_-_slides_-_lecture_5_+_sol
- Fanuc 6 Alarm Codes
- qtpwithdescriptiveprogramming-090810234035-phpapp02
- Attchange.lsp
- Fortran 2003 & 2008 Compilers Support Charts, Rev 1 to 13 Ago13
- DAY2
- Job Scheduling
- Payroll Control Center - Check Implementation Guide
- Ab Initio EME Technical Repository
- Add Cell-Oriented DRD Algorithm Parameters(ADD UCELLDRD)
- 20-ch07-2-tallying
- Errors
- 680_680

Anda di halaman 1dari 320

Manual

Version 2.5+

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

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

2.1 Using the Simulation Program 23

The Parameter File (PARSFILE)

24

How PARSFILEs are used 24

PARSFILE Reference26

Indexed Keywords 29

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 4: Matrix Analysis Languages

4.1 Summary of Linear System Representation 4 2

4.2 MATLAB Code 4 2

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

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

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

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

*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

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.

programs generated by AUTOSIM are easy to use, requiring no experience in

modeling or simulation.

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

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.

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

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

Modeler (symbolic)

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.

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

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

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.

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

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)

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

AUTOSIM 2.0

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)

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)

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

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.

both a and b

3.

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.

Figure 1.3.3. Cross Product.

product operation when building

AUTOSIM models. However, it is handy for defining directions of moving reference

frames.

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

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

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)

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

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

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)

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.

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.

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.

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.

AUTOSIM 2.0

START

SET DEFAULTS

INPUT

known functions of time

INITIALIZE

file, and write parameters and

initial conditions into an echo file

SIMULATE

compute response variables, write

variables into output file

FINISH

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

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: Calculate computed coordinates

Write?

no

yes

OUTPUT

Done?

no

yes

E = equilibrium simulation

K = kinematics simulation

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

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

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.

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)

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)

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.

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

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

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

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.

23

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

AUTOSIM 3

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

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

,

,

,

,

,

,

,

,

,

,

,

,

,

,

,

,

,

,

,

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.) 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

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

AUTOSIM 3

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.

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.

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

AUTOSIM 3

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.

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.

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.

keywords, as will be described shortly below. The convention is to use the

keyword ID, but other names can be specified by the modeler.

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

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.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

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

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

Option

plain text

text ERD

(Fortran)

text ERD

(C)

binary

ERD

AUTOSIM 3

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

Keyword

SIMFILE

INPUT

ECHO

FINAL

ERDFILE

RUN

END

AUTOSIM 3

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

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

AUTOSIM 3

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)

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)

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)

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)

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

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.

2.

compute -gi

2 14

3.

AUTOSIM 3

a.

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

solution is xi.

b.

Otherwise, continue...

(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)

xi+1 xi + xi

6.

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

AUTOSIM 3

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)

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

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

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

X(t)

AUTOSIM 3

large time step

OK for low-frequency

response

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)

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

AUTOSIM 3

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

AUTOSIM 3

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.

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

AUTOSIM 3

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.

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

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.

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

AUTOSIM 3

START

SET DEFAULTS

INPUT

known functions of time

INITIALIZE

file, and write parameters and

initial conditions into an echo file

SIMULATE

compute response variables, write

variables into output file

FINISH

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

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

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

AUTOSIM 3

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

parameters and other constants

Compute valid starting position of

parts in multibody system based on

positions of independent coordinates

values used for this run.

Create file with simulation variables

and write header information

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

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)

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

AUTOSIM 3

coordinates

Compute constraint

errors and Jacobian

INITNR

Errors

OK?

yes

BKSUB

no

LUD

Solve linearized

constraint equations

for changes in

computed

coordinates

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

INTEQS

AUTOSIM 3

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: Calculate computed coordinates

Write?

no

yes

OUTPUT

Done?

no

yes

E = equilibrium simulation

K = kinematics simulation

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

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

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.

compute QP

subroutines

moments

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

compute UP

RETURN

have QP, UP,

trigs, Z's

Figure 2.3.7. Flow chart for subroutine

DIFEQN.

2 31

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.

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

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)

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

AUTOSIM 3

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

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

AUTOSIM 3

indep. coordinate

Calculate

force/moment errors

QUASI2

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

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

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

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.

2.

simlib.c

3.

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

AUTOSIM 3

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

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

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

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.

2.

simlib.f

3.

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.

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.

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

AUTOSIM 2.0

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

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

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.

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

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

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.

C

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)

IF (FORMAT(1:1)

WRITE (IFILE,

ELSE IF (FORMAT

WRITE (IFILE,

&

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

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

AUTOSIM 3

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

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

rights reserved.

IMPLICIT NONE

INTEGER

NVARS

PARAMETER

(NVARS = 7)

<Note:

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'

UNITSN(NCHAN) = 'rad'

RIGBOD(NCHAN) = 'C'

C

IF (FORMAT .EQ. 'TEXT') THEN

WRITE(IFILE, '(256A)') '"Time", ',

& ('"' // SHORTN(ILOOP)(:LENSTR(SHORTN(ILOOP))) // '", ',

&

ILOOP=1, NCHAN)

<Note:

RETURN

END

2 47

', 31A32))

AUTOSIM 2.0

CHAPTER 3

Support for the ADSIM and ACSL languages has been dropped from AutoSim

versions higher than 2.0.

CHAPTER 4

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

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)

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.

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

AUTOSIM 2.0

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)

command consists of the following sections:

1.

Numerous comments describe the multibody system model, listing bodies, state

variables, forces, and moments.

2.

3.

4.

5.

6.

MatrixC, and MatrixD are defined.

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

AUTOSIM 2.0

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.

2.

3.

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

1. Design Model

of multibody system

Modeling

(Symbolic

Analysis)

to describe system model

3. Run AUTOSIM

to generate custom program

to describe specific system

Simulation

(Numerical

Analysis)

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

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

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.

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

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

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

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

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)

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

AUTOSIM 2.0

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

(b) body B in new position

Figure 5.2.3. The three standard points in a body.

59

BCM

AUTOSIM 2.0

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

AUTOSIM 2.0

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

Holonomic and Nonholonomic

Constraints

AUTOSIM 2.0

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

A2

A1

AUTOSIM 2.0

Force F

B2

B1

A

B

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

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)

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)

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.

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

AUTOSIM 2.0

not important)

of parameters

change names of

parameters

change units of

parameters

define optional output variables

finish the symbolic multibody analysis

change global

variables

add optional

points

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

AUTOSIM 2.0

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

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

AUTOSIM 2.0

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

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

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

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

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

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.

3.

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

5 23

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

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

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

AUTOSIM 2.0

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)

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

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

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:

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

AUTOSIM 2.0

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

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

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

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

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

AUTOSIM 2.0

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.

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))")

5 34

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.

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

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

AUTOSIM 2.0

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.

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

AUTOSIM 2.0

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.

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

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

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*

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

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

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.

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")

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

AUTOSIM 2.0

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

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,

equations.

derivatives of external functions and variables.

61

AUTOSIM 2.0

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

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]))")

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

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.

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

AUTOSIM 2.0

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

AUTOSIM 2.0

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

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)

(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:

READ(BUFF2, 140)

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:

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

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).

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

AUTOSIM derives derivatives and partial derivatives of expressions under certain

conditions, such as:

forces with respect to the state variables;

respect to the state variables;

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

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

AUTOSIM 2.0

Fcf

.x

Fcf

.x

b. Saturating Damper

Fcf

.x

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

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

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

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.

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

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.

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

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

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

AUTOSIM 2.0

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,

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,

7 10

AUTOSIM 2.0

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

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

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

AUTOSIM 2.0

(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

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

AUTOSIM 2.0

;;; 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)

(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 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

AUTOSIM 2.0

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

AUTOSIM 2.0

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

1.

2.

`(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.

:long-name (format nil "~a spring deflection" longstr)

:gen-name "Deflection" :units "L" :body sbody)

20.

21.

22.

:long-name (format nil "~a damper rate" longstr)

:gen-name "Rate" :units "L/T" :body dbody)

23.

24.

25.

:magnitude (sub (arg-exp bias) (mul k x))

:direction d :point1 point1 :point2 point2)

26.

27.

:direction d :point1 point1 :point2 point2)

28.

29.

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

30.

31.

32.

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

))

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

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)

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")

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))

(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

AUTOSIM 2.0

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

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

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

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

?

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.

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

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

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, 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

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

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.

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.)

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

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

(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

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

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

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')

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))

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))

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")

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

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

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

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

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)

? (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

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

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

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)

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

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)

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

=============================

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

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

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

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)

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

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

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.,

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

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*

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

8 110

8.3 Globals

AUTOSIM 2.0

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*

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)

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

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

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))

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")

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

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

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*

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

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

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

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

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

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

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

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

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

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

*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-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

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

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

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-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

kinematical equations, 111

kinematical loops, 511

kinematics analysis, 110

kinematics command, 536, 841

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

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

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

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

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

tabular functions

installing, 534

I6

Index

AUTOSIM 2.0

tan function, 8107

tensors, 55

tq function, 8107

translate keyword, 518

tree topology, 510

tu function, 8107

typeset equations, 119

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

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 function, 8108

ZI array, 233, 37, 41, 34

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

- 04-01006Diunggah olehrachmat99
- 9780387238173-c1Diunggah olehMartín Figueroa
- Shifrin L. Mathematica Programming.. an Advanced Introduction (Draft, 2008)(408s)_SCDiunggah olehVport Port
- Bdc RecordingDiunggah olehmahisapabap
- Dso Activation Time ImprovemntDiunggah olehsatyakosaraju
- BAB03- The Cont Blocks LibDiunggah olehcakMAD69
- FlowersDiunggah olehdc
- matlab_-_slides_-_lecture_5_+_solDiunggah olehKtk Zad
- Fanuc 6 Alarm CodesDiunggah olehIon Vasilica Brosu
- qtpwithdescriptiveprogramming-090810234035-phpapp02Diunggah olehshashmi08039
- Attchange.lspDiunggah olehbytejuice
- Fortran 2003 & 2008 Compilers Support Charts, Rev 1 to 13 Ago13Diunggah olehitetejac
- DAY2Diunggah olehMaulana Dhawangkhara
- Job SchedulingDiunggah olehnadeem_khan4all
- Payroll Control Center - Check Implementation GuideDiunggah olehnikebara
- Ab Initio EME Technical RepositoryDiunggah olehabraham_sse1594
- Add Cell-Oriented DRD Algorithm Parameters(ADD UCELLDRD)Diunggah olehmpxis
- 20-ch07-2-tallyingDiunggah olehyair B
- ErrorsDiunggah olehercov85
- 680_680Diunggah olehUbiquitous Computing and Communication Journal
- ans_apdlDiunggah olehdwdg
- PDF_Application_macros_en_V2.pdfDiunggah olehbeihan
- Statement call in javaDiunggah olehanuja_java
- Tenesee_ABAPDiunggah olehmuro562001
- Apps Technical NotesDiunggah olehJames Anderson
- Post Command LanguageDiunggah olehAndrei S. Pavlov
- Date FunctionsDiunggah olehKelLy Besa-Ang
- A Framework for Programming Embedded Systems: Initial Design and ResultsDiunggah olehcbthiess
- CRP for Oracle R12Diunggah olehSumit K
- 14858_subprogramsDiunggah olehVaibhav Jain

- [20837429 - Polish Maritime Research] An Experimental Study of Emission and Combustion Characteristics of Marine Diesel Engine with Fuel Injector MalfunctionsDiunggah olehtyanfeng
- 19 Powerpoint PresentationsDiunggah olehtyanfeng
- Step-By-Step_ Prepare USB Media to Install Windows 10 – GoodDiunggah olehtyanfeng
- 做甲醇必讀：這篇文章說透了甲醇產業鏈 - Q博士Diunggah olehtyanfeng
- 數學式和數學用語的英文讀法Diunggah olehquantalcat
- Automatically Converting Matlab Code to c CodeDiunggah olehtyanfeng
- Lecture Notes for Section 14.4Diunggah olehtyanfeng
- 低價刺激歐美甲醇燃料業「井噴」2015Diunggah olehtyanfeng
- 乙醇還沒弄明白，甲醇又來了？Diunggah olehtyanfeng
- 姚春德：甲醇是內燃機最好的替代能源Diunggah olehtyanfeng
- 6. 世界主要國家石油產品價格及稅率Diunggah olehtyanfeng
- 6. 世界主要國家石油產品價格及稅率Diunggah olehtyanfeng
- Lyapunov-based guidance law for impact time control and simultaneous arrival.pdfDiunggah olehtyanfeng
- world-22_27Diunggah olehtyanfeng
- Tutorial-Motor-Basics-LectureDiunggah olehapi-3765150
- Contents BELS064 2Diunggah olehtyanfeng
- Contents BELS064 2Diunggah olehtyanfeng
- Acitve Mirco-mixers Using Surface Acoustic Waves on Y-cut 128o LiNbO3Diunggah olehtyanfeng
- AviationChief - V-n DiagramsDiunggah olehtyanfeng
- V-n Diagram With Gust LoadDiunggah olehtyanfeng
- V-n diagram (n=+-2)Diunggah olehtyanfeng
- Banking TurnDiunggah olehtyanfeng
- PROD_SET_20130722165157Diunggah olehtyanfeng
- Development of Ceiling Fans and Outlook for the FutureDiunggah olehtyanfeng
- Fabrication and Analysis of MIST FanDiunggah olehtyanfeng
- 491790643Diunggah olehtyanfeng
- V-n diagramDiunggah oleh2jraj
- Ex7 ClimbingDiunggah olehtyanfeng
- Intel® Xeon® Processor E3-1535M v5 (8M Cache, 290 GHz) Product SpecificationsDiunggah olehtyanfeng
- Dell P7710 Owner's Manual_en-usDiunggah olehtyanfeng

- 27 Limits Part 1 of 1Diunggah olehUtkarsh Tewari
- 252008255-Lecture-3.pdfDiunggah olehDiipesh Monga
- 2008USAMOsolnDiunggah olehMarco Antonio Leal
- Csc349a Cribsheet Rev3.0Diunggah olehPaBa
- Notes Ma131 Ch6Diunggah olehXcalibur1101
- IRJET-The Comparison of the Muslim Settlements in Pathok Negoro Area, Yogyakarta, IndonesiaDiunggah olehIRJET Journal
- AttitudeDiunggah olehShreya Jaiswal
- RotationDiunggah olehfree_prog
- sols4Diunggah olehjiamin_tay5573
- solu8Diunggah olehAlisen Erdogan
- Tutorial ECEDiunggah olehMustafidzul Mustapha
- MPC controller design for Inverted pendulum.pdfDiunggah olehSolomon Genene
- Anti de Sitter Space WikiDiunggah olehmenilanjan89nL
- b.tech. (Computer Science)Diunggah olehरजतयदुवंशी
- Selectivity EconometriaDiunggah olehRoger Asencios Nuñez
- circle geometry.pdfDiunggah olehUpasna Khastgir
- Chapter 1Diunggah olehHoang Minh Dac
- Tutorial 06 SolutionDiunggah olehMohd HelmiHazim
- PDE Methods for Pricing Barrier OptionsqDiunggah olehMohammed Ali Al-belushi
- eric liss resumeDiunggah olehapi-404638544
- 410-prosedur-pendaftaran-program-sarjana-1308141037.pdfDiunggah olehign_handoko
- 2.2 Multistep EquationsDiunggah olehMrPeterson25
- CO211-ErrorDetectionandCorrectionDiunggah olehThilini Nadeesha
- Study and Analysis of Single Point Cutting Tool Under Variable Rake AngleDiunggah olehIJRASETPublications
- Subtracting - Missing AddendDiunggah olehAzierah Misstaurus
- IA-09multiple and Sub Multiple Angles(45-47)Diunggah oleheamcetmaterials
- Barnett - The Calculation of Spherical Bessel Functions and Coulomb FunctionsDiunggah olehzvirko
- (1993) 'the Growing Importance of LA in Undergrad Mathematics'Diunggah olehCaio Viega
- Complex analysisDiunggah olehAritra Lahiri
- Mathematical Theory of Elasticity- A. E. H. LOVE, M.a.- CAMBRODGE PRESS 1893 Vol-IIDiunggah olehamitrawal