acsl reference manual

��

��

Reference Manual

AEgis Software, a divison of the AEgis Technologies Group, Inc. 6703 Odyssey Drive, Suite 103

Huntsville, AL 35806U.S.A.

Phone: (256) 922-0802Fax: (256) 883-5516

http://www.ACSLsim.com

Copyright:

Copyright (c) 1999 the AEgis Technologies Group Inc. All Rights Reserved. Printed in the United States of America.

ACSL is a registered trademark of the AEgis Technologies Group Inc.

Information in this document is subject to change without notice. The software described in this document is fur-nished under a license agreement. The software and this documentation may be used only in accordance with the terms of those agreements.

AEgis Software, a division of the AEgis Technologies Group Inc.6703 Odyssey Drive, Suite 103Huntsville, AL 35806U.S.A.http://www.ACSLsim.com

December 1999

Advanced ContinuousSimulation Language

(ACSL)

Reference Manual

AEgis Software, a division of the AEgis Technologies Group, Inc.6703 Odyssey Drive, Suite 103

Huntsville AL 35806 USA

ACSL Reference Manual

Copyright © 1998-1999 by the AEgis Technologies Group, Inc.ACSL isa registered trademark of the AEgis Technologies Group, Inc.Al l rights reserved. Printed in theUnited States of America.

Foreword

This manual describes the Advanced Continuous Simulation Language, ACSL(pronounced "axle"). The language is designed for modeling and evaluating theperformance of continuous systems described by time-dependent, nonlinear differentialequations.

Typicalapplications

Applications of ACSL in new areas are being developed constantly. Typical areas inwhich ACSL is currently applied include control system design, aerospace simulation,chemical process dynamics, power plant dynamics, plant and animal growth,toxicology models, vehicle handling, microprocessor controllers, and robotics.

Prerequisites This manual assumes that you are an engineer or scientist with some experience incomputers and programming. You thus know the basics of calculus and of FORTRAN,C, or C++ and are familiar enough with a computer operating system to manage andedit files.

Relateddocuments

This manual documents the machine-independent elements of ACSL. User guidesdescribing installation and execution on a particular computer are published separatelyand shipped with each ACSL system. AnACSL Beginner's Guideis also available.

How to use thismanual

We recommend that you read through the first three chapters and then turn to theexample programs in Appendix A. The ACSL statements (Chapter 4) and runtimecommands (Chapter 5) are in alphabetical order for reference.

The linear analysis and frequency response features are described under theANALYZE command in Chapter 5. System symbols are listed in Appendix C.

Before running a simulation, be sure to study Chapter 7 on debugging.

ACSL Reference Manual Page iii

Page iv ACSL Reference Manual

Table of Contents

1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

1.1 Simulation language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11.2 Job processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-21.3 Language features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-21.4 Coding procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-41.5 Reserved names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-51.6 Fortran subroutines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6

2. Language Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

2.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12.2 Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12.3 Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-32.4 Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-42.5 Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5

3. Program Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

3.1 Implicit and explicit structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13.2 Program flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13.3 Program sorting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-43.4 Preset of user variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-63.5 Preset of derivatives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6

4. ACSL Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1ABS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4ACOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4AINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4ALGORITHM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5ANINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10ASIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11Assignment statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11

Arithmetic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11

Logical . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11

Character . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11

ATAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12ATAN2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12BCKLSH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12BOUND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13CALL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13CHARACTER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14CINTERVAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14CLOSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16CMPXPL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16Comment (!) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16COMMON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17CONSTANT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18Continuation (&) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-19CONTINUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-20COS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-20DBLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-20DBLINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-21

ACSL Reference Manual Page v

DEAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-22DELAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-22DELSC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-24DELVC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-25DERIVATIVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-25DERIVT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-28DIM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-28DIMENSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-29DISCRETE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-30DO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-32DOUBLE PRECISION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-33DYNAMIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-33END . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-34EQUIVALENCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-34ERRTAG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-35EXP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-36EXPF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-36FCNSW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-36FORMAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-37GAUSI, UNIFI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-37GAUSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-38GO TO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-38HARM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-39HISTORY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-39IF, IF-THEN-ELSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-40IMPLC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-42IMPVC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-44INCLUDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-45INITIAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-45INQUIRE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-46INT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-46INTEG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-47INTEGER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-49INTERVAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-49INTVC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-50I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-51LEDLAG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-51LIMINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-52LINEAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-54LINES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-54LOG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-55LOG10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-55LOGD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-55LOGICAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-56LSW, RSW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-57MACRO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-57MAX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-57MAXTERVAL, MINTERVAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-58MERROR, XERROR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-59MIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-60MINTERVAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-60MOD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-60NINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-60NSTEPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-61OPEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-62OU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-62PAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-63

Page vi ACSL Reference Manual

PARAMETER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-64PRINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-64PROCEDURAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-64PROGRAM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-66PTR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-66PULSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-67QNTZR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-67RAMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-68READ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-68REAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-69REALPL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-69RESET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-70RSW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-70RTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-71SAVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-71SCALE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-72SCHEDULE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-72Separator (;) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-80SIGN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-80SIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-81SMOOTH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-81SORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-83SQRT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-83STEP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-84TABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-85TAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-88TERMINAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-89TERMT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-89TRAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-90TRANZ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-92Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-93UNIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-96UNIFI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-96USEDBV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-96VARIABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-97WRITE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-97XERROR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-97

5. ACSL Runtime Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

5.1 Runtime executive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-15.2 ACTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-25.3 ANALYZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-45.4 Comment (!) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-205.5 Continuation (&) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-205.6 CONTINUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-215.7 DATA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-225.8 DISPLAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-245.9 END . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-265.10 EXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-265.11 FILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-265.12 HELP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-285.13 MATH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-285.14 MERROR, XERROR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-305.15 OUTPUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-30

ACSL Reference Manual Page vii

5.16 PAUSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-325.17 PLOT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-325.18 PREPARE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-425.19 PRINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-435.20 PROCEDURE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-455.21 QUIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-475.22 RANGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-485.23 REINIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-495.24 RESTORE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-505.25 SAVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-515.26 Separator (;) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-525.27 SET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-525.28 SPARE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-545.29 START . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-545.30 SYSTEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-555.31 Wild cards (* and ?) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-565.32 XERROR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-56

6. Macro Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

6.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-16.2 Macro definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-46.3 Macro definition header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-46.4 Macro directive statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-66.5 Macro examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-116.6 Macro invocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-17

7. Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1

7.1 Debugging procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-17.2 DEBUG printout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-47.3 Variable Step Algorithm Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-77.4 Output for debugging of integration process . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-87.5 Jacobian Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-167.6 Loss of accuracy with large bias terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-19

8. Application Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1

8.1 Parameter sweep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-18.2 Phase and gain plots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-28.3 Summary output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-38.4 Impulse and step response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-48.5 Externally defined variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-58.6 Stopping missiles at intercept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-68.7 State space linear matrix model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-78.8 Full set matrix operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-88.9 Moving time backwards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-88.10 Plotting averages from Monte Carlo programs . . . . . . . . . . . . . . . . . . . . . . . . . . 8-98.11 Plotting arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-108.12 Calling subroutines in C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-118.13 Synchronizing DISCRETE events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-13

Page viii ACSL Reference Manual

A. ACSL Example Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1

1. Limit Cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-12. Spring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-53. Control Loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-94. Pilot Ejection Study . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-135. Temperature Distribution along a Radiating Fin . . . . . . . . . . . . . . . . . . . . . . . . . . A-206. Aircraft Arresting Gear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-347. Aircraft Longitudinal Study . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-418. Physiological Benchmark . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-529. Phase and Gain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6210. Missile Airframe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-7011. Discrete Sampled Compensator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-9012. Aspirin Dosage Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-9713. Block on a Rough Surface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-10214. Linear analysis example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-11615. Tank with Boiling Benzene . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-123

B. General Purpose Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1

B.1 AGET–, APUT– . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1B.2 DEBUG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-2B.3 DISSTR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-2B.4 INITD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-3B.5 INTEG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-3B.6 LISTD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-4B.7 RSTART . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-5B.8 SETI, SETR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-5B.9 WEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-5B.10 XFERBR, XFERBI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-6

C. ACSL System Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1

C.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1C.2 Plots in general . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1C.3 Printer plots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-3C.4 Continuous plots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-3C.5 Strip plots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-5C.6 Frequency plots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-6C.7 Print data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-8C.8 Integration control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-8C.9 Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-9

D. ACSL Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-1

E. References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-1

ACSL Reference Manual Page ix

Page i ACSL Reference Manual

1. Introduction

1.1 Simulationlanguage

Simulation of physical systems is a standard analysis tool used in the evaluation ofhardware design prior to actual construction. The continuous system simulationlanguage described herein, and referred to as ACSL (Advanced ContinuousSimulation Language), has been developed expressly for the purpose of modelingsystems described by time dependent, nonlinear differential equations and/or transferfunctions.*

Applications Typical application areas for continuous simulation are control system design,chemical process representation, missile and aircraft simulation, power plantdynamics, biomedical systems, vehicle handling, microprocessor controllers, fluidflow, and heat transfer analysis. Users can derive model code from block diagrams,mathematical equations, conventional Fortran statements, etc.

Graphical frontend

A graphical front end for ACSL is available in a software package called GraphicModeller. Block diagrams are developed on screen from pre-defined PowerBlocksrepresenting ACSL statements, operators, functions, and/or user-defined blocks in anunlimited hierarchical structure. ACSL code is generated directly from the graphicalmodel.

Languagehighlights

Highlights of the ACSL language are free form input, function generation of up tothree variables, and independent error control on each integrator. Flexibility isprovided for plotting the behavior of the models under a number of external forcingfunctions. Many simulation oriented operators such as variable time delay, dead zone,backlash, and quantization are included and made readily accessible. Global single ordouble precision calculation can be selected.

The ACSL program is intended to provide a simple method of representing thesemathematical models on a digital computer. Working from an equation description ofthe problem or a block diagram, the user writes ACSL statements to describe thesystem under investigation. Runtime commands exercise the model; these statementscan be submitted for solution in batch mode or entered interactively. Interactively youcan run the simulation, look at the results, and change constants to experiment with themodel; for example, trying different spring constants or actuator limits.

An important feature of ACSL is its sorting of the continuous model equations, incontrast to general purpose programming languages such as Fortran where programexecution depends critically on statement order. ACSL program structure and thetranslator sorting procedure are described in Chapter 3.

ACSL Reference Manual Page 1-1

* The basic structure follows the specification established by the Technical Committee on Continuous SystemSimulation Languages and under the auspices of Simulation Councils, Inc. (SCi) inSimulation9 (Dec. 1967) pp281-303.

1.2 Jobprocessing

Inputs to ACSL are in two parts. Theprogramdefines the system being modeled; theruntime commandsexercise this model (i.e., they change parameters, execute runs,specify plots, etc.).

The program is read by the ACSL translator, which translates it to a Fortran compilefile. The Fortran code is then compiled, linked with the ACSL runtime library, andexecuted, finishing at an ACSL runtime prompt:

ACSL>

At this point, ACSL is waiting for runtime commands, which can be enteredinteractively, by reading a command file, or in a batch process. The commands areread, decoded, and executed in sequence. See Chapter 5 for a description of thecommands. A minimum of a START command is necessary to exercise the model.

1.3 Languagefeatures

The language consists of a set of arithmetic operators, standard functions, a set ofspecial ACSL statements, and a MACRO capability. The MACRO capability allowsextension of the special ACSL statements, either at the system level for eachinstallation, or for each individual user.

Operators andfunctions

The arithmetic, relational, and logical operators, described in Chapter 2, work as theydo in Fortran. The functions, listed in Chapter 4, consist of special ACSL operatorssuch as QNTZR (quantization), UNIF (uniform random number), etc. In addition, allthe functions of the Fortran library are available;e.g., SQRT (square root), MOD(modulus), etc.

Integration Integration is a special ACSL operator that is called by either INTEG (scalar) orINTVC (vector). This is written in the form:

r = INTEG(x, rzero)

which implies:

R = RZERO+ ∫0

T

X dt

This integration operator is the heart of the simulation system. In building any model,it is necessary to change differential operators into integration operators; this isconventionally accomplished by expressing the highest derivative of a variable interms of lower derivatives and other variables. As an example, consider the springdashpot system excited by a given function of time F(t). In general form, this is:

x..

+ 2ζωx.

+ ω2x = F(t)

whereω is the natural frequency andζ the damping ratio. Expressing this equation interms of the highest derivative,x

.., gives:

x..

= F(t) − 2ζωx.

− ω2x

1. Introduction 1.2 Job processing

Page 1-2 ACSL Reference Manual

INTEG operator This derivative can then be integrated once forx.

and again forx. Sincex.

appears onthe right hand side, it must be given a name (XD). The two integrations can be writtenin the program as:

xd = INTEG(F(T) - 2*ze*w*xd - w**2*x, xdic)x = INTEG(xd, xic)

This process transforms the original set of differential equations to a set of first orderequations which can be solved directly by integrating.

Redundant statevariables

Be careful in the transformation process to avoid the introduction of redundant statevariables. In the above sequence, the reference tox

.(XD) could have been avoided by

calculatingx..

(XDD) directly and embedding an INTEG operator in the expression;i.e.,

xdd = F(T) - 2*ze*w*INTEG(xdd, xdic) - w**2*x

Now X is the second integral of XDD and can be calculated as follows:

x = INTEG(INTEG(xdd, xdic), xic)

In these two equations, there are three INTEG operators (each one a state variable), buttwo are integrations of XDD with the same initial condition. One of these is redundantand can be eliminated by explicitly naming the first derivative as shown previously.

Limit cycleexample

As an introduction to the process of coding a model, we will outline a simple exampleusing the arithmetic operators and the SQRT and INTEG functions. The followingequations define a limit cycle:

x.

= y +x (1 − x2 − y2 )

√x2 + y2; x(0) = 0.5

y.

= − x +y (1 − x2 − y2 )

√x2 + y2; y(0) = 0.0

The equations are coded as follows:

r2 = x**2 + y**2x = INTEG(y + x*(1.0 - r2)/SQRT(r2), 0.5)y = INTEG(-x + y*(1.0 - r2)/SQRT(r2), 0.0)

Program code While this series of statements completely describes the equations to be solved, it doesnot represent the complete problem statement. Figure 1-1 lists the complete runningprogram. Each statement is numbered for reference. A DERIVATIVE statement (1) isneeded to define the beginning of the program. The communication interval (datalogging rate) is specified by the CINTERVAL operator (3). A termination conditionmust be specified in a TERMT statement (7). Finally, the program definition iscompleted by an END statement (8) to match the DERIVATIVE statement. This ENDstatement tells the translator that no more ACSL statements are expected, althoughFortran subroutines or functions can be added at the end of an ACSL program.

A further refinement is in assigning symbolic names for the initial conditions, X(0)and Y(0), and for the stop time TF. These are preset in the CONSTANT statement (2).It is better programming practice to use a symbol preset to the value desired than toembed literal constants (0.5, for example) in the program. Changes then occur in oneplace in the program, and values can also be changed at runtime.

Runtimecommands

The second part of Figure 1-1 is an example of runtime statements. OUTPUT (9)defines the variables that are to be listed on the screen at each communication intervalas the run progresses. The model is then executed by the command START (10). Line

1.3 Language features 1. Introduction


(11) is a comment, (12) changes the initial condition, and (13) runs the model again.Line (14) quits from the runtime session.

Section 1 of Appendix A lists the actual program, gives more detailed explanations,and shows examples of results and plots.

1.4 Codingprocedure

The ACSL coding line contains eighty columns. ACSL statements may be placedanywhere on the line, but we suggest that developing standards to make programseasier to read. Suggested standards are as follows:

Section delineators (PROGRAM, INITIAL , END, etc.) start in column 1PROCEDURAL brackets (PROCEDURAL/END) start in column 6Unlabeled statements start in column 7Labelled statements start label in column 6Equal sign in assignment statements in column 15 or beyond

Separator More than one statement can be placed on one line by separating the statements with asemicolon (; ).

Continuation Any statement can be continued on to the next line by adding an ampersand (&) at theend of the line, to the right of any nonblank information but before column 80. Anytrailing blanks are squeezed out of the line containing the ampersand and the followingline is added directly. Starting with column 1, it is as though the characters were strungon the end after the last nonblank character of the preceding line. Leading blanks ofthe continuation line are not suppressed unless a leading ampersand is present on thecontinuation line. Comments can be added after the trailing ampersand since thesecomments are stripped off first. An empty line needs two ampersands since a singleone can't be distinguished.

Comments Everything after an exclamation point (! ) is considered a comment and is ignored bythe translator (in the program) and the runtime executive (in runtime commands).

Blank lines Blank lines can be placed anywhere in the program and have no effect.

(1) DERIVATIVE ! limit cycle(2) CONSTANT xz = 0.5 , yz = 0.0 ,tf = 4.0(3) CINTERVAL cint = 0.2(4) r2 = x**2 + y**2(5) x = INTEG( y + x*(1.0 - r2)/SQRT(r2), xz)(6) y = INTEG(-x + y*(1.0 - r2)/SQRT(r2), yz)(7) TERMT(t .ge. tf, 'Time Limit')(8) END

(9) OUTPUT t,x,y,sq(10) START(11) ! Change initial conditions and run again(12) SET xz=0.7(13) START(14) QUIT

Figure 1-1. Limit cycle example of model code and runtime commands

1. Introduction 1.4 Coding procedure


1.5 Reservednames

The only reserved names in the language are those of the form Znnnnn and ZZaaaa,wheren is any digit anda is any alphanumeric character. All generated variables andsystem subroutine names are in this form.

System variabledefaults

It is a good idea, in addition, to keep in mind the system variable default names listedin Table 1-1. These default names can be changed to any name, but if names are notspecified, the default names will be in existence so they can be set by program controlin the model definition section. Other uses of these names (e.g., defining MAXT as astate variable) could cause conflicts.

Runtime systemsymbols

A further level of names to be considered is the runtime system symbols listed inAppendix C. These are flags and numeric values that determine such things as plotformat, print intervals, etc. Quantities such as the Y axis length (YINCPL) for lineplots, grid line type (GLTPLT), etc. are under your control at runtime. All thesesymbols have default values. Access is by runtime SET command;e.g.,

SET YINCPL = 5.0

Precedence ofnames

Symbols in SET commands are searched for first in the user's dictionary;i.e. thedictionary created from the variable names in the program code. If that search isunsuccessful, the dictionary of ACSL system symbols is searched. Thus, if one of thesystem symbols is used as a name in the program, that use takes precedence over theACSL system use. You should generally not duplicate system symbol names withinthe program since doing so means that you will not have the luxury of modifying thesystem default values.

Table 1-1. System variable defaults

Statement Default name Default value Definition

ALGORITHM IALG 5 Integration algorithmCINTERVAL CINT 0.1 Communication intervalERRTAG none .FALSE. Error flagMAXTERVAL MAXT 1.0E+10 Maximum calculation intervalMINTERVAL MINT 1.0E-10 Minimum calculation intervalVARIABLE T 0.0 Independent variable

Note: It is probably a good idea to treat these names as reserved and not use them for any purpose except that stated.

1.5 Reserved names 1. Introduction


1.6 Fortransubroutines

User-defined Fortran functions or subroutines can be used in an ACSL program byincluding them at the end of the program;i.e. immediately following the last ACSLEND statement. The translator looks for the following:

REAL FUNCTION ...INTEGER FUNCTION ...LOGICAL FUNCTION ...CHARACTER FUNCTION ...DOUBLE PRECISION FUNCTION ...SUBROUTINE ...FUNCTION ...PROGRAM ...

If one of these keywords is found, the translator assumes that all the subsequent linesare to be passed directly to the Fortran compiler without any changes, so Fortranformat must be followed exactly;i.e., start in column seven or beyond, etc.

First line It is important that the line following the ACSL model really contain one of theFortran statements listed above. A Fortran comment (C in column one) is rejectedsince it could be the beginning of a valid ACSL line;e.g.,

c = k1*x

Tabs The first line cannot contain a tab since ACSL sees a tab as a space until it determinesthat it is in Fortran. Tabs are acceptable in the Fortran code itself.

TOO MANY ENDS If text following the ACSL model does not correspond to the beginning of a Fortranroutine, the error messageToo many endsis produced. A model definition with toomany END statements causes the model file to close prematurely. The first statementafter an extra END statement looks the same to the translator as an incorrect Fortransubroutine header.

$ for commonblocks

The only change the translator makes in transferring the Fortran code is to look for adollar sign ($) in column one. This line is replaced by all the ACSL common blockscalled/ZZCOMi/ and type statements (which may run to many lines). Using thisfeature makes the names and values of an ACSL program available to the subroutine.The dollar sign should appear before any DATA or executable statements, but can beafter type statements or comments.

Note that there is no selectivity in pulling in the common blocks; either all the symbolsare obtained or none. It is easy to get name conflicts or violate the translator sortingalgorithm by this action. We recommend using your own common blocks wherenecessary to make names from one program or subroutine available in another.

1. Introduction 1.6 Fortran subroutines


2. Language Elements

2.1 Introduction

Most of the basic elements of ACSL are defined as in Fortran. Table 2-1 lists themajor differences. If you are familiar with Fortran, you could skip to the next chapterafter reading the table; if not, you should be sure you understand the languageelements described in this chapter.

2.2 Constants

Constants may be either integer, floating point (single or double precision), logical, orcharacter.

Integer An integer constant is a whole number, written without a decimal point, exponent, orembedded blanks. Positive numbers may be prefixed with a plus sign; negativenumbers must be prefixed with a minus sign. The maximum length of an integer ismachine dependent. Subscripts of arrays are generally limited to five digits. Examplesof integer constants include:

0 +526 -63 476

Table 2-1. Major differences between ACSL and Fortran syntax

labels Labels can be alphanumeric or numeric. Labels are separated from the statements towhich they are attached by a colon;i.e.,

label: statement

Due to conflicts with macro expansions within labeled statements, we recommend thatlabels be used only with CONTINUE statements. See the section on labels.

names Blanks are not allowed within names. Names may have up to thirty-one characters.Names should not be of the form Znnnnn or ZZaaaa wheren is any number anda isany alphanumeric character.

types Variables starting with I, J, K, L, M, or N arenotautomatically considered integer.All variables and functions are considered floating point (single or double precisiondepending on the library specified) unless typed explicitly otherwise.

coding Free format; use any columns 1 through 80.

continuation An ampersand (&) at the end of a line indicates continuation onto the next line. Anon-blank column six has no significance in free format.

comments An exclamation point (! ) indicates a comment. ACSL ignores all code from anexclamation point to the end of the line. A "C" in column one has no significance infree format.


Floating point A floating point constant is written with a decimal point and/or an exponent. Positivenumbers may be prefixed with a plus sign; negative numbers must be prefixed with aminus sign. The exponential forms are E (single precision) and D (double precision).Examples of floating point constants include:

3.1416 31.416E-1 7.9566314D-4 3E1-0.000345 0.347E03 -27.6E+220

Numbers entered with a decimal point and no exponent (1.234, for example) are givena double precision exponent of D0 (i.e., 1.234D0) when the global double precisiontranslator option is selected. Numbers in expressions such as:

x = y*1.234

are handled by the compiler;i.e., the constant 1.234 is automatically promoted todouble precision if Y is double precision. However, since 1.234 is not an exact binarynumber, it is not as precise as 1.234D0. The main use of this promotion feature is inarguments to subroutines where it is impossible for the compiler to determine theprecision of the subroutine argument when used inside the routine. Be careful whenusing integers and floating point numbers in subroutine arguments in case the type isaccidentally changed. For example:

CALL mysub(1, 1.234)

must have arguments that are an INTEGER and a REAL, but when using the globaldouble precision translator, the second argument will be converted to 1.234D0 and thesubroutine's internal precision must be adjusted.

To prevent a mismatch in this situation, use the exponent form or one of the typeconversion functions DBLE or REAL. REAL(1.234) is always single precision, andDBLE(1.234) and 1.234D0 are always double precision, but 1.234E0 is changed to1.234D0 under global double precision. In the example above, you can ensure that thesecond argument is always single precision by:

CALL mysub(1, REAL(1.234))

Promotion ofintegers

A number without a decimal point (1 instead of 1.0) can be used inmostcircum-stances where a floating point number is expected. The number is floated before it isused. Be sure however to use a decimal point (or a variable name) in arguments tofunctions, macros, or subroutines. Also, expressions withonly integers are notpromoted, so1/2/pi is zero, but1/2.0/pi and1/(2*pi) give correct results.

Logical Logical constants may be one of two values.

.TRUE. .FALSE.

However, when logicals are plotted in ACSL, zero corresponds to .FALSE. and one to.TRUE. There is no equivalent to this in Fortran.

Character Character constants are strings of letters, numbers, and other characters.

SET TITLE = 'Limit Cycle, Run1'

Character constants are defined by a string of characters within single quotes. Singlequotes are inserted in a string by doubling them; for example, to define a stringabc'def , use'abc''def' .

Constants assymbols

Constants are best given symbolic names in model code. While literal constantscanbeused in expressions directly, it is impossible to change their values at runtime. Tochange a literal constant, the original source code must be changed and the programretranslated, compiled, and linked. If the same constant appears more than once, more

2. Language Elements 2.2 Constants


changes in the source text are required. It is better to give all constants symbolicnames to be used in expressions, presetting these via CONSTANT statements;i.e.,rather than:

area = 3.142*r**2

the following code is preferred:

CONSTANT pi = 3.142area = pi*r**2

2.3 Variables

Variable names are symbolic representations of numerical quantities that may or maynot change during a simulation run. They refer to a location and have a value equal tothe current number stored in that location. Both simple and subscripted variables maybe used. A symbolic name must start with a letter and be followed by up to thirtyletters and digits (not more than thirty-one characters total).

Types All variables in an ACSL program are assumed to be real (single or double precision,depending on the library specified) unless explicitly typed otherwise. The Fortranconvention for integers starting with the letters I through N does not apply. TypeREAL specifies single precision only; type DOUBLEPRECISION specifies doubleprecision only. Variables can also be of type INTEGER, LOGICAL, orCHARACTER. Examples of simple variables include:

a a57 ab57d k20

Subscripts A subscripted variable may have up to six subscripts enclosed in parentheses.Subscripts can be expressions in which the operands are simple integer variables andinteger constants, and the operators are addition, subtraction, multiplication, anddivision only. For more information on storage allocation, see DIMENSION.Examples of subscripted variable names include:

b(5,2) b53(5*i + 2, 6, 7*k + 3)c47(3) array(2) plate(2,2,3,3,2,2)

In the above examples, I and K must be declared explicitly to be INTEGER variables.

Array order Elements of arrays are written and accessed by column, then row; for example, theelements ofb(2,5) can be shown:

11 12 13 14 1521 22 23 24 25

Extracted as a single-dimensioned vector, the order is:

11 21 12 22 13 23 14 24 15 25

Underscore Underscores can be included in variable names to make them more readable, inaccordance with Fortran 88 standards.

this_long_name = INTEG(motor_velocity, initial_condition)

2.3 Variables 2. Language Elements


2.4 Labels

A label can be attached to a statement so that control is transferred to it by GO TO orso that a FORMAT statement is labeled.

Form A label can be either alphanumeric or numeric.

Reservedlabels

The ACSL system uses labels starting at 99999 and working downwards; you shouldtherefore avoid labels with high numeric values to avoid possible conflicts.

Syntax A label is set off from the statement to which it applies by a colon (: ), as in thisexample.

L1: CONTINUEx = a + b1000 : y = c + dGO TO L1

Statementsattached to

Although it is legal to attach statement labels to any executable statements, onlyCONTINUE statements are recommended. The difficulty is that the labeled statementmay be translated into several statements;i.e., the effect of a MACRO call inside astatement is that the macro is expanded first, followed by the labeled statement.

Macroexpansion

As an example, consider the random number generator GAUSS, which is a MACRO.It could be used in a labeled statement in a PROCEDURAL as follows:

GO TO label...label : x = GAUSS(mean, sigma)

This expands to the Fortran code:

GO TO 99996...Z09999 = MEAN + GRV(ZZSEED)*(SIGMA)

9999 6 X = Z09999

With the MACRO call in a labeled statement, the intermediate variable Z09999 is notassigned a value when the GO TO transition is executed. However, if a CONTINUE isused at the labeled statement as follows:

GO TO label...label: CONTINUEx = GAUSS(mean, sigma)

the code expands into the correct sequence as follows:

GO TO 99996...

99996 CONTINUEZ09999 = MEAN + GRV(ZZSEED)*(SIGMA)X = Z09999

UseCONTINUEstatements

One solution to the label problem originally considered was to attach the LABEL tothe first line of the code generated from the MACRO. Then, however, DO loopsbecame the problem, since the label must be the last operation of the loop (statementsafter the labeled statement are not in the loop). Even if ACSL differentiates betweenthe DO loop labels, the language allows a loop with direct GO TOs to the terminatingstatement label;e.g.,

2. Language Elements 2.4 Labels


DO labe l i = 1, 20...IF (condition) GO TO label...label : x = x + GAUSS(mean, sigma)

To formulate rules to translate this sequence appears to be impossible. If this operationis programmed with labeled CONTINUE statements, two labels will be necessary andthe translation is straightforward;i.e.,

DO label 1 i = 1, 20...IF (condition) GO TO label2...label2: CONTINUEx = x + GAUSS(mean, sigma)label1: CONTINUE

2.5 Expressions

An expression is a combination of operators and operands which, when evaluated,produces a single numerical value. Expressions may contain arithmetic, relational, andlogical operators. ACSL syntax for expressions is the same as in Fortran.

Arithmeticoperators

The arithmetic operators are:

+ addition- subtraction* multiplication/ division** exponentiation

Two operatorstogether

Two arithmetic operators can not appear next to each other in an arithmeticexpression. If minus is to be used to indicate a negative operand, the sign and theelement must be enclosed in parentheses if preceded by an operator;e.g.,

b*a/(-c) -a*b - c a*(-c)

are all valid, but the following is not:

b*a/-c

Warning –dividing by

integer

Dividing by an integer (i.e., assuming that the integer is promoted to floating point)sometimes gives incorrect results. For example, the first calculation results in zero, butspecifying the 2 in floating point gives the correct result:

x = 1/2/pi zerox = 1/2.0/pi correct

ANSI standard forbids changing I/J/R to a supposedly equivalent I/(J*R). Thefollowing guidelines apply:

1/2 integer zero1/2.0 floated to floating point1/(2*pi) okay1/pi/2 okay

Parentheses Parentheses can be used to indicate groupings as in ordinary mathematical notation,but they cannot be used to indicate multiplication.

2.5 Expressions 2. Language Elements


Relationaloperators

The relational operators, the results of which can be only TRUE or FALSE, are:

.EQ. equal to

.NE. not equal to

.GT. greater than

.LT. less than

.GE. greater than or equal to

.LE. less than or equal to

Logicaloperators

The logical operators are:

.EQV. combines two logical expressions to give the value TRUE when they areequivalent; otherwise, the value is FALSE

.NEQV. combines two logical expressions to give the value of TRUE when theyare NOT equivalent; when the two expressions are equivalent, the valueis FALSE

.NOT. reverses the truth of the logical expression that follows it

.AND. combines two logical expressions to give the value TRUE when BOTHare TRUE; otherwise, the value is FALSE

.OR. combines two logical expressions to give value TRUE when EITHER isTRUE; otherwise, the value is FALSE

Operands Operands may be constants, variables (simple or subscripted), or functions. Examplesof arithmetic expressions include:

a 5.76 -(c + del*aero)3 + 16.5 b + a(5)/2.75 (b - SQRT(a**2 + x**2))/2.0

Relationalexpressions

Relational expressions are a combination of two arithmetic expressions with arelational operator. The relational expression will have the value TRUE or FALSEdepending on whether the stated relation is valid or not. The general form of therelational expression is:

a1 op a2

whereai are arithmetic expressions andop is a relational operator. A relationaloperator must have two operands combined with one operator; thus, the form:

a1 op a2 op a3

for example:

A .EQ. B .EQ. C

is not valid. Examples of valid relational expressions include:

a .EQ. b a + d .LT. 5.3a57 .GT. 0.0 (5.0*b - 3.0) .LE. (4.0 - c)

Logicalexpressions

Logical expressions are combinations of logical operands and/or logical operatorswhich, when evaluated, will have a value of TRUE or FALSE. The general form of thelogical expression is:

l1 op l2 op l3 op ⟨ ln

whereli are logical operands or relational expressions. Examples are:

2. Language Elements 2.5 Expressions


LOGICAL aa, cc, lfuncaa .AND. (b .GE. c) .OR. cc .AND. lfunc(x,y) &

.AND. (x .LE. y) .OR..NOT. aa

Note that the symbolic names AA, CC, and LFUNC have been declared to be of typeLOGICAL, and LFUNC is a function with a TRUE or FALSE result calculated fromthe value of the variables X and Y.

Characterexpressions

Character constants and variables can be joined together by the // operator. Substringsof characters can be selected by a colon (:) operator; a substring may not be of zerolength. For example:

c1 = c2(5:10)//c3

where C1, C2, and C3 are character variables. A character variable may not appear onboth the left and right hand side of the same statement.

Integers can be converted to characters through the CHAR function; for example:

name = first//last//CHAR(period)

Mapping for the CHAR function depends on the character code used by the compiler.ASCII is almost universal.

Single characters can be converted to integer (in the opposite direction to CHAR) bythe ICHAR function.

Expressionsin functions

Arguments of functions may, in general, be expressions. Since expressions can containfunctions, an arbitrary depth of complexity can be generated. Using the SIN and COSfunction as an example, the following is a valid expression:

a + SIN(x*COS(5*x + y) - COS(a + z/SIN(5.3*c) &+ c*y/SIN(SIN(x + y)*pi)))

The sole requirement for an expression is that it have only one value when evaluatednumerically.

2.5 Expressions 2. Language Elements


2. Language Elements 2.5 Expressions


3. Program Structure

3.1 Implicit andexplicit structure

It is possible to write a simulation model in ACSL with only PROGRAM and ENDstatements to outline the model structure. This is known asimplicit structure because itimplies that the whole program is a DERIVATIVE section. This simple structure haslimitations, especially in handling initial conditions.

The more flexibleexplicitstructure includes INITIAL, DYNAMIC (with embeddedDERIVATIVE and DISCRETE), and TERMINAL sections, as shown in Figure 3-1. Ifthis method is chosen, any or all of the five explicit blocks may be included. The orderof the sections must be as shown, and each section must be terminated with its ownEND statement.

3.2 Program flow

Figure 3-2 outlines the flow of an ACSL program with explicit structure. A program isactivated with a runtime START command.

PROGRAM

INITIAL

Statements executed before the run beings.State variables do not contain the initial conditions yet.

END

DYNAMIC

DERIVATIVE

Statements to be integrated continuously.END

DISCRETE

Statements executed at discrete points in time.END

Statements executed each communication interval.END

TERMINAL

Statements executed after the run terminates.END

END

Figure 3-1. Outline of explicitly structured program


INITIAL The program proceeds sequentially through the INITIAL section, the section forcalculations performed once before the dynamic model begins. Initial condition valuesare moved to the state variables (outputs of integrators) at the end of the INITIALsection, but not all initial conditions will have been defined. Usually some initialconditions are calculated at this point. Any variables that do not change their valuesduring a run can be computed in INITIAL. However, CONSTANT statements are notrequired to be placed in the INITIAL section; they are not executable and can beplaced anywhere in the program.

DERIVATIVEDISCRETE

The integration routine is initialized when control transfers out of the INITIALsection. This initialization procedure involves transferring all initial condition valuesinto the corresponding states and evaluating the code in the DERIVATIVE andDISCRETE sections once. This action is taken to ensure that all calculated variablesare known before recording the first data point. Note that it may appear from theprogram listing that the DYNAMIC section is executed before the DERIVATIVEsection; in fact, DERIVATIVE and DISCRETE are evaluated first and should not relyon calculations in the DYNAMIC section to initialize variables for DERIVATIVE orDISCRETE sections. On the other hand, all values calculated in the DERIVATIVEand DISCRETE sections are available in the DYNAMIC section.

DYNAMIC After initialization and evaluation of the DERIVATIVE and DISCRETE code, theSTOP flag is reset and the program executes the code within the DYNAMIC block.There are no restrictions on the variables that can be referred to in this DYNAMICsection. All the states have values, and intermediate calculations in the DERIVATIVEand DISCRETE sections have been executed.

STOP flag After the DYNAMIC section has been evaluated, the STOP flag is tested; if the flaghas been set, control is transferred to the TERMINAL region. The STOP flag is set bythe TERMT statement; if any TERMT statements are included in the DYNAMICblock, control is transferred at this check when one of the arguments of TERMTbecomes true. If the STOP flag has not been set, the program writes out the values ofall the variables specified in the OUTPUT and PREPARE lists, the former to theoutput file or terminal, the latter to a scratch file for later plotting and/or printing.

Integration The integration routine is now asked to integrate over a communication interval (oruntil a termination condition is met) using the code embedded in the DERIVATIVEblocks to evaluate the state variable derivatives.

The integration routine returns with the states advanced through the communicationinterval and again the STOP flag is tested. At this point, the flag may have been set bya TERMT statement in a DERIVATIVE or DISCRETE section; if not, the programloops and re-executes the DYNAMIC section.

Transfercontrol

Control can be transferred between some sections using GO TOs and statement labels,if needed. It is illegal to transfer into the DYNAMIC region, since the integrationinitialization then could not be performed correctly. Transferfrom the dynamic regionto either INITIAL or TERMINAL is quite acceptable; so also is transfer betweenINITIAL and TERMINAL blocks. Control cannot be transferred either into or out ofDERIVATIVE or DISCRETE sections since these are changed into a separatesubroutine and, as such, are inaccessible to the main program loop.

TERMINAL Program control transfers to the TERMINAL section when the STOP flag has been setTRUE. On passing out of the last END, control returns to the ACSL executive, whichreads and processes any further runtime commands (PLOT, DISPLAY, etc.). Note thatif a jump (GO TO) sends control from the TERMINAL section back to the INITIAL,the last output is not written out unless the LOGD operator is used (see Chapter 4).

3. Program Structure 3.2 Program flow


Figure 3-2. Main Program Loop of ACSL Model

3.2 Program flow 3. Program Structure


3.3 Programsorting

The ACSL translator sorts the code in the DERIVATIVE section so that outputs arecalculated before they are used. Sections other than DERIVATIVE are sorted only ifthe SORT keyword is specified. Sorting takes place onlywithin sections, never acrosssections. The sort algorithm is relatively simple and consists of two passes.

First pass Pass number one examines each statement; output variables are marked as calculatedand an input list consisting of all variables on the right of the equal sign is establishedfor the statement. A variable name may appear simultaneously on both left and righthand sides of an equal sign in either an assignment statement or PROCEDURALheader. In this case, sorting takes place only on the left hand or output variable so thatthe block is positioned before any use of the variable.

Second pass Pass number two takes the list of statements and examines them in turn. If none of thevariables on the input list have their calculated flags set (meaning that the variable hasalready been calculated), the statement is added to the compile file and the calculatedflag for the output variable (or variables) is turned off. If any of the variables on theinput list are marked calculated, the statement is saved in memory and the nextstatement examined. If any statement has been added to the compile file, all the savedstatements are re-examined to see if they can now be added to the compile file andtheir calculated flags reset. This algorithm works because any output variables thathave already been processed have their calculated flags reset. Only output variablesappearing later in the program are flagged and as such can hold up statements thatdepend on these outputs.

States State variables are not flagged as calculated. States are calculated by the integrationroutine before all derivative evaluations.

Counters One-line algebraic loops are allowed as a way to mechanize counters. Technically, itshould be identified as an unsortable statement block, but it is a useful procedure thatis generally not a problem.

x = x + b

Example The following example demonstrates the sorting procedure. These statements appearin DERIVATIVE code:

CONSTANT pi = 3.142, rz = 1.0area = pi*r**2r = rz + lrlr = INTEG(area, 0.0)

The first statement is translated into a Fortran DATA statement and an I/O list isestablished. There are no inputs and variables PI and RZ have their calculated flags set.

DATA PI/3.142/,RZ/1.0/

The second statement has inputs PI and R, and variable AREA has its calculated flagset. The third statement has inputs RZ and LR; the calculated flag for R is set. The laststatement establishes LR as a state and AREA as the derivative. The calculated flag forLR is not set; it is assumed to be known from the start because it is a state variable.

At the end of the first pass, the symbol table looks like Table 3-1, and the calculatedflags are set as in column (a). The second pass starts by reading the statements insequence again, along with the associated I/O lists. The first statement has no inputlist, so it can be output to the compile file directly, at which time the calculated flagsfor PI and RZ are reset, as shown in Column (b).

3. Program Structure 3.3 Program sorting


No other statements are pending, so the second statement is read. The inputs are PI andR. R is still flagged as calculated, so the statement is saved. The third statement isread. The inputs to this statement are RZ and LR. Neither of these inputs is flagged, sothat statement is transferred to the compile file and the output variable flag for R isreset, as shown in column (c). The saved statement is re-examined, and now no inputvariables are flagged, so the statement can be disposed of, erasing the flag on AREA.

Any well posed problem (without algebraic loops) can be completely sorted by thismethod and the compile file then has all the statements correctly ordered.

CONSTANT CONSTANT statements are best placed where they are used. Since CONSTANTstatements are treated like regular assignment statements for sorting purposes, theyshould not be placed at the end of the program as almost all the other statements wouldhave to be saved or held up, slowing translation time.

Algebraicloops

Algebraic loops are identified during translation by the fact that statements are leftover at the end of the DERIVATIVE section sort. This is considered an error sincetrue algebraic loops should be broken by calculations, PROCEDURALs, or theimplicit integrators IMPLC (scalars) or IMPVC (vectors).

Theunsortable statement blockdiagnostic lists all the statements involved in thealgebraic loop. It is usually easiest to follow the loop backwards from the bottom ofthe list, where you will find that each variable on the left side of an equal sign appearson the right hand side of the statement above it. PROCEDURAL blocks makefollowing the path more difficult since the entire block is listed and considered as onestatement. The position is determined by the variables on the left and right hand sideof the PROCEDURAL header. When the code is reconstructed by the translator, thePROCEDURAL header is lost, so the dependencies for the entire code block should benoted by hand to clarify the sequence.

The translator diagnostic listing of the algebraic loop delimits each original line orblock by four periods (. . . .) so that each PROCEDURAL block can be recognized;variable names may have been changed and macros expanded, making identificationof individual code blocks difficult without this aid.

Most algebraic loops are programming errors caused by incorrect PROCEDURALheaders or missing state equations. For example, the following code:

PROCEDURAL (a, b = c, d)a = cb = dEND ! of procedurald = a

Table 3-1. Calculated flags in symbol table during sort

Symbol(a)

beginpass 2

(b)after

CONSTANT

(c)after R=statement

(d)after AREA=

statement

area ON ON ONlrpi ONr ON ONrz ON

3.3 Program sorting 3. Program Structure


causes an algebraic loop to be reported since it implies that A is a function of both Cand D, although this is not actually the case. Use PROCEDURALs sparingly and withcare. Using many small PROCEDURALs is better than using a few large ones.

Diagnosingloops

When an unsortable statement block is diagnosed, first check the PROCEDURALs forerrors. Second, check for a modelling error such as a missing state in a control loop.

MultipleINITIAL,

DYNAMIC,and

TERMINALsections

INITIAL sections and TERMINAL sections can be placed anywhere in a program.The translator appends each INITIAL section to the end of any collected previously (toa default null INITIAL if there is no explicit user INITIAL before the DYNAMIC orDERIVATIVE). Similarly, TERMINAL sections are collected as the translator sortsthrough the program, each appended to any collected previously. Thus, anyTERMINAL sections defined in a DERIVATIVE section, for example, occur beforethe code in an explicit final TERMINAL section.

Sectionnesting

As of Version 11.5, any section (INITIAL, DYNAMIC, DERIVATIVE, DISCRETE,or TERMINAL) can be nested within any other section, to any level of nesting. Forexample, in a DERIVATIVE section, one can now write:

SCHEDULE burnout .XN. accelerationDISCRETE burnout

INITIAL; dt = GAUSS(0.050, 0.001); ENDSCHEDULE separation .AT . t + dt

END ! of burnout

3.4 Preset ofuser variables

The ACSL executive presets all floating point variables to 5.5555E33, integers to55555333, and logicals to .FALSE. The reason for this presetting is so that if avariable is used before it is calculated, drastic results are seen. This helps prevent yourunknowingly using wrong answers. It particularly points up situations where a valueof zero would allow the program to proceed when it should not.

An especially insidious situation can occur when variables are not calculated beforebeing used in the case where more than one START is executed in a runtime session.All runs after the first then use values left around at the end of the previous run.Setting all user variables to a large number allows you to identify uncalculatedvariables in the first debugging runs.

3.5 Preset ofderivatives

The ACSL executive presets all derivatives and residuals (as defined in INTEG,INTVC, IMPLC, and IMPVC statements) before each START to 3.33333333E-33.After the initial evaluation of the DERIVATIVE section, the executive checks that allderivatives have changed from the preset value; if not, an error message is produced:

DERIVATIVE NO. n NOT CALCULATED

This message usually indicates that a derivative calculation has been skipped or that aderivative is specified with a CONSTANT statement, which is not executable. Youcan determine which derivative is referenced in the message by checking a DEBUGdump or DISPLAY/ALL and counting down the list of derivatives.

3. Program Structure 3.4 Preset of user variables


4. ACSL Statements

4.1 Introduction

This chapter describes in detail all the basic statements recognized by the ACSLtranslator. A number of these are the same as equivalent Fortran statements, with theexception that ACSL places no restriction on column placement of the code.

FORTRANfunctions

Descriptions of Fortran functions are included in this chapter for convenience. Werecommend using only the generic functions since these are typed according to thetype of argument and output;e.g., use ABS instead of IABS, DABS, or CABS andMAX instead of AMAX0, AMAX1, MAX0, MAX1, DMAX0, or DMAX1. Tospecify one of the typed (non-generic) functions reduces flexibility, while the genericfunctions adapt to single or double precision, INTEGER or REAL type, automatically.

Documentationconvention

In the following examples and descriptions, elements in lower case are syntacticalelements (i.e., variables) and may be replaced with any character string that satisfiesthe definition. Elements shown in upper case must be exactly as spelled out in thestatement (although not necessarily in upper case). In specifying the integrationoperator, for example, the word INTEG must be given exactly while all the otherelements are variables you name as part of the model. The form is specified as:

state = INTEG(deriv, ic)

An example would then be in the form:

x = INTEG(xd, xic)

! & ; : The use of these characters in program code is described in this chapter underComment (!), Continuation (&), and Separator (;). The ampersand (&) is also used forconcatenation in macros (see Chapter 6). Statement labels, using a colon (:), arediscussed in Chapter 2. Wild cards (* and ?) are available for many of the runtimecommands (see Chapter 5), but are not used in program code.

CONSTANTrecomputation

Variables defined in CONSTANT statements generally should not also be defined inassignment statements, so if the translator encounters this situation, it issues thefollowing warning message:

Warning: Re-computing a constant

See the section on CONSTANT in this chapter. The warning message can besuppressed, as described in theACSL Sim User's Guide.

Debugging Calls to LOGD can help in debugging a program when no system debugger isavailable. See LOGD in this chapter for a description of this procedure. See Chapter 7for a complete discussion of debugging.

Equal sign (=) ACSL uses the equal sign in an unfamiliar way. In translating a program, ACSL needsto know the inputs and the outputs to each statement so that the statement sequencecan be sorted into the correct order. In assignment statements, all variables to the rightof the equal sign are inputs; the variable to the left is given the single numerical valueof the right hand expression and thus is the output. This concept is extended to caseswhere more than one element is an output;i.e., all elements to the left of the equal signare considered outputs and those to the right are considered inputs.


Equal sign inPROCEDURAL

This concept of the use of equal signs is extended to the PROCEDURAL, which hasthe following possible form:

PROCEDURAL(a, b, c = d, e)... block of statementsEND

This code tells the translator to treat the statements bracketed by the PROCEDURALand its matching END statement as a block (i.e., not to rearrange the order within theblock); that D and E are inputs; and that A, B, and C are outputs. Only variablescalculated elsewhere in the same DERIVATIVE section must be listed on the inputlist. Constants need not appear on the list. However, beware – today's constant istomorrow's variable! State variables (output of state operators) must not appear on thelist.

See the section in this chapter on PROCEDURAL for details on when and how to usethis structure. See Chapter 3 for information on program flow and statement sorting.

Operators forsimulation models

Included in this chapter are descriptions of a number of functions especially designedfor simulation models. In general, the output of each function is a single number(usually floating point) and the arguments are arithmetic expressions of arbitrarycomplexity;i.e., these expressions may contain functions which contain argumentswhich contain functions to any depth. Logical or relational expressions are used todetermine switching criteria in the special functions; use only .TRUE. or .FALSE. forlogical constants. Any other representation for logicals may not be recognized sincethe bit pattern of logicals depends on the installation and Fortran compiler in use.

State operators Some operators involve state variables and can be invoked only from within aDERIVATIVE section. While they may be included in a first level PROCEDURALblock, these operators are always executed and cannot be successfully by-passed byjumping around them. They also cannot be iterated in a DO loop. The following is apartial list of such operators:

CMPXPL DBLINT IMPLC IMPVC INTEG INTVC LEDLAGLIMINT OU REALPL TRAN

If an attempt is made to skip around any of these statements, the derivative for thestate variable is usually left a non-zero value (constant while the operator is skipped)so that the internal state variable continues to change. The correct method for stoppinga state variable from changing is to ensure that the derivative is set to zero.

Array nameconflicts

ACSL operator macro names should not be used for arrays names because of apotential conflict. There is no problem with scalars, but when an array element isreferenced on the right side of an equal sign, it is seen as an argument to the systemmacro. ACSL cannot check that the name is also defined as an array because theTABLE statement defines an array to hold the data and a macro of the same name fortable lookup. ACSL operators whose names should not be used for arrays are:

BCKLSH CMPXPL DBLINT DELAY DELAYP DERIVTDELSC DELVC EXPF GAUSI GAUSS HISTORYIMPL IMPLC IMPVC INTEG INTVC LEDLAGLIMINT LIMIT LINEAR LINES MODINT OUOUTPUT PREPAR PTR RADC RADCI RDIGRDIGI REALPL RESET RSHM RSHM RSHMIRTDEVICE RTP SCALE SMOOTH TERMT TRANTRANZ UNIF UNIFI WDAC WDACF WDIGWDZGI WSHM WSHMI ZOH

4. ACSL Statements 4.1 Introduction


Standalone formof operators

Some operators are defined as macros, and when the operator has only one output, twoalternative forms of invocation (conventional and standalone) are possible. As anexample, consider REALPL, the first order lag. A conventional use of this operator is:

y = k1*REALPL(t1, x)

where the state variable (output of the real pole function) is given a dummy name (a Zvariable). It is usually advantageous to multiply the input rather than the output byconstants (synonymous if the operator is linear) as follows:

y = REALPL(t1, k1*x)

so that the input to the operator is now an expression. In this form of the expression,the standalone macro invocation can be used as follows:

REALPL(y = t1, k1*x)

and in this case (only) the variable Y is assigned to the state table. This standaloneform is usually preferred in order to minimize the number of dummy variables, butnumerically all forms are equivalent.

Operators that can be given in standalone form are so indicated in their individualdescriptions. They are:

BCKLSH CMPXPL DBLINT DELAY DELSC DELVCEXPF GAUSS HISTORY LEDLAG LIMINT LINEAROU REALPL SMOOTH TRAN UNIF

Precision ofoperator

arguments

In the description of arguments, many are described as real floating point expressions.The precision of this type of expression varies according to the global ACSLtranslation mode;i.e., single precision or double precision. All the subroutinesdescribed here adapt automatically to this type change, either by the conversion rulesof Fortran for intrinsic functions like SIN, COS, MAX, MIN, etc. or else by selectionof a different ACSL runtime library.

Precision ofACSL operators

The runtime library provides copies of ACSL functions and subroutines witharguments of the correct type. For example, BOUND comes in two versions, one thataccepts all the arguments in single precision and produces a single precision result,and one that accepts all the arguments in double precision and produces a doubleprecision result. This changeover is automatic with the selection of the single ordouble precision mode on the ACSL command.

Selecting globalprecision

The mechanism for selecting the ACSL runtime library depends on the computeroperating system. For example, on Unix systems, the-x option specifies doubleprecision; on VAX systems, the /DOUBLEPRECISION switch does the same. See theACSL Sim User's Guide.

Specifyingprecision inmodel code

We recommend that single or double precision not be specified in the program so thatACSL can handle all floating point variables according to the runtime library selected.All unspecified floating point variables are considered REAL (single precision) withthe single precision library and DOUBLEPRECISION with the double precisionlibrary. When sizing arrays, use the DIMENSION statement rather than REAL orDOUBLEPRECISION; for example:

DIMENSION a(2,4), b(5,5,5), rm(3)

Forcing precision Forcing precision is usually necessary only if a variable is to be an argument to anexternal subroutine within which a particular precision is specified. Assume asubroutine MYSUB with two scalar real arguments, one scalar double and one vectordouble precision arguments;i.e.,

4.1 Introduction 4. ACSL Statements


CALL mysub(rs1, rs2, ds1, dv2)

Then types would be specified as follows to ensure consistency within the subroutine:

REAL rs1,rs2DOUBLEPRECISION ds1,dv2(20)

Another approach is to use the generic type changing functions REAL( ) and DBL( )for the scalars. Then the type has to be specified only for the vector as follows:

DOUBLEPRECISION dv2(20)CALL mysub(REAL(rs1), REAL(rs2), DBLE(ds1), dv2)

This is the preferred way since the actual precision of the variables RS1, RS2, andDV1 is immaterial in the ACSL program.

4.2 ABS

FORM: y = ABS(x)

The outputy is the absolute value ofx wherex is an expression. The output type(INTEGER, or REAL, DOUBLEPRECISION) depends on the input type. An exampleusing ABS is:

cd = cdz + cdal*al + cdde*ABS(dle)

4.3 ACOS

FORM: y = ACOS(x)

The outputy is the arc cosine ofx wherex is a floating point variable or expressionlying between -1.0 and +1.0. The result, in radians, lies between zero andπ; its type(REAL or DOUBLEPRECISION) depends on the input type. An example usingACOS is:

th = ACOS(x/r)

4.4 AINT

FORM: y = AINT(x)

The outputy is the truncation ofx wherex is a floating point variable or expression.The output type (REAL or DOUBLEPRECISION) depends on the input type. Thisfunction differs from INT where the output is type INTEGER for any type input. Inthe following example, the result is -3.0.

a = AINT(-3.7)

Since INT( ) is promoted to REAL or DOUBLE as appropriate in any expression, theonly situation where it is necessary to use AINT( ) is in the argument to a subroutinein order to force the type. For example, if the first argument of MYSUB is floatingpoint, the following ensures a truncated (integer) value, but transmitted as a floatingpoint number:

CALL mysub(AINT(v1), ...)

4. ACSL Statements 4.2 ABS


Using INT( ) in this situation doesn't work since the argument is passed with typeinteger.

4.5 ALGORITHM

FORM: ALGORITHM name = integer constant

DEFAULT: name: IALGinteger constants: 5

wherenameis the new name for the integer defining the runtime algorithm. With thisstatement, you can change the system variable name and/or the choice of integrationroutine. The name IALG is the default and its value may be set numerically at runtimeeven if the ALGORITHM statement has not been specified in the program.

Array withmultiple sections

If a program contains only one DERIVATIVE section and no DISCRETE sections,ALGORITHM name (referred to by its default name IALG hereafter) is a scalar;however, more than one DERIVATIVE and/or DISCRETE section results in IALGbecoming an array. The elements in IALG then correspond to the sections in the orderthey are encountered in the source code. If ALGORITHM is defined outside aDERIVATIVE section, then it is the global default for all DERIVATIVE sections;DISCRETE sections have their algorithm slot set automatically zero. To change thealgorithm for a specific DERIVATIVE section, put an ALGORITHM statement with aunique name in the section; for example,

DERIVATIVEALGORITHM fastalg = 4

The scalar name given is equivalenced to the array element; for example, if theDERIVATIVE section is first in the program,FASTALGis equivalenced to IALG(1).At runtime, either the array element or the local name can be referenced.

SET IALG(1)=1SET fastalg=8

Table 4-1. ACSL integration algorithms

IALG algorithm step order

1 Adams-Moulton variable variable2 Gear's stiff variable variable3 Euler fixed first4 Runge-Kutta fixed second5 Runge-Kutta fixed fourth6 none – –7 user-supplied – –8 Runge-Kutta-Fehlberg variable second9 Runge-Kutta-Fehlberg variable fifth

10 Differential algebraic system solver variable variable

4.5 ALGORITHM 4. ACSL Statements


Warning – do notchange during

run

The choice of integration algorithm cannot be changed during a run because tablespace has to be allocated before the run begins. After once determining IALG for arun, ACSL never looks again to see if it has changed. The communication intervaland/or integration step sizecanbe changed.

Recommendedintegration control

Table 4-1 lists the available integration algorithms. For fixed step algorithms, werecommend setting NSTEPS (NSTP) to 1 so that you control the step size withMAXTERVAL (MAXT) and the data logging rate with the communication intervalCINTERVAL (CINT). The integration step size for fixed step algorithms is calculatedby:

H = MIN(MAXT, CINT/NSTP)H = MIN(H, time_to_next_event)

CINT is divided by NSTP. If NSTP is 1 and MAXT is less than CINT, then MAXTsets the integration step size and CINT affects only the data logging rate. Eventsinclude DISCRETE sections (usually controlled by an INTERVAL statement), stateevents or time events activated by SCHEDULE statements, and CINT. CINT does nothave to be an even multiple of MAXT since the integration steps up to it automatically.

Fixed stepalgorithms

The Runge-Kutta routines (IALG = 4 and 5) evaluate the derivatives at various pointsacross a step. A weighted combination of these derivatives is then used to step acrossthe interval. Euler (IALG=3) makes just one derivative evaluation and the step sizemust be small compared to that of other algorithms to achieve acceptable accuracy.Euler is used for any integrations required by operators in DISCRETE sections.Runge-Kutta second order advances the state with two derivative evaluations per step.This usually needs a somewhat smaller step than Runge-Kutta fourth order (fourderivative evaluations per step). For the same step size, it should run about twice asfast. Optimizing the step size and algorithm is generally worth the effort.

Runge-Kuttaprocedure

Figure 4-1 shows the procedure for the fourth order Runge-Kutta algorithm. Ifx is thestate,h is the integration step size, andt is time, the derivativek is evaluated at thebeginning, twice at the midpoint, and once at the end of the integration step as follows:

k1 = f (xn , tn )

k2 = f

xn +hk1

2, tn + h

2

k3 = f

xn +hk2

2, tn + h

2

k4 = f ( xn + hk3 , tn + h )

The new state is then calculated by:

xn+1 = xn + h6

( k1 + 2k2 + 2k3 + k4 )

The second order Runge-Kutta routine follows a similar procedure, making onederivative evaluation at the beginning and another at a point two-thirds across the stepas follows:

k1 = f ( xn , tn )

k2 = f

xn +2hk1

3, tn + 2h

3

4. ACSL Statements 4.5 ALGORITHM


The new state is then weighted by one-fourth and three-fourths and calculated by:

xn+1 = xn + h4

( k1 + 3k2 )

MINT, XERROR, and MERROR (discussed below for the variable step algorithms)do not affect the fixed step algorithms in any way.

Variable stepalgorithms

The Adams-Moulton (IALG=1) and Gear's Stiff (IALG=2) are both variable step,variable order integration routines that are self-initializing. In general they attempt tominimize the step changing by always choosing a step size that divides evenly into thetime-to-go to the next event and keeping the per-step error in each state variable belowan allowed value. This desired value is obtained by taking the maximum of thecorresponding absolute allowed error (XERROR) and the relative allowed error(MERROR) multiplied by the maximum absolute value of the state so far:

Ei = MAX (Xi, Mi ∗ |Yi |MAX )

The order of integration starts at one and then changes dynamically as the programprogresses. The step size also changes dynamically as the integration routine attemptsto take the largest possible step consistent with the allowed error bounds.*

Adams-Moulton Adams-Moulton is useful for models in which the step size changes significantlyduring a simulation, as for a satellite in a highly eccentric orbit. In this case, a muchlarger step size can be used when the satellite is far from the earth than when it is near.This algorithm can also help determine an appropriate step size for fixed step runs, asdescribed below.

Figure 4-1. Runge-Kutta fourth order algorithm



* For more information on mechanization of the variable step, variable order integration routines, see subroutineDIFSUB in Numerical Initial Value in Ordinary Differential Equations, C.W. Gear, Prentice-Hall, NJ 1971 pp150et seq.

Gear's stiff Gear's algorithm is for stiff systems that have frequencies of three or four orders ofmagnitude difference, where the high frequency motions are extremely active at somepoint (such as in a chemical reaction, explosion, etc.) and then smooth to essentiallyzero amplitude. The Gear's stiff algorithm is then able to take large time steps sinceonly the low frequency motions are of interest.

Gear's stiff integration can take steps that are orders of magnitude larger than thesmallest time constant in a stiff system. There is an overhead involved, however, sincea linearized state transition matrix must be formed and inverted. Tests have shown thatfor problems where the range of time constants differs by only one or two decades,there is little benefit in using this method; Adams-Moulton is invariably faster. If therange of time constants covers more than three or four decades, then this techniquemaybe significantly faster than any other.

Runge-Kutta-Fehlberg

The Runge-Kutta-Fehlberg algorithms (IALG = 8, 9) are fixed order but variable step.They are useful for models with a number of discontinuities, such as a system in whicha spring is encountered periodically. The Adams-Moulton method uses informationfrom previous steps to determine the size of the current step, but theRunge-Kutta-Fehlberg method starts fresh each step, thus having less difficulty withdiscontinuities. These routines adjust the step length to keep the error per step less thanthat specified by XERROR and MERROR. The relative error (MERROR) values areapplied to the largest absolute value of the state so far, not the current value.

Algorithm 8 evaluates the derivative three times per step and makes a second orderstate advance; algorithm 9 evaluates the derivative six times and makes a fifth orderstate advance. If any error in a state is larger than that allowed, the step size is reduced(by no more than 0.1 at a time) until the error criteria are satisfied for all states or theminimum step size (MINT) is reached. After a successful step, the new step size is setto be 0.8 (for IALG = 8) or 0.9 (for IALG = 9) of a step size which would result in themaximum allowable error (as calculated during the previous step), except that the newstep size is not less than the previous successful one.

The lower order algorithm (IALG = 8) is recommended for most applications becauseit usually uses less computer time.

Differentialalgebraic system

solver (DASSL)

The DASSL code* (IALG of 10) is intended to directly solve implicit differentialalgebraic equations (DAEs) where the derivative term cannot be specifically isolatedon the left hand side of an equation. In this case, instead of:

Y.

= F(Y, t)

we have:

F(Y, Y., t) = RESIDUAL = 0

whereF, YandY.

are N-dimensional vectors and the zero is really the residual that isbeing driven to zero. The following introductory description is take from Brenan,Campbell, and Petzold p. 117. The basic idea for solving the DAE system usingnumerical ODE methods, originating with Gear, is to replace the derivative in theabove equation by a difference approximation and then solve the resulting system forthe solution at the current time using Newton's method. Replacing the derivative bythe first order backward difference, we obtain the explicit Euler formula:

4. ACSL Statements 4.5 ALGORITHM


* For more information on the mechanization of DASSL, seeNumerical Solution of Initial Value Problems inDifferential Algebraic Equations, by E.E. Brenan, S.L. Campbell, and L.R. Petzold, North-Holland, 1989.

F

Yn+1 ,Yn+1 − Yn

hn+1, tn+1

= 0

where:

hn+1 = tn+1 − tn

This nonlinear system is then solved forYn+1 using a variant of Newton's method.DASSL uses a fixed leading coefficient implementation of the BDF formula whichcan approximate the derivative to higher accuracy at higher orders. The advantage ofthefixed leading coefficient is that this is the term that appears in the iteration matrix,and the matrix only has to be recalculated on a change of step size – not on everysubsequent step – as the history washes out of the range of information needed to besaved by backward differences.

In ACSL, the implicit form:

F( Y, Y., t ) = 0

is expressed as:

y, yd = IMPLC(F(y,yd,t), yic)

and is really implemented by adding bothy andyd to the state vector as:

y = INTEG(yd, yic)yd = IMPLC(F(y,yd,t), 0.0)

Thus, for every algebraic/differential state, two slots are allocated in the state table.

MINT withvariable step

algorithms

The variable step algorithms never take steps smaller than MINTERVAL (MINT).The integration step size for variable step algorithms is calculated as for the fixed stepalgorithms with the addition of a check on the minimum step size as follows:

H = MAX(MINT, MIN(MAXT, CINT/NSTP))

NSTP withvariable step

algorithms

NSTP can be set to help a variable step algorithm start off. If the first try(CINT/NSTP) is too large (i.e., if the estimated error is larger than the allowed error),the algorithm reduces the step size and tries again, until it finds a small enough stepsize to start off. Setting NSTP to a fairly large number (1000, for example) starts theroutine at small step size, which is then increased automatically as the run progressesuntil it reaches the most efficient size. Beware of leaving NSTP at a large value andswitching to a fixed step algorithm.

Error summary An error summary is produced automatically at the end of simulation runs usingvariable step algorithms, giving the weight each state had in controlling step size. Youcan adjust the error criteria (XERROR and MERROR) using this information. Thenumber of times the predictor-corrector algorithm failed to converge and caused ageneral step size reduction is also listed. This is usually considered a more seriousfailure than bumping into the allowable error tolerance. See Chapter 7 for a moredetailed discussion. The summary may be suppressed by setting the system variableWESITG (write error summary, integration control) to FALSE. Current step size(CSSITG) and current integration order (CIOITG) are available as system variablesthat can be OUTPUT or PREPAREd.

Determiningappropriate step

size

Determining an appropriate step size for a fixed step algorithm is worth some effort. Ifa step size is too large, the results are inaccurate or even catastrophic; if too small,computer time is wasted.



For fixed step algorithms, the step size should normally be about the size of thesmallest time constant. One or two points per radian (six to ten per cycle) is sufficientto keep the system from becoming unstable. The time constants can be determinedusing the runtime command:

ANALYZE /EIGEN

The eigenvalues are listing in ascending order; these are the reciprocal time constantsof the system. The reciprocal of the largest eigenvalue is often a good choice for theintegration step size for fixed step algorithms.

Another approach is to use a variable step algorithm to see what ACSL believes to beappropriate. Use the Adams-Moulton routine and the system variables for current stepsize and current integration order as follows:

SET IALG=1PREPARE T,CSSITG,CIOITG ...STARTPLOT CSSITG,CIOITG

Check that the step size is not being constrained by CINT. If it is, increase CINT andMAXT and run the simulation again. Look at the shape of CSSITG. If it is steady, usea fixed step size just slightlylarger than the values chosen by the variable algorithm(the system choice of step size is somewhat conservative, so a slightly larger step isusually adequate). If the curve varies widely, however, consider using one of thevariable algorithms. The system choice of CIOITG should also be steady and can befactored into your choice of algorithm order and step size.

Efficiency andaccuracy

You can compare the efficiency of the various algorithms with the SPARE command;for example:

SET IALG=4SPARE ; START ; SPARESET IALG = 5SPARE ; START ; SPARE

Each SPARE command lists the cpu time elapsed since the previous SPAREcommand. Compare the accuracy of the results by printing (or plotting) significantvariables or by getting debug dumps.

4.6 ANINT

FORM: y = ANINT(x)

The outputy is the nearest whole number ofx wherex is a floating point variable orexpression. The output type (REAL or DOUBLEPRECISION) depends on the inputtype.

Since NINT is promoted to REAL or DOUBLE as appropriate in any expression, theonly situation where it is necessary to use ANINT( ) is in the argument to a subroutinein order to force the type. For example, if the first argument of MYSUB is floatingpoint, the following ensures the nearest whole number (integer) value, but transmittedas a floating point number:

CALL mysub(ANINT(v1), ...)

4. ACSL Statements 4.6 ANINT


4.7 ASIN

FORM: y = ASIN(x)

The outputy is the arc sine ofx, wherex is a floating point variable or expressionbetween -1.0 and +1.0. The output is in radians (−π ⁄ 2 ≤ y ≤ + π ⁄ 2 ); its type (REALor DOUBLEPRECISION) depends on the type of the argument. ASIN could be usedas follows:

area = 0.5*pi*r**2 - x*SQRT(r**2 - x**2) + (r**2)*ASIN(x/r))

4.8 Assignmentstatements

4.8.1 Arithmetic

FORM: variable = expression

where variable may be simple or subscripted. If a subscripted variable is used in asorted section, it must be enclosed in a PROCEDURAL block. On execution, thesingle value of the expression is stored into the location defined by variable; forexample, the results of the expression on the right side of the following statement isstored into location Y:

y = a*b + c/d

A special form of the assignment statement is the integration statement. The use of theINTEG operator marks the variable as a state variable. In the example

a = INTEG(ad, aic)

A is marked as a state variable and AD is stored as the derivative of A.

Type conversion is performed automatically from an integer, real, or double precisionexpression to an integer, real, or double precision variable.

4.8.2 Logical

FORM: lvariable = lexpression

wherelvariablemay be simple or subscripted andlexpressionis a logical expressionformed from a logical operator; for example:

flag = a .NE. b .OR. flag2

4.8.3 Character

FORM: cvariable = cexpression

wherecvariableis a character variable or substring andcexpressionis a characterexpression; for example:

cvar(5:10) = string(1:4)//'Z'

concatenates a Z to four characters extracted from STRING and places them incharacter positions 5 through 9. Unfilled character positions incvariableare filled

4.8 Assignment statements 4. ACSL Statements


with blanks. If the length ofcexpressionexceeds that forcvariable, the characterexpression is truncated on the right.

4.9 ATAN

FORM: y = ATAN(x)

The outputy is the arc tangent of the floating point argumentx wherex is unlimitedexcept for infinity and the result is in radians in the range (−π ⁄ 2 < y < +π ⁄ 2 ). ATANcould be used as follows:

al = ATAN(-vmm(3)/vmm(1))

For full coverage of the circle, it is better to use ATAN2.

4.10 ATAN2

FORM: z = ATAN2(y, x)

The outputz is the arc tangent of an angle formed by the point with floating pointcoordinatesx, y and the positive X axis;x andy can be both positive and negative,defining the full circle of revolution. The result is in radians in the range(−π < z ≤ + π ). An example of ATAN2 is:

pdgn = ATAN2(dlq, dlp + 1.0E-30)

4.11 BCKLSH

FORM: y = BCKLSH(ic, dl, x)BCKLSH(y = ic, dl, x)

where:

ic = initial condition ofydl = half the width of the backlashx = input (a floating point variable or expression)

Figure 4-2. Mechanism Illustrating BCKLSH Operator

4. ACSL Statements 4.9 ATAN


The output always lies between the limits (x - dl) and (x + dl). Figure 4-2 illustratesthe backlash mechanism.

For asymmetrical applications, the expression for the inputx should be rewritten; forexample, ify is to move whenx is greater than (Y+UL) or less than (Y-LL), then:

y = BCKLSH(yic, 0.5*(ul - ll) , x - 0.5*(ul + ll))

Warning – sorting The BCKLSH operator must be in a sorted (DERIVATIVE) section.

4.12 BOUND

FORM: y = BOUND(bb, tb, x)

where:

bb = bottom boundtb = top boundx = input (a floating point variable or expression)

The outputy is as follows:

y = bb when x < bby = x when bb ≤ x ≤ tby = tb when x > tb

This function bounds or limits variables. It should not be used to limit the output of anintegrator since the integrator itself continues to wind up and must actually integrateout of the limit. The function LIMINT should be used in this case. A statement usingBOUND could be:

MAXT = BOUND(maxtmn, maxtmx, maxtp)

4.13 CALL

FORM: CALL nameCALL name (p1, p2, ..., pn)CALL name (o1, o2, ..., on = p1, p2, ..., pn)

wherenameis the name of a subroutine being called,pi are actual arguments that maybe expressions of arbitrary complexity for input values, andoi are output variables(names or arrays). Arguments may be variables, arrays, or subscripted variables.

Note that in the second form, the translator cannot tell which arguments are inputs andwhich are outputs; if the call is in a sortable section of the program, it should beembedded in a PROCEDURAL block that describes the inputs and outputs. If the callis any other section, a PROCEDURAL is still recommended to avoid theSymbol usedbut not defineddiagnostic. For example, ifoi are output variables andpi are inputvariables or expressions, then the following statements are valid:

PROCEDURAL (o1, o2, o3 = p1, p2, p3, p4)CALL subr(o1, p1, p2, p3, p4, o3, o2)END

Now the translator sorts this section correctly since it has been told which variables areinputs and which are outputs.

4.13 CALL 4. ACSL Statements


The third form of the call is available for the case in which the subroutine is definedwith the input expressions on the left and the output variables on the right. In thisform, the subroutine could be called with:

CALL subr(o1, o2, o3 = p1, p2, p3)

The translator rearranges the order and changes the equal sign to a comma so that theresulting call to FORTRAN is:

CALL subr(p1, p2, p3, o1, o2, o3)

4.14 CHARACTER

See TYPE.

4.15 CINTERVAL

FORM: CINTERVAL name = real constant

DEFAULT: name: CINTreal constant: 0.1

wherenameis a simple unsubscripted variable.

The communication interval CINTERVAL is the interval at which the DYNAMICsection is executed and the variables on the OUTPUT and PREPARE lists have theirvalues recorded. In general, no finer detail can be seen in OUTPUT, PRINT, or PLOT,so it is important to choose this value with care. A communication interval thatgenerates about 100 to 200 data points during a run is sufficient detail for mostapplications.

Sampling effect Beware the sampling effect whereby high frequency oscillations can be folded downto lower frequencies or even a DC level if the sampling time is not small enough.

Adjusting stepsize to CINT

If the next integration step to a communication interval is less than 1.0E-11 (1.0E-6 insingle precision) of the current time (or CINT, whichever is larger), the step isdiscarded as negligible. This situation can occur because of accumulation androunding on a binary machine. The integration algorithm takes steps up to the nextcommunication interval by accumulating the fixed step (for example, with MAXT =0.01 and CINT = 0.1; after ten steps, the time isabout0.1 because of rounding in both0.01 and 0.1). To prevent accumulated roundoff error, a small adjustment is made tothe communication interval. CINT is multiplied by a power of ten until it is close to aninteger, then time is accumulated as an integer but divided by the multiplier beforebeing used.

Double precision To get full precision when changing CINT and MAXT at runtime, use the doubleprecision specification:

SET cint = 0.1D0SET maxt = 0.01D0

Calculating CINT The value of the name defined in the CINTERVAL statement can be calculated in theprogram so that different phases can be viewed at different data rates. For example,assume that a missile simulation has the following four phases of flight:

4. ACSL Statements 4.14 CHARACTER


1) Initial turn2) Midcourse3) Acquisition4) Terminal

It would be useful to measure these phases at different rates;e.g., initial turn at a fairlyfine level of 0.1 second, the long midcourse only every second, and acquisition andterminal at a fine rate of 50 msec. Figure 4-3 outlines a procedure for setting thecommunication interval for each phase. In the INITIAL section, PHASE is declared tobe an integer and initialized to one. An array CINTTAB is defined and filled with thecommunication intervals to match the phases of flight as numbered above. In theDYNAMIC section, the communication interval (using default name CINT) is setusing the current value of the flight PHASE (which ranges from one to four). In theDERIVATIVE section, the value of PHASE is computed from the logic used toestablish the different flight regions. This code is shown as a block since the algorithmdepends on the implementation of the model; but no matter how it is implemented, thevalue of PHASE is maintained in the range one to four.

Changing defaultname

The name of the variable defining the communication interval can be changed fromthe default CINT; for example,

CINTERVAL CI = 0.001

Now all references are to CI when the value is recorded or changed.

Bound onintegration step

CINTERVAL acts as an upper bound on the integration step size (and also for the lastintegration step of a communication interval) since the model is advanced no furtherthan to the data recording time no matter how large the calculated integration step size.This subject is discussed in more depth under DYNAMIC. The actual integration stepis obtained from the following algorithm:

H = MIN(MAXT, CINT/NSTP)H = MIN(H, time_to_next_event)

This applies a bound of MAXT to CINT/NSTP and then limits the step to be no morethan the time left in the current communication interval or to the next other event.

INITIALINTEGER phaseDIMENSION cinttab(4)CONSTANT cinttab = 0.1, 1.0, 0.05, 0.05phase = 1 ! Initialize phase to start...

END ! of initialDYNAMICDERIVATIVE

! Compute phase of flightPROCEDURAL(phase = , , ... )...END ! of procedural...

END ! of derivativeCINT = cinttab(phase)...

END ! of dynamic

Figure 4-3. Outline of program to vary communication interval

4.15 CINTERVAL 4. ACSL Statements


4.16 CLOSE

FORM: CLOSE(UNIT = lu [, STATUS = p])

where:

lu = an integer variable or expression for a logical unit numberp = a character string of either KEEP or DELETE

This operator closes any file that has been opened with the OPEN command.

4.17 CMPXPL

FORM: y = CMPXPL(p, q, x, ic1, ic2)CMPXPL(y = p, q, x, ic1, ic2)

This operator, listed in Figure 4-4, conveniently implements a second order transferfunction where the outputy is related to inputx through the transfer function:

yx

= 1

ps2 + qs + 1

such that:

y.

(0) = ic1y (0) = ic2

Restrictions The same restrictions on initial conditions apply as for the INTEG operator, and bothICs may be omitted if zero. The time constantsp andq may be expressions of arbitrarycomplexity, butp may not be zero. Settingp to zero results in division by zero, as canbe seen in the listing of the macro.

Warning This operator (as all the memory operators) should be used only in sorted sections andshould not be used in a PROCEDURAL block.

The CMPXPL operator could be used as follows:

x = k2*CMPXPL(a, b, xp)

4.18 Comment (!)

FORM: !string

All text after an exclamation point to the end of the line is considered a comment. Thetest is reproduced in the listing and then discarded. Examples of comments are:

MACRO cmpxpl(y,p,q,x,ic1,ic2)MACRO STANDVAL ic1=0.0,ic2=0.0MACRO REDEFINE ydotydot = INTEG(((x)-(y)-(q)*ydot)/(p), ic1)y = INTEG(ydot, ic2)MACROEND

Figure 4-4. CMPXPL operator macro

4. ACSL Statements 4.16 CLOSE


! ---------------- Calculate the derivativex = a + b ! Add 'a' and 'b' and place in 'x'a = sin(w*t) ! Forcing function acceleration

Comments can also be added after continuations (& at end of code) since thecomments are stripped off before the rest of the line is analyzed by the translator.

cm = cmz + cmal*al & ! pitch moment coefficient+ cmde*dle + (cb/(2*v))*(cmad*ald + cmtd*q)

4.19 COMMON

FORM: COMMON / cname / clist

where:

cname= the name of the common block. This name is communicated to thelinker.

clist = a comma-delimited list of variable names which may optionally bedimensioned;e.g., K(2,3,4).

Note:Don't mix CHARACTER variables with other types (REAL,DOUBLEPRECISION, INTEGER, LOGICAL) in the list. Also, usercommon block variables are not preset (ANSI Fortran requirement).

The COMMON statement provides a means of associating variables in Fortransubroutines and functions with the ACSL model code, and, in particular, entering thevariable names into the model dictionary. Entering names into the dictionary allowsconstants to be changed and variables to be viewed and plotted at runtime.

Types Variable names in the COMMON block list arenot typed automatically. StandardFortran conventions apply;i.e., variable names beginning with I, J, K, L, M, or N areconsidered INTEGER, and all other names are assumed to be floating point singleprecision. Deviations from these assumptions are handled by specific type statements,which are usually bundled with the COMMON statement in an INCLUDE file.

System variablesand states

ACSL system variables, states, derivatives, and initial conditions are allocated tospecific places by the ACSL translator and cannot be moved to external commonblocks. The system variables include all those with names starting ZZ and the programcontrol variables such as T, CINT, IALG, NSTP, MAXT, and MINT.

The states, derivatives, and initial conditions (as listed in a debug dump) also cannotbe moved to external common blocks. ACSL needs to maintain them in a linear list forthe integration routines to see as a vector. See the chapter on Debugging for moreinformation on system variables and common block names.

Examples Examples of COMMON statements are:

COMMON / scalc / x,y,z(10)REAL k1,k2COMMON / adata / k1,k2,index

In INCLUDE file A bundle of statements in an INCLUDE file could look like:

LOGICAL flag1,flag2INTEGER count1,count2REAL k1,k2COMMON / mcom / count1,flag1,k1,x2,count2,flag2,k2,x2,a(250)

4.19 COMMON 4. ACSL Statements


4.20 CONSTANT

FORM: CONSTANT d1 = a1, d 2 = k*a 2, d 3 = a31, a 32, k*a 33

where:

di = identifiers representing simple variables or array names. Implied DOloop notation may not be used. Ifdi is an array name, integer subscriptsmay be used to fill individual elements within the array, or else theentire array must be filled.

ai = literals and signed or unsigned constants or PARAMETER names.

k = integer constant or integer PARAMETER name repetition factors;the literal following the asterisk is repeatedk times.

The CONSTANT statement is similar to a Fortran DATA statement and is used topreset symbolic locations with numeric data. Since it is not an executable statement, itcan be placed anywhere in the program. The recommended placement is just beforethe statement using the CONSTANT value.

Examples Examples of the correct use of the CONSTANT statement include:

LOGICAL switch1INTEGER iiDIMENSION a(2)CONSTANT switch1=.TRUE., ii=2, a=2*1.0, b=-5.76

CONSTANT vs.assignment

statement

The effect of the CONSTANT statement is quite different from that of an assignmentstatement. The assignment statement moves data from one place to another (into thelocation for the variable to left of the equal sign) every time control passes through thestatement. The CONSTANT statement, on the other hand, just presets the variable tothe left of the equal sign when the simulation is loaded into memory. The variable canthen be overridden by assignment statements or by runtime SET statements.Assignment statements for constants such as the following should be avoided:

INITIALk1 = 5.70k2 = 7.63

END

Although these values can be changed at runtime by SET statements, they are returnedto the original value as soon as the assignment statements are executed. This precludesdoing runs with different values of the parameters. Replace the code above with aCONSTANT statement as follows:

CONSTANT k1 = 5.70, k2 = 7.63

Now the values of K1 and K2 can be changed at runtime and remain that value untilchanged again by another SET statement.

Initializingcounters

CONSTANT statements shouldnotbe used to initialize counters. For example,counters are often initialized in the INITIAL section and then incremented later:

INITIALINTEGER nn = 0

ENDDYNAMIC

n = n + 1...

4. ACSL Statements 4.20 CONSTANT


If the counter were initialized using a CONSTANT statement, the results would becorrect for the first run, but any subsequent runs would start with the value left over atthe end of the previous run.

Warningmessage

When a variable is given a value in a CONSTANT statement and later appears on theleft side of an equal sign, the translators issues a warning message:

Warning: Re-computing a constant.

The warning does not abort translation. Warning messages can be suppressed with aswitch on the call to ACSL. See theACSL Sim User's Guide.

4.21 Continuation (&)

FORM: statement &[&]continuation

Any model source code (or runtime) statement can be continued onto another line byending the first line with an ampersand (&). Any number of continuation lines isallowed (although the resulting Fortran code may be limited to twenty packed lines)and the ampersand may appear in any column up to 72. The translator removes blanksbetween the end of the code and the ampersand on the first line but carries blanks atthe beginning of the continuation line onto the compile file.

cm = cmal*al + (cmq*wm(2) &+ cmbep*be*wm(1))*d/(2.0*vmam(1))

If the continuation linebeginswith an ampersand, then blanks at the beginning of theline are dropped; this allows name and character strings to be continued withoutstarting the continuation line in column one.

charactervariable = 'longcharact&&erstring'

In other words, blanks between the two ampersands are eliminated.

Blank lines Because the syntax analyzer looks for the leading ampersand in continuations, a blankline results in a syntax error. To introduce blank lines in continuations, use twoampersands; for example:

TABLE xyz , 1 , 10 && &/-10.0 , 0.0 , 30.0 , 60.0 , 120.0 &, 150.0 , 180.0 , 210.0 , 240.0 , 270.0 && &, 8.33 , 8.33 , 4.0 , 1.6 , 5.2 &, 5.2 , 6.6 , 8.3 , 10.7 , 16.7 /

Comments Comments can be added to a continued line as follows:

x = a + b & ! Comment on the sum+ SIN(a/b)*m ! Explanation of sine function

The translator strips comments off before looking back from the end of the line for anampersand.

4.21 Continuation (&) 4. ACSL Statements


4.22 CONTINUE

FORM: label: CONTINUE

CONTINUE is normally used to transfer control after a GO TO command or toterminate a DO loop. It is the preferred statement for all labels due to problems withmacro expansions as explained in Chapter 2. Note that code using CONTINUEs andlabels generally requires the use of PROCEDURALs in sorted sections.

4.23 COS

FORM: y = COS(x)

The outputy is the cosine ofx wherex is a floating point variable or expression inradians. The result is in the range (−1.0≤ y ≤ + 1.0 ). The type (REAL orDOUBLEPRECISION) of the output and function depends on the type of theargument. A statement using COS could be:

simd = (wm(2)*COS(fim) - wm(3)*SIN(fim))/COS(thm)

4.24 DBLE

FORM: DBLE(x)

This function converts an integer, single precision, or double precision argumentx todouble precision.

The main use of DBLE is to force the precision of arguments to subroutines where theprecision of the argument cannot be deduced by the compiler. If a subroutinerequiresa double precision argument, then the type can be forced in the form:

CALL mysubr(DBLE(x1), DBLE(x2), ... )

Now whether the global translation mode is single or double precision, the inputarguments to the subroutine are the correct type. Alternatively, arguments can beforced to DOUBLEPRECISION type by:

DOUBLEPRECISION x1,x2CALL mysubr(x1, x2, ... )

This method fails however with global single precision if the inputsx1or x2are states,derivatives, initial conditions, or any of the ACSL system variables (e.g., CINT,MAXT, etc.).

Variables that aregivenvalues by the subroutine can't be supplied in function form.The reason this does not work is that the function form copies the actual argument to atemporary location. Such variables must be forced to a precision by eitherDOUBLEPRECISION or REAL; for example:

DOUBLEPRECISION y1,y2CALL mysubr(DBLE(x1), DBLE(x2), y1, y2)

A similar procedure applies for single precision where REAL forces the singleprecision type:

REAL y3,y4CALL mysubr2(REAL(x3), REAL(x4), y3, y4)

4. ACSL Statements 4.22 CONTINUE


4.25 DBLINT

FORM: DBLINT(x, xd = xic, xdd, xdic, bb, tb)

where:

x = displacement

xd = velocity (x.

)

xic = x(0); i.e., initial condition ofx

xdd = the input, acceleration (x..

)

xdic = x.

(0); i.e., initial condition ofx.

bb = bottom boundtb = top bound

The DBLINT (double limited integration) operator, shown in Figure 4-5, is forintegrator limiting when the limited output is the second integral of an acceleration.

Mass-spring-damper system

This type of limiting can best be explained in terms of the mass-spring-damper systemdescribed by:

mx..

+ bx.

+ cx = f (t )

such that:

x.

(0) = xdicx (0) = xic

where physical stops constrain the mass to move only betweenxbb (bottom bound) andxtb (top bound);i.e.,

xbb ≤ x ≤ xtb

When the displacement (x) of the mass reaches its limit, the mass must stop, implyingthat the velocity (x

.) is zero. The mass must remain stopped until the force acting on it

(f (t) − cx ) changes sign.

Alternateimplementation

An alternate way of performing this operation is to wrap a stiff spring around the loopwhen the wall is approached; this corresponds to what happens physically since thewall always has a finite spring constant. Figure 4-6 is a block diagram of such asystem where Ks is spring stiffness, Kw wall stiffness, and Kd the damping constant.The problem with this representation is in the behavior of the digital integrationroutine in the vicinity of the wall when the wall stiffness is extremely high. A moreaccurate but more complex approach is to use the SCHEDULE operator to find timesof both wall impact and wall leaving (when the force changes sign or crosses zero).

Warning This operator (as all memory operators) can be used only in DERIVATIVE sectionsand should not be put in a PROCEDURAL block.

macro dblint(x,v,xic,a,vic,lbx,ubx)macro redefine vl,icconstant ic=0.0callzzdlim(v,vl=ic,x,integ(zzlimf(x,a,lbx,ubx),vic),lbx,ubx)x=intvc(v,xic)macroend

Figure 4-5. DBLINT operator macro

4.25 DBLINT 4. ACSL Statements


4.26 DEAD

FORM: y = DEAD(bb, tb, x)

The DEAD operator implements a dead zone in outputy whenx lies between aspecified bottom boundbband top boundtb. The results can be represented as follows:

y = x − bb ; x < bby = 0.0 ; bb ≤ x ≤ tby = x − tb ; x > tb

The dead zone operator could be used as follows:

v2 = v1 + k*DEAD(vmn, vmx, v3)

4.27 DELAY

FORM: y = DELAY(x, ic, tdl, nmx, delmin)DELAY(y = x, ic, tdl, nmx, delmin)

where:

x = the input (an arithmetic expression of arbitrary complexity).

ic = the initial value of the output until the independent variable hasadvanced by the delay,tdl. This argument must be a variable name(rather than a literal constant) for the runtime command REINIT towork. REINIT needs a name into which to store the current DELAYoutput as the initial condition for subsequent runs.

Figure 4-6. Alternate implementation for DBLINT

4. ACSL Statements 4.26 DEAD


tdl = the delay time between input and output (any expression with a value≥ 0.0).

nmx = a literal integer giving the maximum number of saved data pointsneeded to represent the delay. The integration step size may vary butthe sum ofnmxintegration steps must always be greater than thecurrent time delay.

Note: This integer must be a literal integer or a parameter name with aninteger value. For example:

co = DELAY(ci, cic, cdl, 1000, cmn)

Using a PARAMETER variable:

INTEGER cmxPARAMETER(cmx=1000)co = DELAY(ci, cic, cdl, cmx, cmn)

This integernmxallocates space in a circular buffer to hold the historydata of previous sample times and previous input values. Ifdelminisdefined, thennmxshould be somewhat larger than the maximum delaytimes expected (tdl) divided by thisdelmin(or by the integration step ifit is larger).

delmin=minimum interval between saving of data points in delay buffer. Thisargument may be omitted, in which case a default of zero is used.Typically delmincan be a tenth or a hundredth of the expected delaytime and still represent dynamics adequately.

The DELAY operator delays a variable in time to model transport effects such aspassage through a pipe. It should not be used lightly since it may require considerablestorage unlessdelminis specified.

Implementation The DELAY operator is implemented by allocating a dummy array, 2*nmxwordslong, and prefilling it with the value ofic, extending over all past history. Each entryin the table is associated with a time, and at each new integration step (ordelmin,whichever is larger) a new value is inserted into the array, treating it as a circular list.To compute the output value,tdl (the current time delay) is subtracted from theindependent variable value and the table is searched for time values that bracket thisrequired previous time. A linear interpolation is performed between the correspondinginput values. If not enough data points are present, an error is reported and the runterminates.

Varying timedelay

Whentdl changes dynamically, this operator approximates the pipeline with a varyingflow rate.

Direct feedbacknot allowed

The operator provides an algebraic path from input to output, so direct feedback(without an integrator) is illegal; the following for example is not allowed:

y = DELAY((n - y)/k, yic, tdl, 1000, 0.1)

If direct feedback is really necessary, the output of the DELAY can be filtered througha real pole to break the loop. This is a good idea anyway since it eliminates jumps inthe slope of the DELAY output produced by the straight line interpolation. Forexample:

y = REALPL(tfilt, DELAY((in - y)/k, yic, tdl, 1000, 0.1))

In this situation,TFILT is chosen to be small relative to the delay time (tdl).

4.27 DELAY 4. ACSL Statements


4.28 DELSC

FORM: state = DELSC(xn, ic)DELSC(state = xn, ic)

where:

state = a simple variable (DELVC handles vectors)

xn = an arithmetic expression of arbitrary complexity; i.e., may contain furtherDELSC statements or other functions or macros.

ic = a simple non-subscripted variable, a real constant, or a generalexpression enclosed in parentheses.

DELSC produces a one-step delay between the calculation of the xn value and itsassignment to the state so that it shows up in the variable at the beginning of the nextstep.

DELSC may be embedded in any legal expression as a function that has a singleoutput: the value of the state. When the delay statement is alone, then the state namecan be identified; embedding it in an expression means that an ACSL-generatedvariable (i.e., in the form Znnnnn) is used for the state name.

Warning –DISCRETE only

The DELSC statement can be placed only in a DISCRETE section, not aDERIVATIVE section.

With initialconditions

Since DISCRETE sections are not in general sorted, if an expression is used for theinitial condition, then the DELSC expression must be placed before any reference tothe state and after the calculation of the next value, so that this form is normally to beavoided. The implementation of the expression form involves the followingexpression:

if(zzicfl) state = ic

so it is only after the expression is seen that the states has a value the first time.

In the more general case, the initial condition variable is equivalenced into the initialcondition table and the values for all the states are moved at once before anyDERIVATIVE or DISCRETE section code is executed at all.

Placement In unsorted DISCRETE blocks, DELSC must be placed after the calculation of itsinputs.

See the description of the INTEG statement for a general description of the way theACSL system build tables of states, derivatives, and initial conditions. DELSC placesthe state in the state table, the next state in the derivative table, and the initial conditionvalue in the initial condition table. The integration algorithm knows to update thedelay state variables by:

xn+1 = xn

whereas the continuous states are updated by:

xn+1 = xn + h*xd(effective) n

Examples of the use of the DELSC statement include:

y = DELSC(5.0*(x(2) + c), yz)x = 4.0*DELSC(4*y, 0)z = DELSC(znext, zic)

4. ACSL Statements 4.28 DELSC


4.29 DELVC

FORM: x = DELVC(xn, xic)DELVC(x = xn, xic)

whereX, XN, andXIC are arrays of the same size and correspond to state, derivative,and initial conditions, respectively.

The restrictions on the DELSC operator with regard to arrays can be avoided by usingthis vector integrator operator. The restrictions on the DELVC operator are identical tothose on the INTVC operator with the additional one that the DELVC statements canappear only inside DISCRETE blocks.

In unsorted DISCRETE blocks, DELVC must be placed after the calculation of itsinputs.

The following are examples using DELVC:

DIMENSION x(1), xic(10), m(5,5), mn(5,5), mic(5,5)y = DELVC(yn, yic) ! scalar delayx = DELVC(xn, xic) ! vector delaym = DELVC(mn, mic) ! matrix delay

4.30 DERIVATIVE

FORM: DERIVATIVE [name]...END

The DERIVATIVE keyword identifies the beginning of a block of code performed atthe request of the integration routine to evaluate the state variable derivatives. TheDERIVATIVE statement must be paired with a matching END statement.

Implementation The integration routine is called from the DYNAMIC section and asked to advance thestate over the next communication interval using the code embedded in theDERIVATIVE blocks to evaluate the state variable derivatives;i.e., the integrationalgorithm calls the DERIVATIVE section. The actual number of evaluations dependson the integration algorithm employed.

Transfers illegal All the statements in the DERIVATIVE section are translated into a separatesubroutine, so it is illegal to transfer control by GO TOs from DERIVATIVE sectionsto other sections (INITIAL, DYNAMIC, DISCRETE, or TERMINAL) or vice versa.

MultipleDERIVATIVE

sections

More than one DERIVATIVE section may be used, each with its own independentintegration algorithm and integration step size. Although this technique can saveexecution time when correctly used, any implementation must be approached withcaution since, in general, incorrect answers are likely unless the model is split with afull understanding of the effects of computation delays for variables that cross blockboundaries. This tool has been provided for research into problem splitting rules andshould be regarded more as a state-of-the-art technique rather than for every daypractical implementation. For a novice, no more than one DERIVATIVE sectionshould ever be used.

When using more than one DERIVATIVE section, each DERIVATIVE section isclosed with its own END statement, and all the DERIVATIVE sections are enclosedwithin the DYNAMIC section. Each DERIVATIVE section can have its ownintegration algorithm, maximum step size, minimum step size, and NSTEPS value.Default values for these quantities are established in normal fashion. If a value is

4.30 DERIVATIVE 4. ACSL Statements


specified outside a DERIVATIVE section, this becomes the default for allDERIVATIVE sections. Values relating to a particular DERIVATIVE section aredefined by including the appropriate statement within the DERIVATIVE section;e.g.,

ALGORITHM IALG = 4NSTEPS NSTP = 1

DYNAMICDERIVATIVE sec1

ALGORITHM alg1 = 3MAXTERVAL max1 = 0.001...

END ! of sec1DERIVATIVE sec2

MAXTERVAL max2 = 0.010...

END ! of sec2END ! of dynamic

The first two statements establish algorithm number four (4) to be the defaultALGORITHM and one (1) to be the default of NSTP. Within DERIVATIVE section"sec1", the algorithm is specified to be three (3), with a maximum step size of 1 msec(0.001). Within DERIVATIVE section "sec2", the default algorithm (4) is taken andthe maximum step size set to 10 msec (0.010). Since NSTP is one, these are the actualstep sizes.

Arrays of systemvariables

These changes in block descriptor names are implemented by forming an arraydimensioned to the number of DERIVATIVE (and DISCRETE) sections for each oneof the describing quantities. The names used are the default or those specified outsidethe DERIVATIVE sections. In the preceding example, these names and theirdimensions would be IALG(2), NSTP(2), MAXT(2) and MINT(2). Names specifiedwithin the DERIVATIVE sections are equivalenced into appropriate slots of the mainarray;e.g.,

EQUIVALENCE(IALG(1), alg1)EQUIVALENCE(MAXT(1), max1)EQUIVALENCE(MAXT(2), max2)

and preset to the values specified. These values can be changed by SET commands atruntime. To change the integration algorithm for section two in the example, it must bereferred to as IALG(2) since a name was not explicitly given;i.e.,

SET alg1 = 5, ialg(2) = 5

Because of the equivalencing convention, it is important that unique names be used fordescriptors defined within DERIVATIVE blocks; do not use the same name indifferent DERIVATIVE sections.

Table 4-2. Translator event list

A B C D ... E F G

0.0 0.0 0.001 0.002 0.010 0.010 0.0111 2 1 1 1 2 1

0.0 0.001 0.010 0.010 0.010 0.011 0.0202 1 2 2 2 1 2

4. ACSL Statements 4.30 DERIVATIVE


Order ofexecution

At the start of the simulation run, the DERIVATIVE blocks are placed on an event listand executed in the order in which they are specified in the model definition section.

Each section is placed back on the event list assigned with the time to which that blockhas advanced. In the case given of a 1 msec step associated with Section 1 and 10msec step associated with Section 2, the event list is as in Table 4-2.

After Section 1 has been advanced one step to 1 msec, the event list has Section 2 atthe top (B) with a time of 0.0. Advancing this section one step leaves it at 10 msec andnow Section 1 is back at the head of the list again (C). Section 1 keeps on beingadvanced until both sections are at 10 msec (E). Now we assume that 1 is a little aheadof 2 and goes to 11 msec (F). Next step advanced 2 by 10 msec and the event listpicture changes to (G). This cycle then repeats.

Sections notsorted

Note that the sort algorithm cannot rearrange statements over a block boundary, so thatif a value calculated in the second block is used in the first block, at the first evaluationit is undefined. Such variables should be initialized in the INITIAL section.

Barriers at CINT,DISCRETE, or

SCHEDULE

The only break in the regular progression is at a communication interval or at anequivalent barrier represented by a DISCRETE section or a SCHEDULE event. Thetimes for all DISCRETE, SCHEDULE, and communication actions are entered ontothe event list where all actions are ordered in time; the next time on the event list iscalled the barrier time.

For all DERIVATIVE blocks, the current step size is checked against the current time(T) and the barrier time from the next event list. If integration with the current stepsize would exceed the barrier time, the actual step is reduced so that the last step ismade exactly up to the event. All states then line up in time for the event to take place.

NXEITG The setting of the ACSL system symbol NXEITG (no extra evaluation, default.FALSE.) controls whether an extra derivative evaluation is calculated atcommunication intervals and discrete events. The derivatives and intermediatealgebraic variables have values based on the last state vector, but this vector ischanged for the actual integration step. The default (with NXEITG set to FALSE) is tore-evaluate the derivatives prior to any event, including the communication interval.This action ensures that all derivatives and intermediate algebraic quantitiescorrespond to the actual state values.

A small amount of computer time can be saved by setting NXEITG to TRUE. This isreasonable if the differences in the results are small, which is usually the case. If anydiscrepancies are encountered, remember that the state variables are at the correct timeand any algebraic variables can be re-derived in the sampling code if necessary.

CINT as integermultiple of step

size

Most people choose integration step sizes and communication intervals that are integermultiples of each other. The ACSL system does not require this. For example, it isacceptable to choose a fixed step length for the continuous section of 4 msec, asampling INTERVAL in the DISCRETE block of 11 msec, and a communicationinterval of 20 msec. The first few integration step sizes would then be (in msec):

4, 4, 3, 4, 4, 1, 2, 4, 4, 3, 4, 3, 4, ...

The first short step of 3 msec brings time up to 11 msec, the first barrier time, which isdue to the DISCRETE section. Then two more normal steps are followed by a shortstep of 1 msec to bring time up to the communication time of 20 msec. The nextbarrier is the DISCRETE block at 22 msec causing a step size of 2 msec, and so on.Variable step algorithms look ahead to the next barrier to compute a constant step sizewhich reaches the barrier without requiring a final short step.

4.30 DERIVATIVE 4. ACSL Statements


4.31 DERIVT

FORM: y = DERIVT(ic, x)DERIVT(y = ic, x)

where:

ic = y(0)x = the input (an arithmetic expression)

The derivative function differentiatesx and can be implemented ifabsolutelynecessary. Note that it is never necessary to invoke a derivative; the derivative can beexpressed instead in terms of all the other states in the system. Since the derivativeoperator is a first order approximation, it can lead to instability if it is used to representany major loop. The only time this may be justified is for a minor term where a largeamount of extra calculation may be needed to reform the problem in terms of the states.

PID example As an example of how DERIVT can be avoided, consider the D term in a PID(proportional, integral, derivative) controller. There is a tendency to use DERIVT forthis term, but in hardware, it is always implemented by a differentiation over a firstorder lag;i.e.,

yx

= KsT1 s + 1

This formulation can be represented by a single line of ACSL code:

y = (k*x - INTEG(y, ic))/t1

Natureneverhas a free differentiator; it is always combined with a lag to make itrealizable.

Warning –Jacobian

The use of DERIVT invalidates the Jacobian calculation from the ANALYZEcommand, including all the derived data (zeros, root locus, and frequency responseplots). This is another good reason not to use DERIVT.

Warning –sorting

The DERIVT operator (as all memory operators) should be used only in sortedsections and should not be put in a PROCEDURAL block.

Warning –initial condition

Use a variable name rather than a literal constant for the initial condition so thatREINIT has a place to store it; otherwise REINIT tries to overwrite the global zerowith the one in the common block.

Example An example of a DERIVT statement could be:

ald = DERIVT(alic, al)

4.32 DIM

FORM: y = DIM(x 1, x 2)

The outputy is the positive difference betweenx1 andx2 wherex1 andx2 can beINTEGER, REAL, or DOUBLEPRECISION variables or expressions. DIM takes itstype and types its output based on the type of the arguments. The result can berepresented as follows:

y = x1 − x2 ; x1 > x2

y = 0.0 ; otherwise

4. ACSL Statements 4.31 DERIVT


People often write the following logic:

PROCEDURAL(x = y,z)x = y - zIF(x .LT. 0.0) x = 0.0

ENDa = SQRT(x)

when one line using DIM solves the problem elegantly:

a = SQRT(DIM(y, z))

DIM is useful for representing cable spring stiffness. Negative extension cancels zeroforce with a cable. You can't push on a piece of string!

4.33 DIMENSION

FORM: DIMENSION v1(a...), v 2(a...), ..., v n(a...)

The variable namesvi may have up to six integer constant subscripts separated bycommas;e.g., SPACE(5,5,5,5,5,5). The subscripts may be symbolic if the symbols aredeclared INTEGER and defined in a PARAMETER statement. This operator allocatesspace for up to six dimensions to be associated with a variable name. The statementcan appear anywhere in the program, but it must appear before any invocation of amacro that uses dimension information.

Type declaration Arrays can also be dimensioned using the REAL, DOUBLEPRECISION, orINTEGER statements. DIMENSION is preferred for floating point variables unlessthe type of precision needs to be forced. Using DIMENSION allows the type to adjustdepending on the global option (single or double precision) selected.

Warning –conflict with

system macronames

Names of certain ACSL macros should not be used as arrays. ACSL cannot check thatthe name defined as an array is also a macro because the TABLE statement defines anarray to hold data and a macro of the same name for table lookup. The names of thefollowing ACSL operators should not be used for arrays (as scalars is not a problem):

BCKLSH CMPXPL DBLINT DELAY DELAYP DERIVT DELSCDELVC EXPF GAUSI GAUSS HISTORY IMPL IMPLCIMPVC INTEG INTVC LEDLAG LIMINT LIMIT LINEARLINES MODINT OU OUTPUT PREPAR PTR RADCRADCI RDIG RDIGI REALPL RESET RSHM RSHMRSHMI RTDEVICE RTP SCALE SMOOTH TERMT TRANTRANZ UNIF UNIFI WDAC WDACF WDIG WDZGIWSHM WSHMI ZOH

Array order Elements of arrays are written and accessed by column, then row;i.e., (a(i,j) where i =row, j = column). For example, the elements ofb(2,5) can be shown:

11 12 13 14 1521 22 23 24 25

Extracted as a single-demensioned vector, the order is:

11 121 12 22 13 23 14 24 15 25

Examples Examples of DIMENSION specifications include:

INTEGER nPARAMETER(n=4)DIMENSION rm(3), em(3,3), hold(2,n), x(3,4,2,4,3,5)

4.33 DIMENSION 4. ACSL Statements


4.34 DISCRETE

FORM: DISCRETE [name]...END

The keyword DISCRETE introduces a section to be executed by either an INTERVALstatement or the SCHEDULE operator. The section is concluded by a matching ENDstatement.

DISCRETE sections are intended primarily for modeling digital sampled datacontrollers where the communication to and from the continuous world occurs at fixedtimes known in advance. Another common application is changing state or othervariables when a state event occurs (in which case execution of the DISCRETEsection is handled by a SCHEDULE statement).

Sorting The translator does not automatically sort the code; if you want to have code within aDISCRETE section sorted, use the SORT keyword. Code is never sorted acrosssections, nor are the sections themselves sorted.

Explicit structurelevel

DISCRETE sections are at the same level as any DERIVATIVE sections. If aDYNAMIC section is used, DISCRETE sections are placed inside it. (See Chapter 3for further information on explicit program structure.)

Synchronizingwith DYNAMIC

The DYNAMIC section acts like a DISCRETE section that does data logging everycommunication interval (CINT). When a DISCRETE section is close to an integralmultiple of CINT, it can be difficult to tell whether the DYNAMIC event will occurjust before or just after the DISCRETE event. A call to LOGD(.TRUE.) at the end ofthe DISCRETE section can help clarify the order.

Executed atdiscrete event

DISCRETE sections are executed at a discrete event or time point. The time of theexecution is controlled by the keyword INTERVAL or by a SCHEDULE statement.Like the DERIVATIVE section, each DISCRETE section has a time associated with itthat is entered into an event list. This time becomes a barrier for DERIVATIVEsections, ensuring that the integration routine takes a final step (which may be short)up to the barrier time before the code in the DISCRETE section is executed. Ifexecution is controlled by an INTERVAL statement, the section is re-entered on theevent list with a time of execution equal to the current time plus the current value ofthe INTERVAL variable.

Example The Discrete Sampled Compensator example in Appendix A uses a DISCRETE blockto model a control computer; the program structure is outlined here:

PROGRAM discrete controller...

DYNAMICDERIVATIVE contin

...(X depends on U)END ! of derivativeDISCRETE sample

INTERVAL dtsamp = 0.100...(U depends on X)

END ! of discreteEND ! of dynamicEND ! of program

In the continuous section, a plant is defined. The plant can be as complex as necessarybut structurally has an output X that depends on a control U. The control U should bevisualized as being generated via a digital-to-analog converter so that the value of the

4. ACSL Statements 4.34 DISCRETE


control remains constant between output intervals. The next section is a DISCRETEsection that is executed every DTSAMP seconds, defined by the INTERVALstatement to be 0.1 seconds. This section uses the output value of the plant X, at thesample time, to compute a control U which is used over the next sample interval. Thesuccessful operation of this simulation requires the continuous section to be exactly atthe sample time when the plant value X is used to determine the next control U.

Effect onintegration step

size

Jumps in the control U modify all the high order derivatives estimated for thecontinuous plant, so variable step algorithms (IALG = 1 or 2) may reduce the step sizeor even restart. Since the fixed step size algorithms and the Fehlberg algorithms retainno memory of previous history, with these algorithms the new step starts out with anew evaluation of the discontinuous derivatives. The key to the action is the fact thatthe effective time of the continuous section is exactly at the sample time when theDISCRETE section code is executed.

Initialization At time zero, the DERIVATIVE and DISCRETE blocks containing INTERVALstatements are evaluated in the order of appearance. In general, in a closed loopsituation, some variables have to be initialized in the INITIAL section since they areused before being calculated in a later block. For example, the control variable U inthe preceding code sequence is used in the continuous section before it is calculated inthe DISCRETE block. If used like this without initialization, the first value of U usedin the continuous section is the last value left behind by the previous run! A test of thepresence of these initialization problems is to make two identical runs (i.e., START ;START) and check the values at time zero. If any answers are different, it usuallyindicates an error in initialization.

Evaluation attime zero

The sequence of events for DISCRETE sections with INTERVAL statements at timezero differs somewhat from that of the DERIVATIVE section. For DERIVATIVEsections, the initial conditions are moved to the state variable array and the derivativecode executed once. In integrating over the first step, the integration algorithmre-evaluates the derivatives (the variable step algorithms IALG = 1 or 2 predict thestate variables first before the corrector iteration) so it appears that two derivativeevaluations are used at time zero. With the DISCRETE block, the first evaluation takesplace and then the block is placed back on the event list for execution at some time inthe future (depending on the INTERVAL statement). Now time advances for othersections up to the DISCRETE section barrier time. If the DISCRETE section containsany state variables, they are advanced to the current time by Euler integration. Thenthe DISCRETE section code is re-evaluated.

Integration inDISCRETE

Integration statements (INTEG or INTVC) are generally not used inside DISCRETEsections since this facility is designed to represent sampling actions independent fromthe continuous physical world. There is sometimes a need for a simplified integrationalgorithm with a fixed step size and a single derivative evaluation per step. In thiscase, the entire model can be placed in a DISCRETE block and no extra derivativeevaluations are inserted at the communication interval times. Since the states arealways advanced just before a re-evaluation of the derivative code, algebraic variablesare always synchronized to the state variables for data recording.

Access to statevalues

Before Version 11.5, values of state variables could not be changed in DISCRETEsections when IALG was 1 or 2 (the variable step, variable order algorithms). This wasthe case when the DISCRETE section was activated in response to an INTERVALstatement or a time event SCHEDULE statement. The only exception was when thesection was activated in response to astateevent SCHEDULE statement. The reasonwas that for IALG 1 and 2, the states were hidden. This restriction did not apply to theother algorithms. At Version 11.5, the procedure has been changed so that all statescan be re-computed or reset in DISCRETE sections.

4.34 DISCRETE 4. ACSL Statements


Arrays of systemvariables

When a program contains more than one DERIVATIVE and/or DISCRETE section,several system symbols (MAXTERVAL, MINTERVAL, ALGORITHM, NSTEPS,and ZZNIST) expand into arrays of length ZZNBLK (number of blocks). The blocksare associated with the elements of the arrays in the order they appear in the program.You can see these arrays in the debug output. The mechanism by which ACSLrecognizes a DISCRETE section is to set an effective algorithm of zero in thecorresponding IALG (ALGORITHM) slot. The INTERVAL variable is equivalencedinto the MINT (MINTERVAL) array and preset to the appropriate numeric value (-1 ifno INTERVAL). Slots in the corresponding MAXT (MAXTERVAL) and NSTP(NSTEPS) arrays are ignored.

Limit on numberof sections

The total number of sections, including all INITIAL, DYNAMIC, DERIVATIVE,DISCRETE, TERMINAL, and PROCEDURAL, is limited. The limit depends on thecomputer; it is 31 on 32-bit machines, and 63 on 64-bit machines. If the total isexceeded, the following error message is produced:

...Too many deriv/discrete sections

This limit is seldom reached, but when it is, usually a large number of DISCRETEsections has been defined. The number of sections can generally be reduced bycombining several DISCRETE sections into one, using the optional flag in theSCHEDULE statement to activate the appropriate code.

4.35 DO

FORM: DO n i = m1, m2[, m3]...n..CONTINUE

where:

n = a label (numeric or symbolic) of the terminal statement of the loop.

i = a simple integer variable called the index variable. With each repetition,its value is altered by the increment parameterm3. This variable maynot be changed within the loop.

m1 = initial parameter, the value ofi during the first loop.

m2 = terminal parameter. When the value ofi surpasses the value ofm2, DOexecution is terminated and control goes to the statement immediatelyfollowing the terminal statement.

m3 = increment parameter, the amounti is increased with each repetition.The default value ofm3 is 1.

Them1, m2, andm3may be integer constants, variables, or expressions of arbitrarycomplexity; if variables, they must be declared explicitly to be INTEGER variables.

A DO statement makes it possible to repeat a group of statements a designated numberof times using an integer variable whose value is progressively altered with eachrepetition. The initial value, final value, and rate of increase of this integer variable aredefined by the set of indexing parameters included in the DO statement. The range ofthe repetition extends from the DO statement to the terminal statement, which mustfollow the DO statement, and this whole sequence is called the DO loop.

4. ACSL Statements 4.35 DO


PROCEDURALin sorted sections

This is the standard Fortran DO statement. Note that in DERIVATIVE sections and inimplicit programs the loop must be embedded in a PROCEDURAL block so the sortroutine does not rearrange the order of execution. Using a PROCEDURAL is notnecessary within INITIAL, DYNAMIC, DISCRETE, or TERMINAL sections.

No branch intoloop

The loop cannot extend from INITIAL to TERMINAL to execute a sequence of runs;each loop must be closed within a single structural section because the runtimeCONTINUE statement branches directly into the DYNAMIC loop. Most Fortrancompilers reject a branch into a loop. If a loop around the DYNAMIC section isestablished to make successive runs, then CONTINUE cannot have any meaning sincethe initialization is not performed properly.

Error checking For more information on the structure of the DO statements, see your local Fortranreference manual. The ACSL translator checks the syntax of the DO statement butdoes not validate the correct nesting of loops or terminal statements. Errors ofstructure are indicated by the Fortran compiler.

4.36 DOUBLEPRECISION

See TYPE.

4.37 DYNAMIC

FORM: DYNAMIC...END

The DYNAMIC keyword identifies the beginning of a section of code that isperformed every CINTERVAL communication interval throughout the run. It must beaccompanied by a matching END statement.

The DYNAMIC section is the place to put output-related calculations so they can beperformed at the usually slower data recording rate rather than at each derivativeevaluation. Examples of calculations generally performed in this section are unitconversions (such as radians to degrees), which do not affect DERIVATIVEcalculations. Most calculations that affect code in the DERIVATIVE section should bein a separate DISCRETE section so model behavior is independent of the datarecording action; the DYNAMIC section is not intended for computing variables to beinput to DERIVATIVE or DISCRETE sections.

The time to the next communication interval can be calculated in the model, based onsome simulation phase or configuration, thus obtaining variable data recording rates(see CINTERVAL for an example).

Code in the DYNAMIC block is not sorted automatically; if you wish to have itsorted, use the SORT keyword.

4.37 DYNAMIC 4. ACSL Statements


4.38 END

FORM: END

An END statement denotes the end of a block (e.g., a PROCEDURAL block) orsection (DYNAMIC, DERIVATIVE, etc.). Chapter 3 shows the use of ENDs instructuring an explicit program.

One of the most common errors in programming a model is not getting the rightnumber of ENDs to balance the program sections. The following error messages areissued when the count is incorrect.

...Not enough ends

...Too many ends

The END statement acts like a right parenthesis in an arithmetic expression, exceptthat it terminates blocks of statements; an incorrect count corresponds to unbalancedparentheses.

4.39 EQUIVALENCE

FORM: EQUIVALENCE(main variable, equivalenced variable(s))&,(main variable, equivalenced variables(s)), ...

wheremain variableappears in the user's common block, and thereby reservesstorage, while theequivalenced variable(s)are assigned a position relative to the mainvariable, but do not reserve space. All variables appear in the dictionary with their owntypes and dimensionalities.

This operator is similar to the Fortran version in that it allows renaming of areas ofstorage. Due to the nature of storage in ACSL, there are specific rules for the use ofEQUIVALENCE which do not occur in normal Fortran usage.

Rules for use inACSL

Rules which restrict the use of EQUIVALENCE are as follows:

1) System variables (CINT, etc.), states, derivatives, and initial conditions mayappear only as main variables.

2) A main variable may never appear as an equivalenced variable.

3) An equivalenced variable must not appear more than once.

4) When being specified in an EQUIVALENCE statement, variables may have nomore than one subscript; if a subscript is specified, it must be an integer constant(e.g., 18) or PARAMETER name. Multi-subscripted arrays must appear usingtheir equivalent single subscript. For example, given A(5,5), equivalencing the(3,3) element to SAM would require a reference to A(5*2 + 3) or A(13);i.e.,EQUIVALENCE(A(13), SAM).

4. ACSL Statements 4.38 END


Multiply definedsymbol

In using equivalenced variables, any reference to an equivalenced variable name istaken to be a reference to its associated main variable, even though the equivalencedvariable may be only one element of a large main variable array. Thus the sorterproduces the error messageMultiply defined symbolif two equivalenced variables areassigned values outside a PROCEDURAL block in sorted sections, as shown in thefollowing example.

DIMENSION rm(3)EQUIVALENCE(rm(1), rm1), (rm(2), rm2), (rm(3), rm3)...rm1 = 0.0rm2 = 10000.0...Multiply defined symbol

Storage size Generally the main variable is equal to or larger than its equivalenced variable(s),since the main variable reserves storage;i.e.,

DIMENSION a(10)EQUIVALENCE(a, b)

Here A is the main variable and B is the equivalenced variable. Reference to B usesthe first element of A(i.e., A(1)). B(2) is not allowed unless B is a separately definedarray.

DIMENSION a(10)EQUIVALENCE(b, a)

Now B is the main variable (which reserves one word of memory), and A is theequivalenced variable. Because B occupies only one word, reference to A(2) accessesthe variable that follows B in the common block, a variable which is generally notknown and can change.

4.40 ERRTAG

FORM: ERRTAG name

wherenameis a simple unsubscripted variable. ERRTAG defines the system variablename that is used to indicate an attempt to reduce the step size below the minimum,MINT. This statement changes the name of the variable to a name of your choice. Thevalue of this name is set TRUE to indicate an attempt by a variable step sizeintegration algorithm to reduce the integration step size to satisfy the error bounds.

The type ofnameis automatically set to LOGICAL and the value is preset to FALSE.The variable step integration routine calls the derivative subroutine once with thename given under ERRTAG set to TRUE if it needs to reduce the step size below thespecified minimum MINT. If it is still TRUE on return, the termination flag for thatrun is set. Control should then revert to the TERMINAL section (if any) and theexecutive, and the next runtime command is read. If provision is made to handle thiscase and reset the flag, then care must be taken that a very small step size does notresult in excessive computer time being used.

4.40 ERRTAG 4. ACSL Statements


4.41 EXP

FORM: y = EXP(x)

The output y is the exponential of the floating point argument x, where x is limited insize such that the maximum machine word size should not be exceeded by theexponential. The expression is represented mathematically:

y = ex

The function and output take on the type (REAL or DOUBLEPRECISION) of theinput, thus adjusting to the global type specified by the translator option. The EXPoperator could be used as follows:

b1 = EXP(-tsamp/tlag)

4.42 EXPF

FORM: y = EXPF(ic, ta, lexpr)EXPF(y = ic, ta, lexpr)

where:

ic = y(0) ; 0.0< y(0) < 1.0

ta = time constant (τ)

lexpr = a logical variable or expression denoting rise or decay

The exponential function can be switched on or off. The output is a function rising ona time constant to 1.0 (lexpr= .TRUE. ) or decaying to zero (lexpr= .FALSE.) . Theoutputy is expressed as follows:

y = 1.0 − e(−(T − T0 ) ⁄ τ ) (lexpr= .TRUE. )

y = e(−(T − T1 ) ⁄ τ ) (lexpr= .FALSE. )

T0 andT1 are the times at whichlexprchanges FALSE to TRUE and TRUE to FALSErespectively.

An example using EXPF is:

f1 = EXPF(fic, ta1, T .GT. trise)

4.43 FCNSW

FORM: y = FCNSW(p, x1, x2, x3)

The outputy of the function switch operator is determined by the input functionp asfollows:

y = x1 p < 0.0y = x2 p = 0.0y = x3 p > 0.0

Note that zero almost never exists in the span of real numbers unless some other actionforces it there.

4. ACSL Statements 4.41 EXP


An example using the function switch operator is:

v = FCNSW(ain, vneg, vzer, vpos)

4.44 FORMAT

FORM: label: FORMAT(string)

The Fortran FORMAT statement may be used and must have a label. In an explicitprogram, the FORMAT statement and its corresponding I/O statement (READ,WRITE, etc.) must both be in a DERIVATIVE or DISCRETE section or neither;i.e.,if one of these statements appears in a particular DERIVATIVE or DISCRETEsection, its corresponding statement must appear in the same section.

The ACSL translator does not check the detailed syntax of the FORMAT statement.For further specification, consult your local Fortran manual.

4.45 GAUSI, UNIFI

FORM: GAUSI(k)UNIFI(k)

The output of these functions is the seed for the random number generator. Inputk isan integer constant or expression and should be a large, positive odd number for amaximal length sequence. The macro for GAUSI is listed in Figure 4-7.*

Only one of the initialization routines should be used since they both set the same seedvariable; either may be used with any other routine as they perform exactly the samefunction.

The random number generators are provided with a default seed initialization, so theseinitialization routines are required only when you wish to override the default. Thedefault seed number is 55555555.

MACRO gauss(y,ave,sig)MACRO REDEFINE grvREAL grvCALL zzgrv(grv=zzseed)y = ave + grv*(sig)MACROEND

MACRO gausi(seed)PROCEDURAL(=seed)zzseed=seedENDMACROEND

Figure 4-7. GAUSS and GAUSI operator macros

4.45 GAUSI, UNIFI 4. ACSL Statements


* For more information on how the random numbers are generated, see the article "Random Number Generators:Good ones are hard to find" by Stephen K. Park and Keith W. Miller,Communications of the ACM, Volume 31Number 10, October 1988.

The GAUSI or UNIFI operator should be invoked only in the INITIAL section of anexplicit program, or provision must be made to skip over it except at the beginning ofeach run in an implicit program. If the operator is executed repeatedly, the randomnumbers do not change.

The seed need not be specified for each invocation of the random number generatorssince subsets of random sequences are also uncorrelated random sequences.

4.46 GAUSS

FORM: y = GAUSS(m, s)GAUSS(y = m, s)

wherem is the mean ands is the standard deviation. The outputy is a normallydistributed random variable. Figure 4-7 gives a listing of the operator macro.

Seed The seed for a random sequence can be reset by UNIFI or GAUSI. If not set, adifferent random sequence is in effect for each run.

Warning –do not use inDERIVATIVE

GAUSS is not intended for use in a DERIVATIVE section because the power density(or, what is usually more important, the low frequency power) depends on theintegration step size. Instead, use the OU operator.

The GAUSS operator could be used as follows:

vmic = GAUSS(0.0, vmsg)

4.47 GO TO

FORM: GO TO labelGO TO (n1, n 2, ..., n m), i

whereni are statement labels that correspond to a possible label andi is a simpleinteger variable that has been given a value between 1 andm.

GO TO statements transfer control to labeled statements whose references are fixed orwhich are assigned during execution of the program.

Transfersbetween sections

The statement labels used in the GO TO statements must be associated with executablestatements in the same program unit as the GO TO statement. In explicit programs, theINITIAL, DYNAMIC, and TERMINAL sections exist in a single program unit.However, control cannot be transferred into the DYNAMIC region. The reason for thisis that the integration routines must be initialized at the start of the run; thisinitialization operation is done on leaving the INITIAL section and entering theDYNAMIC section. Control can be transferredfrom the DYNAMIC region to theINITIAL or TERMINAL section and between INITIAL and TERMINAL sections.

DERIVATIVEDISCRETE

The DERIVATIVE section is a separate program block and control cannot betransferred into or out of it. Control also cannot be transferred between DISCRETEand DYNAMIC, INITIAL, or TERMINAL sections because DISCRETE sections arein the same subroutine as the DERIVATIVE section.

Statement labels A statement label may be either numeric or symbolic. Execution resumes at thestatement with the referenced label. We recommend using a CONTINUE as thelabeled statement to avoid possible problems with sorting.

4. ACSL Statements 4.46 GAUSS


Examples Examples of valid GO TO statements include:

GO TO loopGO TO (100, 200, 300, 400, 500), ibin

A large number of GO TOs is considered harmful to the successful completion of anysimulation project.

4.48 HARM

FORM: y = HARM(tz, w, p)

The outputy is a sinusoidal or harmonic drive function with the results:

y = 0.0 T < tzy = sin (w ∗ (T − tz ) + p ) T ≥ tz

where:

tz = delay (sec)w = frequency (rad/sec)p = phase shift (rad)

Note that ifp is nonzero, a discontinuity is involved.

An example using HARM is as follows:

drive = HARM(tdrive, w1, phased)

4.49 HISTORY

FORM: HISTORY(y, yic, n)

where:

y = a variable name that will be used to create an array.

yic = a scalar variable or expression of arbitrary complexity that is stored in thefirst slot (y(1)) in the output array while the other elements in the arrayare pushed down. Extracting past history is then just a reference to y(2)for two time steps ago, y(3) for three time steps ago, etc.

n = must be an integer constant or integer parameter name (not a variablename) that gives the number of history elements to keep track of.

Since the output is a vector, this statement cannot be invoked as an assignmentstatement; in general, only scalar values can be passed across the equal sign. Themacro of the HISTORY operator is listed in Figure 4-8.

Example As an example, the following statement records four samples of a sine wave into ahistory array:

HISTORY(sinhist, sin(2*w*t + fi), 4)

and then we can form a filter by extracting the history elements as equivalent delayline taps:

filt = b0*sinhist(1) + b1*sinhist(2) + b4*sinhist(4)

4.49 HISTORY 4. ACSL Statements


Placement HISTORY can appear only in DISCRETE sections since it makes use of the DELVCoperator to delay the history elements. In unsorted DISCRETE sections, HISTORYshould be placed after the calculation of all its input variables. The elements of thearray are initialized to zero the first time.

4.50 IF,IF-THEN-ELSE

FORM: IF(lexpr) statement

IF(lexpr) THENblock1

ELSE IF(lexpr1) THENblock2

ELSEblock3

END IF

IF statements are used to transfer control or perform calculations conditionally. At thetime of execution, an expression in the IF statement is evaluated and the resultdetermines whether the rest of the statement is executed.

The logical expressionlexpr is a logical or relational expression, one that produces asingle value (either TRUE or FALSE).

Logical IF In the logical IF form,statementis any executable Fortran statement except another IF(either logical or block), a DO statement, or an END. Non-Fortran statements or thoseparticular to ACSL may expand to more than one actual Fortran statement, which isnot allowed. Only a single statement can be included in the logical IF statement.

Examples of logical IF statements include:

IF(a .LT. 5.0 ) a = a + 0.1PROCEDURAL(x = )

IF(x .GT. xmax) GO TO finishx = k*xprevxprev = x

finish: CONTINUEEND

macro history(x, xin, n)macro redefine j, xn, xzmacro relabel loopdimension x(n), xn(n), xz(n)constant xz = n*0.0procedural(xn = xin)xn(1) = xindo loop j = 2, nxn(j) = x(j - 1)loop:continueendx = delvc(xn, xz)macro end

Figure 4-8 HISTORY macro

4. ACSL Statements 4.50 IF, IF-THEN-ELSE


Logical IF statements that transfer control in sections that are sorted by ACSL(DERIVATIVE sections or implicit programs) must be enclosed in PROCEDURALblocks, as in the second example, in order to maintain statement order. This examplehowever would be better handled with a block IF construct.

Block IF Block IF statements conditionally execute blocks (groups) of statements, a sequence ofzero or more complete Fortran statements including other IF-THEN-ELSE blocks.Such a sequence is called a statement block.

Examples of block IF constructs are:

IF(ABS(force) .GT. breakout) THENvdot = netforce/mass

ELSEvdot = 0.0

END IF

IF(a .GT. b) THENd = bf = a - b

ELSE IF(a .GT. b/2) THENd = b/2f = a - b/2

END IF

Initializingvariables

Note that the same output variables should always be defined in all branches of thelogic. If they are not, the last value placed in the variable is left around and used insubsequent integration steps. For example, in the following code, either VDOT orYDOT is not initialized:

IF(a .GE. b) THENvdot = f(a)

ELSEydot = f(b)

END IF

Assuming A starts off less than B, then VDOT is not given a value but YDOT is.When A becomes greater than or equal to B, then VDOT is given a value but YDOTcontinues to hold its last value. This is not necessarily wrong, just an issue to considerwhen coding logic.

Statements onsame line

The IF-THEN statement takes no additional statements on the same line unless theseparator (a semi-colon) is used, turning it into a separate statement;e.g.,

IF(lexpr) THE N ; I = 1 ; ENDIF

Memoryoperators

Memory operators such as INTEG, REALPL, TRAN, etc. should not be used insidestatement blocks. It's possible to step over an integration statement with logic, but thatdoesn't stop the integration from taking place; it just means that the derivative is notbeing calculated. This results in thelastcalculated value being used. If you don't wanta state to be integrated, make the derivative zero.

PROCEDURAL PROCEDURAL blocks are used to hide logical code from the translation sortingprocess, but IF blocks are moved as one and don't require the PROCEDURAL. Thesorting algorithm looks at all the outputs of the block (those variables on the left sideof an equal sign) and all the inputs (those variables on the right side of an equal sign)and positions the block according to the normal sorting rules. Thus the block is placedafter the calculation of all the input variables and before the use of any of the outputvariables.

4.50 IF, IF-THEN-ELSE 4. ACSL Statements


4.51 IMPLC

FORM: z = IMPLC(r, zic)

where:

z = a simple algebraic variable (IMPVC handles vectors)

r = residual, an arithmetic expression of arbitrary conplexity (i.e., maycontain functions, macros, or other integration statements)

zic = a simple unsubscripted variable, a floating point constant, or a generalexpression enclosed in parentheses. If it is a simple variable (preferred),then this variable name must not be used as another initial condition,state, derivative, or system variable name.

Implicitintegration

In implicit integration, algebraic constraints are defined by an expression thatevaluates to a residual; this residual is then kept at or close to zero.

One use of this feature is in solving for pressure or voltages at junctions, where thejunction has flows or currents that sum to zero (Kirchoff's Law). Specifying theunknown quantity (pressure or voltage) as dependent on the residual of the sum of theflows allows it to be adjusted until the sum is really zero.

Examples The example Tank with Boiling Benzene in Appendix A illustrates a PI controller withthe implicit operators. The aircraft example ACRFTS also uses IMPLC.

Must be inDERIVATIVE

The implicit operators must be in DERIVATIVE sections, and they cannot be skippedover in logical structures such as PROCEDURAL or IF-THEN-ELSE blocks.

Residual The residual expression must be related to the algebraic variable by a path such thatthe partial derivative of all the residuals, taken as a vector with respect to all thealgebraic variables again taken as a vector, is a non-singular matrix.

The state and algebraic variables can be seen more clearly in the following:

Y.

= F(Y, Z )0 = G(Y, Z )

Here theY's are the state variables and theZ's are the algebraic variables. This is nowexpressed for scalars as:

y = INTEG(F(Y, Z), yic)z = IMPLC(G(Y, Z), zic)

or, for vectors:

y = INTVC(f, yic)z = IMPVC(g, zic)

where nowF andG are vectors that have been filled with derivatives and residualsrespectively in a separate operation. Of course scalar and vector variables can be usedand mixed freely. The ACSL translator builds a complete vector of states and acomplete vector of residuals for all the component parts.

Since we must be able to solve the residual relationships forZ, this means that thepartial ofG with respect toZ must be non-singular;i.e.,

∂G (Y, Z)∂Z

≠ 0

4. ACSL Statements 4.51 IMPLC


Derivative It sometimes is not possible to extract the derivative explicitly from the left-hand sideof an equation, so that the model equations are expressed as:

F(Y, Y., T) = 0

To handle this, case we have overloaded the IMPLC and IMPVC syntax by defining asecond variable on the left. For scalars, the above equation would be written:

y, yd = IMPLC(F(y,yd,t), yic)

In actual implementation, this is transformed into an integration statement and analgebraic constraint as follows:

y = INTEG(yd, yic)yd = IMPLC(F(y,yd,t), 0.0)

DAEImplementation

The ACSL translator builds up vectors for states, derivatives, and initial conditionsusing the INTEG and INTVC operators. At this level, we have added to these vectorsthe algebraic variables (to the state vector), residuals (to the derivative vector), andinitial guesses for the algebraic variables (to the initial condition vector). These nowlook like Figure 4-9.

Y.

R

= F(Y, Z)G(Y, Z)

or, linearizing:

Y.

R

= FYGY

FZGZ

YZ

Since R is nominally zero, the second line leads to:

GY Y = −GZ Z

and:

Y.

= ( FY − FZ GZ−1 GY ) Y

This matrix is the one used in the Gear stiff algorithm since every time the derivativesare evaluated theZ variables are simultaneously adjusted to force the residuals to zero.

states derivatives ICs

s1 d1 ic1s2 d2 ic2s3 d3 ic3... ... ...a1 r1 ig1a2 r2 ig2a3 r3 ig3

Figure 4-9. Layout of state vectors

4.51 IMPLC 4. ACSL Statements


The nonlinear equation solver to find theZ variables is similar to the one used by theruntime ANALYZE command. It essentially computes a Newton-Raphson step:

δNR = GZ−1 R

and a steepest descent step:

δSD = GZT R

Then it takes a linear combination of these two calculations depending on howsuccessful the iteration is or has been. Since changes are usually small from oneiteration step to the next, this iteration usually converges in one or two evaluationsusing the Newton-Raphson step. The usual problem is finding the algebraic (Z)variable at the very beginning when the initial guesses may be far from the truesolution.

Example An example using the implicit scalar operator is:

residtl = htotal - hl(t1) - hv(t1)tl = IMPLC(residtl, tlic)

4.52 IMPVC

FORM: z = IMPVC(r, zic)

whereZ, R, andZIC are arrays of the same size and correspond to algebraic variable,residual, and initial condition, respectively. The mechanization of this operator isexplained under IMPLC above.

Restrictions apply to the IMPVC operator that are similar to those for vectorintegration, INTVC;i.e.:

1) IMPVC cannot be used in an expression.

2) The residual array cannot appear any where else as a state, algebraic variable, orinitial condition.

3) The initial condition must be a variable name, it cannot be a literal constant or anexpression.

4) The array size may be one, or, equivalently, a simple undimensioned variable canbe used instead. In this case, the residual name is equivalenced directly into thearray of residuals and no extra assignment statement is generated.

An example using the vector implicit operator is:

PROCEDURAL(rv = a,b)rv(1 ) = a + brv(2 ) = c - b

ENDx = IMPVC(rv, xz)

4. ACSL Statements 4.52 IMPVC


4.53 INCLUDE

FORM: INCLUDE 'filename'

where'filename'is in single quotes and conforms to the local operating system syntax.For example, on a Unix system, statement could be in the form:

INCLUDE '../mod1.inc'

and under VAX/VMS as follows:

INCLUDE '[-]mod1.inc'

Environmentvariables

The syntax of the file name supports references to operating system environmentvariables through the use of a prepended dollar sign ($). For example, if HOME is anenvironment variable defined in the Unix or Windows operating system, then theINCLUDE statement will find a file (xyz.inc) in the user's home directory:

INCLUDE '$HOME/syz.inc'

Paths The environment variable is explanded into the full path for the file, includingadjustment for differences in forward or backward slashes for the machine operationsystem. If on a PC, forward slashes (/) are changed to back slashes (\), and if on a Unixsystem, the opposite applies, so a common source file can be used for running on bothPC and Unix systems.

Procedure The INCLUDE statement directs the ACSL translator to suspend reading statementsfrom the current file and read the statements from the INCLUDE file.

The INCLUDE file must comprise complete ACSL statements and must result in avalid program when combined with the surrounding code.

INITIAL,DYNAMIC,TERMINAL

INCLUDE files can contain separate INITIAL, DYNAMIC, and/or TERMINALsections with their matching END statements. These blocks areaddedto the currentsections being built as the ACSL translator works its way through the model definitionfile.

Example An example of using INCLUDE files is to break a simulation into modules which arethen brought into a skeleton;e.g.,

DERIVATIVEINCLUDE 'seeker.inc'INCLUDE 'autopilot.inc'INCLUDE 'actuator.inc'INCLUDE 'airframe.inc'

END ! of derivative

Nesting INCLUDE files can themselves contain other INCLUDE statements.

4.54 INITIAL

FORM: INITIAL...END

The INITIAL keyword identifies the beginning of a section of code that is performedjust once at the start of each run. The INITIAL statement must have a matching ENDstatement. Refer to Chapter 3 for rules of explicitly structured programs.

4.54 INITIAL 4. ACSL Statements


Sorting Code within the INITIAL section is not automatically sorted; if you wish to have anINITIAL section sorted, use the SORT keyword.

Multiple INITIALsections

Any number of INITIAL sections may be used within a program, at any nesting level.This feature is particularly useful in conjunction with INCLUDE files and/or ACSLmacros;i.e., modules can be developed in separate files with their own INITIALsections, then brought into a DERIVATIVE section in a larger model by means ofINCLUDE statements.

The translator collects all the INITIAL sections in the order encountered and addsthem to the end of the INITIAL section to be executed. If the sections of code to beadded need to be in a particular order (so that a variable is defined before being used,for example), the SORT keyword can be used.

Warning – not inPROCEDURAL

MACROs with INITIAL sections cannot be called from within PROCEDURALsections. This is because at the moment the INITIAL keyword must be at aPROCEDURAL nesting level of zero.

4.55 INQUIRE

FORM: INQUIRE(UNIT = lu, FILE = fin, IOSTAT = ios, ERR = s, EXIST = ex, OPENED = od, NUMBER = num, NAMED = nmd, NAME = fn, ACCESS = acc, SEQUENTIAL = seq, DIRECT = dir, FORM = fm, FORMATTED = fmt, UNFORMATTED = unf, RECL = rcl, NEXTREC = nr, BLANK = blnk)

where the arguments follow the Fortran 77 standard. See your local Fortran manual.The only argument required is either (not both) the UNIT or FILE definition.

4.56 INT

FORM: n = INT(x)

The outputn is the integerization of the argumentx. The argumentx can be eithersingle or double precision. The implementation is thatn is the sign ofx times thelargest integer≤ | x |. INT could be used as in the following example:

INTEGER ibin, ibin1ibin = ibin1 + INT(xz + x*y)

INT or AINT can be used on the right side of an equal sign; for example,

y = INT(x)

4. ACSL Statements 4.55 INQUIRE


In this case, the value of X is integerized, but then the result is floated according tonormal conversion rules. The type of the arguments to subroutines however cannot beinferred, so INT or AINT must be chosen to match the argument type. In thefollowing, for example, the first argument is forced to be INTEGER and the second,REAL.

CALL mysubr(INT(x1), AINT(x2), ...)

Since the type of AINT follows the argument (i.e., becomes either single or doubleprecision depending on the type of the argument), it is probably better to force the typeusing DBLE or REAL.

CALL mysubr2(DBLE(AINT(x3)), REAL(AINT(x4)), ...)

Now the arguments won't change type with a change in the ACSL translator mode.

4.57 INTEG

FORM: state = INTEG(deriv, ic)

where:

state = a simple variable. (INTVC handles integration of vectors.)

deriv = an arithmetic expression of arbitrary complexity;i.e., may containfurther INTEG statements, functions, or macros.

ic = a simple non-subscripted variable, a real constant, or a generalexpression enclosed in parentheses. If it is a simple variable (preferred),then this variable name must not be used as another initial condition,state, derivative, or system variable name. If an expression is used, boththe initial condition and the state are given dummy variable names; aconsequence of this is that XERROR and MERROR do not recognizethe state name.

INTEG may also be embedded in any legal expression as a function that has a singleoutput, the value of the state. When the integration statement is alone, then the statename can be identified; embedding it in an expression means that an ACSL-generatedvariable (i.e., in the form Znnnnn) must be used for the state name.

Initial conditionsas expressions

If an expression is specified for an initial condition, the expression is sorted in such away that all components in the expression are evaluated before the state value isassigned in the first (initialization) evaluation of the derivatives. Equations using thestate then follow. Problems may occur when using this form with the REINITcommand at runtime. The expression is always evaluated and substituted for an initialcondition established by the reinitialization operation.

Implementation All integration in an ACSL program is handled by a centralized integration routine. Inperforming integrations, the integration algorithms utilize two intervals: (1) theintegration step size and (2) the communication interval. Since digital integration isbasically a discrete process, the integration step is the fundamental interval over whichthe state variables are updated. No finer detail is accessible except by someinterpolation method. All integration schemes for the set of first order differentialequations in the form:

x.

= f(x)

are transformed into:

4.57 INTEG 4. ACSL Statements


xn+1 = xn + h∗f(xn+α )

where(0.0≤ α ≤ 1.0) andh is the integration step size. The problem is to find theeffective derivative to use in updating the state vector. Note that with suitableconditions on continuity and differentiability, the mean value theorem guarantees thatanα exists that produces an exact answer for the state trajectory; finding it is anothermatter, however. Different integration schemes approximate the derivative in differentways, usually by expanding the derivative function in a Taylor series about the currentstate. For an example of how this is implemented, see the explanation of theRunge-Kutta fixed-step fourth order algorithm in the section on ALGORITHM.

Examples Examples of use of the INTEG statement include:

y = INTEG(5.0*x(1) + c, yic)z = p*INTEG(zdot, 0.0) + btw = INTEG(wdot, (2.0*al*SIN(th)))

Z in the above is not a state since the INTEG function appears embedded in anexpression.

Integratingvectors

The INTVC operator should be used for integrating vectors or multidimensional arrays.

Initial conditionnames

Names of initial conditions can be only names not used as states, other initialconditions, or system variables. The following statements are all illegal when usedwith above example statements, except that CINT can be used if the system defaultname for the communication interval has been changed with a CINTERVALstatement:

yy = INTEG(yyd, yic) ! yic is IC for y defined abovezz = INTEG(z*4.0, w) ! w is a state defined abovezk = INTEG(kk, CINT) ! CINT is a system variable

Translationprocess

The reason for the rules may be better understood if the actual translation operation isexplained. The translator is building up three lists of names that are placed in sequencein three Fortran common blocks. The state list contains all the state variables andarrays, the derivative list contains the corresponding derivatives, and the initialcondition list contains the corresponding initial conditions. Each name in these listsmust be unique.

The initial condition name for each state must be unique. If the initial condition is aliteral constant or an expression, a generated name (in the form Znnnnn) is used. If theinitial condition name is a simple variable, the translator uses that name directly. Theexpression form is changed into a test (IF statement) on the first evaluation of a run, inwhich case the expression is evaluated and the result stored into the state.

The derivative names are all generated variables to avoid possible conflict. Thestatements

yd = INTEG(5.0*x, 1.0)y = INTEG(yd, yic)

generate the following assignment statements:

Z99999 = 5.0*XZ99998 = YD

and a DATA statement for the generated initial condition:

DATA Z99997/1.0/

4. ACSL Statements 4.57 INTEG


Now the state list isYDandY; the derivative list is Z99999 and Z99998; and the initialcondition list is Z99997 andYIC. Each name on the list is unique.

Use in sortedsections only

The INTEG operator should be used only in sorted sections or implicit programs andshould not be used in a PROCEDURAL.

4.58 INTEGER

See TYPE.

4.59 INTERVAL

FORM: INTERVAL name = floating point number

wherenameis a simple unsubscripted variable name. The INTERVAL statementschedules repeated execution of a DISCRETE section and can be used only in aDISCRETE section. It is used to define both the name of the variable controlling therepetition period and its initial value.

No defaults There is no default for the INTERVAL name or value. A DISCRETE section withoutan INTERVAL statement is not executed automatically. An alternative means ofactivating a DISCRETE section is with a SCHEDULE statement.

An example of an INTERVAL statement could be:

DISCRETE dacINTERVAL dt = 0.1...

END

In MINT array The mechanization of the INTERVAL feature is to use the slot in the globalMINTERVAL array corresponding to the DISCRETE section. The INTERVALvariable is equivalenced into this array. If no INTERVAL statement is placed withinthe DISCRETE block, a value of -1.0 is used as the default. This flags the DISCRETEsection as not to be executed during the initialization phase.

Changing value The INTERVAL value may be changed (anywhere in the program, or at runtime). It isthe value which is current when the DISCRETE section has completed executionwhich determines the next execution time. Once the DISCRETE section is on theevent list, changes in the INTERVAL value do not affect the next execution time.

Strobe effect When the INTERVAL for activating a DISCRETE section is a decimal fraction, it ispossible for small errors in timing to resulting in a beating or strobe effect. Theproblem is that decimal fractions (0.1, for example) are never exact on a binarymachine. In order to maintain accuracy, ACSL finds an integer multiplier ofCINTERVAL such that the result is an integer (to machine accuracy). If CINT is 0.1,for example, the multiplier is 10. The communication interval times are obtained byaccumulating integer ones and finding the end point by dividing by ten. A thousand0.1s by this method is 100 exactly, while a thousand additions of 0.1 (not a power oftwo and so a rounded number) has significant error. Since CINT is adjusted andINTERVAL statements are not, a difference can develop. If this is an importantconsideration, double precision can help, or else the INTERVAL value can be biassedby setting it to, for example, 0.1000001 or 0.099999999 instead of 0.01.

4.59 INTERVAL 4. ACSL Statements


4.60 INTVC

FORM: x = INTVC(xd, xic)

wherex, xd, andxic are arrays of the same size and correspond to state, derivative, andinitial condition, respectively. The missile example in Appendix A uses INTVC.

Restrictions The restrictions on the INTEG operator with regard to arrays can be avoided by usingthis vector integrator operator. The restrictions on the INTVC operator are as follows:

1) INTVC cannot be used in an expression.

2) The derivative array must not appear anywhere else as a state. If a state must beused as a derivative (velocity, for instance, which has been integrated fromacceleration and is then the derivative of range), use the block transfer(XFERBR) subroutine to move it into another array before using INTVC.

3) The initial condition must be a variable name; it cannot be either a constant or anexpression.

4) The array size may be one; or, equivalently, a single undimensioned variable canbe used instead. In this case, the derivative name is used explicitly and no extraassignment statement is generated. INTVC is the preferred method forintegrating scalars as long as the derivative is a scalar as well.

5) The derivative array cannot be preset with a CONSTANT statement since it iscleared automatically to a small number before the derivative evaluation routineis called the first time (at the end of the INITIAL section) after every START.

Examples Following are examples using INTVC:

DIMENSION x(10),xd(10),xic(10),m(5, 5),md(5, 5),mic(5, 5)y = INTVC(yd, yic) ! scalar integrationx = INTVC(xd, xic) ! vector integrationm = INTVC(md, mic) ! matrix integration

Warning – can'tbe both state and

derivative

A variable cannot be both a derivative in one INTVC statement and a state in another.For example, if R, V, and A are range, velocity, and acceleration vectors:

DIMENSION r(3), ric(3), v(3), vic(3), a(3)

the following is illegal:

v = INTVC(a, vic)r = INTVC(v, ric)

since these statements ask for V to be considered as both a state and a derivative at thesame time. Using the XFERBR (transfer block) subroutine and defining an RD (R dot)array, the sequence becomes:

DIMENSION r(3), rd(3), ric(3), v(3), vic(3), a(3)v = INTVC(a, vic)CALL XFERBR(rd = v, 3)r = INTVC(rd, ric)


INTVC should be used only in sorted sections or implicit programs, and it should notbe used in a PROCEDURAL.

4. ACSL Statements 4.60 INTVC


4.61 I/O

FORM: READ(clist) ilistWRITE(clist) olistREAD f, ilistPRINT f, olist

These statements transfer data between external files and internal variables followingthe Fortran 77 conventions. The elements in the control listclist are taken from thefollowing:

[UNI T = ] ln integer logical unit[FMT = ] f format statementREC = rn record numberIOSTAT = ios I/O statusERR = s statement label on errorEND = s statement label on end-of-file

The input listilist comprises variable names or arrays or implied DO loops of the form:

(a(j), j=jmn, jmx)

The output listolist can have constants such as character strings and arbitraryexpressions as well as the same type of variable names as implied DO loops as theinput list; for example,

WRITE(97, *) 'Value of V is ', D

The asterisk (*) specifies free format. This is the simplest format for transferring dataitems if just visibility is required.

ACSL accepts the ANSI Fortran 77 standard format. For complete details of theinput/output forms, see your local Fortran reference manual.

I/O statements are not usually placed in DERIVATIVE sections except for debugging.This is because of the frequency and unpredictability of execution of theDERIVATIVE section.

There should be little need to program complicated input/output statements in ACSLsince most of the numeric output and plots are generated automatically. Typicalrequirements for data transfer between external files is for reading experimental dataor writing values for a specialized plot program.

4.62 LEDLAG

FORM: y = LEDLAG(p, q, x[, ic])LEDLAG(y = p, q, x[, ic])

The lead-lag compensator outputy is related to inputx through the transfer function:

yx

=ps + 1

qs + 1

such that:

y(0) = pq

x(0) + ic

Figure 4-10 shows the mechanization of this operator as a system macro.

4.62 LEDLAG 4. ACSL Statements


Restriction oninitial condition

The initial condition,ic, has the same restrictions as the initial condition of the INTEGoperator;i.e., if it is a variable name, the name must not be used as another initialcondition, state, derivative, or system variable name. If the initial conditionic is notspecified, it is given a default of zero.

Time constants The time constantsp andq may be expressions of arbitrary complexity. The lag valueq may not be zero or else a division by zero results.

Settingp to zero makes LEDLAG behave like a pure lag (see REALPL). Settingpequal toq makes LEDLAG behave like an assignment statement:

y = x


This operator (as all memory operators) should be used only in sorted sections orimplicit programs. It should not be used in a PROCEDURAL.

An example using LEDLAG is:

xp = k1*LEDLAG(ta1, ta2, e)

4.63 LIMINT

FORM: y = LIMINT(yd, ic, bb, tb)LIMINT(y = yd, ic, bb, tb)

where:

yd = derivative (variable name or expression)

ic = initial condition ofy, with the same restriction as on the INTEG initialcondition (i.e., if it is a variable name, the name must not be used asanother initial condition, state, derivative, or system variable name);may be omitted if zero (but comma must be included)

bb = bottom bound ony

tb = top bound ony

Figure 4-11 shows the effect of the LIMINT operator. The LIMINT operator could beused as follows:

dl = LIMINT(dld, dlic, -dlmx, dlmx)

MACRO ledlag(out,p,q,in,ic)MACRO STANDVAL ic=0.0MACRO REDEFINE x,yx = inout = y+(p)*x/(q)y = INTEG((x-out)/(q),ic)MACROEND

Figure 4-10. LEDLAG operator macro

4. ACSL Statements 4.63 LIMINT


Use with BOUND Integrators should not be limited using the BOUND function since the integratorcontinues to integrate and then must integrate out of the limit when the derivativechanges sign. The LIMINT operator holds the integrator at the limit as long as thederivative is of such a sign to drive it further into limit. When the derivative reversessign, the integrator immediately comes off the limit. However, LIMINT and BOUNDcan be used together to force a hard limit:

y = BOUND(0.0, 1.0, LIMINT(2.0*t, 0.0, 0.0, 1.0))

SCHEDULEalternative

The LIMINT operator can penetrate the limit, especially if the approach is at highvelocity (i.e., large values for the derivative and step size). If it is necessary to find thelimit points with more precision, use the SCHEDULE operator to force iteration untilthe limit penetration point is found, then execute a DISCRETE section to set thederivative to zero. Use another SCHEDULE statement to find the point at which theintegrator comes back out of the limit and execute another DISCRETE section tobegin using the calculated derivative again.

SCHEDULE withLIMINT

The integration routine can be forced to step up to the limit by using SCHEDULE. Inthis case, the LIMINT operator is used and no DISCRETE section is executed. In thefollowing example, SCHEDULE forces an iteration to the point whenX just crossesthe symmetric boundary±XMX.

x = LIMINT(xd, xic, -xmx, xmx)SCHEDULE .XP. ABS(x)-xmx

Varying the limits The limits should not vary in time while the system is in the limit.

Use in sortedsections

This operator (as all memory operators) should be used only in sorted sections orimplicit programs, and it should not be used in a PROCEDURAL.

Figure 4-11. Effect of LIMINT Operator

4.63 LIMINT 4. ACSL Statements


4.64 LINEAR

FORM: linear(y = 'datablock:argument')y = linear('datablock:argument')

The argument inside the single quotes identifies the data block by name (in front of thecolon) and identifies which column of the data block to interpolate. This data block isdefined in a DATA statement at runtime, generally in a command file (see DATA inChapter 5). For this discussion, assume that there is defined a DATA block in thecommand file as follows:

data foo(t, x, y)0.0 2.0 2.01.0 3.0 2.02.0 1.0 2.53.0 3.0 3.54.0 9.0 1.55.0 8.0 4.56.0 2.0 5.07.0 2.0 5.08.0 2.0 6.39.0 2.0 8.1end

The time column must be present and be of strictly monotonic increasing order for theinterpolation to work; i.e., each time point must be greater than (not equal to) thepreceding time point.

This operator linearly interpolates between data points down a column of the givenargument. As an example, extract X as follows:

LINEAR(x = 'foo:x')

or

x = LINEAR('foo:x')

This looks up the value of the independent variable (in this case it has to be T, sincethis is a column of the data block FOO), finds the data points that bracket this time,and then linearly interpolates to find the function value that is placed in the outputvariable X.

Default datablock name

In all these cases, the name of the data block can be omitted from the quoted string(part in front of the colon). In this case, the default data block is the one identified onthe start command; for example:

START/DATA=foo

If no default data block is specified, then the simulation run aborts since the operatordoes not know where to get the data.

4.65 LINES

FORM: CALL LINES(n, "TOF")

wheren is the number of lines about to be printed. Ifn lines are not available on thecurrent page, the page is ejected.

4. ACSL Statements 4.64 LINEAR


The LINES command tells the executive processor how many lines are to be writtenwith PRINT or WRITE statements. At runtime, the executive processor keeps track ofthe number of lines written on the output file and every 55 lines issues a top-of-formand prints out the header and TITLE. If Fortran WRITE statements are included in themodel definition, they are expected to inform the processor how many lines they aregoing to write so that the pagination is performed correctly.

CALL LINES(2, "TOF")PRINT 99, a, b, c99: FORMAT(1X, 2E12.5/1X, F12.2)

In order to force a top-of-form prior to the write command, call subroutine PAGEbefore calling LINES. Placing a digit 1 in column one for top-of-form should not beused in ACSL.

4.66 LOG

FORM: y = LOG(x)

The outputy is the natural logarithm ofx wherex is a floating point variable orexpression. The function and output take the type (REAL or DOUBLEPRECISION)of the input. This generic function is recommended over ALOG (REAL) or DLOG(DOUBLEPRECISION) since it adjusts to the type of the translator option. Anexample using LOG is:

y = a - LOG(ABS(SIN(w*t)))

4.67 LOG10

FORM: y = LOG10(x)

The outputy is the common logarithm (i.e., to the base 10) ofx wherex is a floatingpoint variable or expression. The function and output take the type (REAL orDOUBLEPRECISION) of the input. This generic function is recommended overALOG10 (REAL) or DLOG10 (DOUBLEPRECISION) since it adjusts to the type ofthe translator option. An example using LOG10 is:

gdbn = 10.0*LOG10((dlp**2 + dlq**2)*(w/pi*xmag))**2)

4.68 LOGD

FORM: CALL LOGD(lexpr)

wherelexpr is a logical variable or expression. Write the PREPARE and OUTPUTlists. Output is written for each call to LOGD whenlexpr is TRUE. Output is writtenat every NCIOUT call to LOGD whenlexpr is FALSE. LOGD can be called in anysection of an ACSL program, and in FORTRAN subroutines called from ACSL.

The data logging operation for the OUTPUT and PREPARE lists is forced by a call tothis subroutine. Data logging takes place automatically only at the end of theDYNAMIC section and on exit from the TERMINAL section. LOGD can be used toobtain finer detail where required. An example of its use is to force a data loggingaction whenever a logical variable is TRUE as follows:

4.68 LOGD 4. ACSL Statements


LOGICAL hirateIF(hirate) CALL LOGD(.TRUE.)

Square cornersfor DISCRETE

plots

Each time LOGD is called, a time point is saved for the values of the variables on thePREPAR list. This can be useful for squaring off plots of sampled data values. Force adata logging before and after a sampling action (i.e., at the beginning and end of aDISCRETE section). Variables are then logged precisely as they change and plotsaccurately reflect the changes.

Help indebugging

On computers without a good system debugger, or in situations where the computerhangs, LOGD can help in debugging. Insert calls to LOGD throughout the program (atthe beginning and end of various sections, for example), or at least in areas ofsuspected problems, along with a variable set to some number. If the call is in a sortedsection or implicit program, put it in a PROCEDURAL as follows:

PROCEDURALaaaaa a = < some number >CALL LOGD(.TRUE.)END

Use a different number at each call in order to identify which LOGD produced whichOUTPUT line. At runtime, add AAAAAA to the OUTPUT list. START the modeland note which call to LOGD (as indicated by AAAAAA) appears last before the runcrashes.

OUTPUT T,aaaaaa, ...START

Check the model source file and/or the translated FORTRAN compile file for clues asto which statement after this last call to LOGD and before the next one not executedcaused the problem.

Logical argument The logical argument of LOGD affects only the action of printing the OUTPUT list. Ifthe logical is TRUE, the values of variables on the OUTPUT list are printed regardlessof the count relative to NCIOUT (number of communication intervals per OUTPUT);if FALSE, the call to LOGD is treated as another communication time and included inthe NCIOUT count. NCIOUT controls the OUTPUT rate.

4.69 LOGICAL

See TYPE.

4. ACSL Statements 4.69 LOGICAL


4.70 LSW, RSW

FORM: i = LSW(p, j 1, j 2)y = RSW(p, x 1, x 2)

where LSW is the integer switch, and RSW is the real (floating point) switch. Theoutputsi or y take on the value of the second argument,j1 or x1, when the logicalexpressionp has the value TRUE; otherwise they have the value of the third argument,j2 or x2. Thej1 andj2 are any integer expressions;x1 andx2 are floating pointexpressions. The LSW function is typed INTEGER intrinsically; RSW is floatingpoint. Examples of LSW and RSW statements are as follows:

INTEGER ncountLOGICAL countncount = LSW(count, ncount+1, ncount-1)cmal = cmalf(mach)*RSW(mach.GT.machmx, (xcg - xcp)/d, 1.0)

Alternative forlogicals

For logical switches, assignment statements are simpler and clearer. In the followingexample,SWITCHis TRUE whenX is greater thanXMIN and FALSE otherwise:

switc h = x .GT. xmin

Warning –all arguments

evaluated

Note that all of the arguments in the statement are evaluated, whether or not they areused. The following statement, therefore, results in an error ifP becomes zero:

y = RSW(p .EQ. 0.0, x, x/p)

Writing the statement as follows avoids the problem of division by zero:

y = x/RSW(p .EQ. 0.0, 1.0, p)

However, the following solution is preferable because it eliminates an IF statement:

y = x/(p + 1.0E-33)

The probably ofP being -1.0E-33 is effectively zero!

4.71 MACRO

FORM: MACRO name(x1, x 2, ..., x n)

The keyname MACRO denotes the beginning of a MACRO definition (if not alreadywithin a MACRO definition). Within a definition, it denotes special subcommands tobe interpreted by the macro processor. For a full description of the macro capability,see Chapter 6.

4.72 MAX

FORM: y = MAX(x1, x 2, ..., x n)

The output n is the value of the maximum argument, where the argumentsxi arevariables or expressions; any number of arguments may be included. Negative valuesare considered less than positive values. The type (INTEGER, REAL, orDOUBLEPRECISION) of the output is implied from the arguments.

nmax = MAX(num1, num2, 2*jj)w = MAX(wmn, kw*w)

4.72 MAX 4. ACSL Statements


4.73 MAXTERVAL,MINTERVAL

FORM: MAXTERVAL name = real constant

DEFAULT: name: MAXTreal constant: 1.0E+10

FORM: MINTERVAL name = real constant

DEFAULT: name = MINTreal constant = 1.0E-10

wherenameis a simple, unsubscripted variable. The maximum and minimum value ofthe integration step size can be controlled and renamed with these statements.

MAXTERVAL MAXTERVAL is the upper bound on the integration step size for both variable stepand fixed step algorithms.

MINTERVAL If a variable step size integration algorithm attempts to take a step smaller than thevalue of the applicable MINTERVAL, the error tag variable (see ERRTAG), if any, isset. If the error tag has already been set, then the termination flag is set. Fixed stepalgorithms ignore MINTERVAL.

Arrays withmultiple sections

If a program contains only one DERIVATIVE section and no DISCRETE sections,MAXTERVAL name (referred to by its default name MAXT hereafter) is a scalar;however, more than one DERIVATIVE and/or DISCRETE section results in MAXTbecoming an array. The elements in MAXT then correspond to the sections in theorder they are encountered in the source code. If MAXTERVAL is defined outside aDERIVATIVE section, then it is the global default for all DERIVATIVE sections; theelements for DISCRETE sections are ignored. To change MAXT for a specificDERIVATIVE section, put a MAXTERVAL statement with a unique name in thesection; for example,

DERIVATIVEMAXTERVAL maxtsm = 0.0001

The scalar name given is equivalenced to the array element; if the DERIVATIVEsection is first in the program, for example,MAXTSMis equivalenced to MAXT(1). Atruntime, either the array element or the local name can be referenced.

SET MAXT(1)=0.001SET maxtsm=8.05

MINTERVAL is similar, except that for DISCRETE sections the MINTERVALelements contain the value of the INTERVAL statement; a -1 indicates that there is noINTERVAL statement for the corresponding section.

Integration stepsize

The integration step size H for fixed step algorithms is calculated from CINT/NSTP(see CINTERVAL and NSTEPS statements) and then bound by MAXT;i.e.,

H = MIN(MAXT, CINT/NSTP)

For variable step algorithms, a lower bound of MINT is added:


Control of fixedstep integration

For fixed step algorithms, we recommend setting NSTP to 1 and MAXT to the desiredstep size. This approach decouples control of the step size from the communicationinterval CINT. CINT then is the data logging rate, MAXT is the integration step size,and each can be set separately without affecting the other.

4. ACSL Statements 4.73 MAXTERVAL, MINTERVAL


Runtime The values of these variables can be set by assignment statements in the program or bySET commands at runtime. For example, if the following statement is in a program,

MAXTERVAL MAXT1 = 1.0E-6

then at runtime its value can be changed:

SET MAXT1 = 2.0E-6

Even if the MAXTERVAL and MINTERVAL statements are not included in theprogram, they can be accessed at runtime using the default names of MAXT andMINT. It is seldom necessary to change MINTERVAL.

4.74 MERROR,XERROR

FORM: MERROR v1=real constant, v 2=real constant, ..., v n

XERROR v1=real constant, v 2=real constant, ..., v n

where MERROR is the relative error bound, XERROR is the absolute error bound,andvi are nonsubscripted variable names that are state variables (i.e., appear on the leftside of an INTVC or INTEG statement that is not embedded in an expression). Thestate itself can be an array, but then the errors specified apply to all elements in thearray. Individual elements cannot be given separate error tolerances.

If any relative or absolute errors are specified, the first specification encountered isapplied to all integrators that are unspecified. For example:

MERROR x=1.0E-4, y=1.0E-6

where:

x = INTEG(xd, xic)y = INTEG(yd, yic)z = 5.0*INTEG(zzz, 0.0) + COS(x)

Note thatZ in the above example cannot have any error bounds specified since it is nota state. The actual state is a generated variable name in the Znnnnn form that is placedin the translated assignment statement instead of the INTEG operator.

The MERROR and XERROR statements have meaning only for the variable stepintegration algorithms and are used to limit the error introduced at each step. Based onthe maximum absolute value of a state variable |vi |maxsince the start of the run (aCONTINUE runtime command is considered the start of a run in this context), theallowable error bound is defined to be:

Ei = MAX (Xi, Mi | vi | max )

If any of the predicted errors in an integration step is greater than the correspondingallowable errorEi, the step size is reduced appropriately. If the error is still too largeafter the step size has been reduced to the minimum (MINTERVAL), the ERRTAGvariable, if any, is set TRUE and the run aborted.

For states that are always less than 1.0, the absolute error dominates, which canpotentially be a problem. Absolute error is used to cover cases when the variable isnear zero. Usually relative error is the important consideration.

4.74 MERROR, XERROR 4. ACSL Statements


4.75 MIN

FORM: y = MIN(x 1, x 2, ... x n)

The outputy is the value of the minimum argument, where argumentsxi are variablesor expressions. Any number of arguments may be included. Negative values areconsidered less than positive values. The type (INTEGER, REAL, orDOUBLEPRECISION) of the output is inferred from the arguments.

ilo = MIN(imn+1, j, k5)maxtc = MIN(period/nstmn, maxtxz)

4.76 MINTERVAL

See MAXTERVAL.

4.77 MOD

FORM: y = MOD(x1, x 2)

The outputy is the remainder ofx1 divided byx2, wherex1 andx2 are constants,variables, or expressions. The type (INTEGER, REAL, or DOUBLEPRECISION) ofthe function and the output is inferred from the arguments. The generic MOD functionis preferred over the more specific AMOD1, MOD0, etc.

The actual implementation can be written as:

x1 − [x1 ⁄ x2 ] x2

where [ ] is an integer with magnitude of not more than the argument and with thesame sign. Examples of MOD are:

INTEGER j, k, idiv, icounticount = 100 + MOD(j*k+100, idiv)fis = MOD(INTEG(fisd, fisic), twopi)

4.78 NINT

FORM: n = NINT(x)

The outputy is the nearest integer ofx wherex is a floating point variable orexpression. The output type is always INTEGER. This function differs from INT orAINT, which truncate the input, and from ANINT, which is the nearest whole numberwith output of type REAL or DOUBLEPRECISION. NINT could be used in asubroutine argument list as follows:

CALL mysub(NINT(v1), ...)

4. ACSL Statements 4.75 MIN


4.79 NSTEPS

FORM: NSTEPS name = integer constant

DEFAULT: name: NSTPinteger constant: 10

wherenameis a simple, nonsubscripted variable. The NSTEPS statement defines theintegration step size in terms of the communication interval;i.e., NSTEPS is thenumber of integration steps in a communication interval.

The NSTEPS statement can also be used to rename the variable something differentfrom the default of NSTP.

Type The variable named in the NSTEPS statement is automatically typed INTEGER.

Variable stepalgorithms

The effect of NSTEPS with variable step algorithms differs from that with fixed stepalgorithms. Setting NSTP to a relatively large number is a means of helping a variablestep algorithm start at an appropriate size. For variable step algorithms, the step size His determined by:


In other words, the communication interval is divided by NSTP and then the results isbounded by MINT and MAXT. If the first try is too large (i.e., if the estimated error islarger than the allowed error), the algorithm reduces the step size and tries again, untilit finds a small enough step size to start off. Setting NSTP to a fairly large number(1000, for example) starts the routine at a small step size, which is then increasedautomatically as the run progresses until it reaches the most efficient size. Beware ofleaving NSTP at a large value and switching to a fixed step algorithm.

Fixed stepalgorithms

For fixed step algorithms (IALG = 3, 4, or 5), MINT is ignored so the step size iscalculated by:

H = MIN(MAXT, CINT/NSTP)

We recommend that NSTP be set to 1 so that the integration step size can becontrolled by MAXT, specified based on knowledge of the plant dynamics; forexample:

NSTEPS nstp1 = 1MAXTERVAL maxt1 = 0.001CINTERVAL cint = 0.1

With this procedure, the data logging rate (CINT) is decoupled from the integrationstep size (now simply MAXT1) so that each can be set independently withoutaffecting the other.

Array of NSTP When a program contains more than one DERIVATIVE and/or DISCRETE section,NSTEPS becomes an array of length ZZNBLK (the number of sections in theprogram). The elements of the array correspond to the sections in same order as theyappear in the program. For DERIVATIVE sections, each slot contains the appropriatevalue of NSTEPS, which can be set either globally or else individually for eachsection. For DISCRETE sections, the slot in NSTEPS is ignored and INTERVAL isused for the step size of any integrations.

4.79 NSTEPS 4. ACSL Statements


4.80 OPEN

FORM: OPEN([UNIT =] lu[, IOSTAT = ios

, ERR = s, FILE = fin, STATUS = sta, ACCESS = acc, FORM = fm, RECL = rl, BLANK = blnk])

where the arguments follow the Fortran 77 standard. See your local Fortran referencemanual. The only argument required is the logical unit number.

4.81 OU

FORM: y = OU(τ, m, s)

OU(y = τ, m, s)

where:

τ = low-pass filter time constant; the break frequency is 1⁄ (2π τ) Hz

m = mean value ofys = standard deviation (RMS value) ofy

The OU operator may be used only in a sorted section or implicit program. It shouldnot be used in a PROCEDURAL. For a random number generator in a nonsortedsection, use GAUSS or UNIF.

Band limited white noise is implemented by this Ornstein-Uhlenbeck function. Anormal random number generator (GAUSS) delivers a fixed total power (RMS value),but the frequency spread depends on the current step size. Usually the low frequencypower density is important, so casual use of GAUSS into a low pass filter leads toill-defined variation of this quantity as the step size is changed. The Ornstein-Uhlenbeck process maintains a constant source of power over a specified frequencyband, thus eliminating any problem of having to include the current integration stepsize in the standard deviation of the random variable.

Note that in general the roll-off time constantτ should be at least twice the size of themaximum integration step; use MAXTERVAL to enforce this constraint.

The operator is implemented by generating a correlated noise sequence from thegeneral formula:

n i+1 = ni e−∆t ⁄ τ + ωi

where:

τ = correlation time constant

∆ t = sample interval

ωi = Gaussian random variable

In order to find theωi that produces the correct noise power such that:

4. ACSL Statements 4.80 OPEN


n2__

= σ2__

square the above equation forn i+1 and take the expected values:

nn+12

____= ni

2__

e−2 ∆ t ⁄ τ + ω12

___

It can be assumed that the random drive is uncorrelated with the noise sequence;i.e.,

ni ωi

____= 0

But:

ni2

__= ni+1

2____

= σ2__

so:

ωi2 = σ2 ( 1 − e− 2 ∆ t ⁄ τ )

and now the sequence can be expressed by

n i+1 = ni e−∆ t ⁄ τ + σ √1 − e− 2 ∆ t ⁄ τ

gi

wheregi is a Gaussian random variable of zero mean and unit variance. An exampleusing the OU operator is:

noise = OU(ta1, mean, sigma)

4.82 PAGE

FORM: CALL PAGE(K, NLL)

whereK is a code to modify the page eject as follows:

-2 suppress auto page eject, eject next write-1 suppress auto page eject0 ignore auto page eject but return NLL1 turn on auto page eject2 turn on auto page eject, eject next write

andNLL is returned as the number of lines left on the current page.

The subroutine PAGE is used to force a top-of-form and turn on or suppress auto pageeject. As a by-product, the number of lines left on the current page is returned as thesecond argument. For example, in order to force a new page before writing ten linesvia a formatted write statement, use the following code:

CALL PAGE(2, NLL)CALL LINES(10)WRITE(6, 99) ...

The ACSL system normally operates in an internal auto page eject mode. Theexception is the printer PLOT command, when plots can span page boundaries. Autopage eject is then restored after each PLOT.

There may be a conflict using the PAGE statement when using the plotting packageDISSPLA, which also has a PAGE command.

4.82 PAGE 4. ACSL Statements


4.83 PARAMETER

FORM: PARAMETER(p1 = e1[, p 2 = e2] ...)

The PARAMETER statement associates the symbolic name with an expression thatcan be made up of constants and/or previously defined parameters butnotvariables.The symbolic name may then be used whenever an integer, real, logical, or characterconstant would normally appear in the program code.

Dictionary The PARAMETER namepi doesnotappear in the program dictionary and is replacedeverywhere by the value of the corresponding expressionei.

Expression The expression (ei) can consist of literal constants, PARAMETER names, andarithmetic operators (+, -, *, /).

Type INTEGER PARAMETER variables are not automatically typed INTEGER, even if they beginwith letter I, J, K, L, M, or N. Include an INTEGER type statement for any integerPARAMETER variable names before they are used.

Placement inprogram

The PARAMETER statement must appear in the program before the parameter isused; otherwise, the translator produces an error message:

...Parameter already defined NAME

Example PARAMETER statements are useful for defining things like array sizes and forkeeping the definitions in one place. For example,

INTEGER maxdimPARAMETER (maxdim = 5)DIMENSION a(maxdim,maxdim), v(maxdim), r(maxdim)CONSTANT v = maxdim*1.0

4.84 PRINT

See I/O.

4.85 PROCEDURAL

FORM: PROCEDURAL(output list = input list)...END

where:

output list = v1, v2, ...,vn

input list = e1, e2, ...,en

andvi are nonsubscripted variable names whileei may be variables or expressions.The PROCEDURAL header must be paired with a matching END statement.

The PROCEDURAL keyword denotes the beginning of a block of PROCEDURALcode to be executed in the sequence given;i.e., the code within the PROCEDURALblock is not sorted by the ACSL translator. PROCEDURAL blocks are required onlyin sections that are sorted. They are permitted but not required in non-sorted sectionsof the program.

4. ACSL Statements 4.83 PARAMETER


Arguments The header list should contain only nonsubscripted variable names. The variablenames may belong to arrays, however, in which case the entire array must be filledwithin the block. The sort algorithm requires that values appear as outputs only oncein sorted code; otherwise the error messageMultiply defined symbolis issued.

States and constants do not need to be included in the argument list because they areavailable all the time. Calculated variables are needed because they tell the sorterwhere to put the procedural in relation to calculations.

Array example As an example, the following statements in a sorted program result in the variable Abeing flagged as defined twice:

a(1) = x + ya(2) = y + z

This is illegal. An acceptable form would embed this sequence in a PROCEDURALblock, informing the sort routine to place the block before reference to any element ofthe array A, as follows:

PROCEDURAL(a = x, y, z)a(1) = x + ya(2) = y + zEND

Sorting operation The entire PROCEDURAL block is moved by the translator within a DERIVATIVEsection so that it is placed after the calculation of all variables on the input list andbefore the use of any variables on the output list. Although other variables may bepresent on the list, sorting is only with respect to variables calculated within the sameDERIVATIVE section. The sort operation never moves code across sectionboundaries. The entire DERIVATIVE section can be made a PROCEDURAL, andsince it then cannot be moved, no input or output argument list is necessary. It is betterto use more small PROCEDURALs rather than fewer large ones.

When required PROCEDURAL blocks should always be used in sorted sections around codeconstructs in which the order must not be changed. Typical operations which must beenclosed in PROCEDURAL blocks include DO, GO TO, IF, and array calculations.The IF-THEN-ELSE block does not require a PROCEDURAL even in sorted sections.

With subroutinecalls

Another construct which may require a PROCEDURAL is the subroutine call. IfACSL is not informed which arguments are inputs and which are outputs, a subroutinecall may not be sorted correctly. Enclosing subroutine calls in PROCEDURAL blocksor using an equal sign in the subroutine argument list are methods of clarifying inputand output lists for the translator (see CALL).

With algebraicloops

Experts may lie in specifying what is on the input/output lists. The ACSL translatornever looks inside the PROCEDURAL block to ensure compliance with the listsupplied, so it is possible to break algebraic loops for approximate solution byomitting one of the loop variables from the PROCEDURAL input list. Since thisvariable is used before it is calculated, initialization in the INITIAL section is required.In breaking implicit loops this way, the last value of the variable is used, which issatisfactory in a large number of cases. Be warned however that the results changewith step size and a variable phase shift is present in traversing the implicit block. Thisalso destroys the validity of the Jacobian and all derived quantities such aseigenvalues, zeros, etc. Use IMPLC to handle algebraic loops.

Warning –memory

operators

Statements involving memory operators should not be included in PROCEDURALblocks because parts of these operators must be separated for sorting. These operatorsare BCKLSH, CMPXPL, DBLINT, DERIVT, LIMINT, and OU.

4.85 PROCEDURAL 4. ACSL Statements


Integrationoperators

Using integration operators (INTEG, REALPL, etc.) inside PROCEDURAL is notillegal but does not make sense. States cannot be computed procedurally, onlyderivatives can.

4.86 PROGRAM

FORM: PROGRAM [string]...END

wherestring may contain any number of characters, which are ignored. ThePROGRAM statement is the first line in an explicit model definition. It must beaccompanied by a matching END statement to terminate the model definition. Thecharacter string is not used in any way and serves merely to identify the model file andlisting. For example:

PROGRAM a missile 6DOF simulation

For implicit programs (i.e., those with no explicit structure statements), useDERIVATIVE rather than PROGRAM. This approach is required because somesystem macros have INITIAL sections, which expect explicit structure with thePROGRAM statement. A DERIVATIVE statement can include aname, but for a titlewith more than one word, use the comment indicator.

DERIVATIVE ! title of program...END

4.87 PTR

FORM: PTR(x , y = r, θ)

The polar to rectangular operator resolves angleθ (which must be expressed inradians) and radiusr into Cartesian coordinatesx andy (with the same units asr) bythe following equations:

x = r cosθy = r sin θ

This form is not a functional representation since there are two outputs. Thus, thisstatement cannot be embedded in an expression; it can only stand alone as shown.Figure 4-11 lists the mechanization of this operator as a system macro.

An example of PTR is:

PTR(rt1, rt2 = lrt, fi)

MACRO ptr(x1,x2,r,th)x1 = (r)*COS(th)x2 = (r)*SIN(th)MACROEND

Figure 4-12. PTR operator macro

4. ACSL Statements 4.86 PROGRAM


4.88 PULSE

FORM: y = PULSE(tz, p, w)

wherey is a pulse train (0.0 or 1.0) starting at the first integration step at which timeequals or exceedstz. The period isp and width isw, as shown in Figure 4-13. Thewidth cannot be zero.

The independent variable, default T, drives the PULSE function. Note that theintegration step size may affect the answers in that too large a step could cause thepulse to seem to stay on indefinitely. The output is always turned on (y = 1.0) at thebeginning of the first integration step following the exact turn-on time. The width isnot synchronized to the integration step size, so it should be significantly larger thanthe step size.

Do not use PULSE as a strobe to periodically activate parts of a program. This is a jobfor DISCRETE sections executed by means of INTERVAL statements or theSCHEDULE operator.

PULSE could be used as follows:

drive = k*PULSE(tdrive, period, width)

4.89 QNTZR

FORM: y = QNTZR(p, x)

wherex andp are real variables or expressions. The outputy is the value ofxquantized in discrete steps of resolutionp. This is a zero centered system, as shown inFigure 4-14. An example of QNTZR is:

epq = QNTZR(ep, signal - oldsig)

Figure 4-13. Mechanization of PULSE Function

4.89 QNTZR 4. ACSL Statements


4.90 RAMP

FORM: y = RAMP(tz)

The RAMP function generates a linear ramp of unit slope, starting at a specified timetz. It is another way of applying a dead zone to the independent variable.

RAMP starts at the first integration step that equals or exceedstz, as depicted in Figure4-15. The output can be expressed as follows:

y = 0.0 ; T < tzy = T − tz ; T ≥ tz

An example of a RAMP statement is:

z = k1 + k2*RAMP(tramp)

4.91 READ

See I/O.

Figure 4-14. QNTZR quantizer function

Figure 4-15. RAMP function

4. ACSL Statements 4.90 RAMP


4.92 REAL

FORM: REAL(x)

This function converts an integer, double precision, or single precision argumentx to asingle precision value. See DBLE for a discussion of usage.

See also REAL as a single precision floating point variable type under TYPE.

4.93 REALPL

FORM: y = REALPL(p, x[, ic])REALPL(y = p, x[, ic])

The REALPL operator produces a first order lag where outputy is related to inputxthrough the transfer function:

yx

= 1ps + 1

where:

y(0) = ic

Figure 4-16 lists the macro to implement this operator.

The initial condition has the same restrictions as the INTEG operator;i.e., if it is asimple variable (the preferred form), this variable name must not be used as anotherinitial condition, state, derivative, or system variable name. If the initial condition iszero, it may be omitted. The time constantp may be an expression of arbitrarycomplexity, but it cannot be zero or division by zero results.

An example of a REALPL statement is:

xm = k3*REALPL(ta3, x)

MACRO realpl(y,p,x,ic)MACRO STANDVAL ic=0.0y = INTEG((x-(y))/(p),ic)MACROEND

Figure 4-16. REALPL operator macro

4.93 REALPL 4. ACSL Statements


4.94 RESET

FORM: RESET("EVAL")RESET("NOEVAL")

This special operator is provided for use in the INITIAL section to initialize the statevariables and optionally perform intermediate calculations.

Argument The arguments EVAL and NOEVAL specify whether or not a complete derivativeevaluation is to be attempted. It is your responsibility to ensure that unknown initialconditions have reasonable values to prevent arithmetic errors (division by zero, forexample).

When states areinitialized

Starting at Version 11, the states are initialized at thebeginningof the INITIALsection, the equivalent of RESET("NOEVAL"). Previously, states had been initializedat theendof the INITIAL section, so there was more reason to use this operator. Nowonly RESET("EVAL") is needed.

Accelerometerexample

RESET could be used for example in calculating the initial conditions onaccelerometer filters in a missile simulation. In order to obtain the nominalacceleration, the missile velocity vector must be rotated into the missile axes, the angleof attack determined, and the aerodynamic coefficient data looked up to obtain forcecoefficients. This code must be expressed in terms of the initial condition variablesrather than the state variables unless the RESET operator is used. If theRESET("EVAL") statement is placed at the beginning of the INITIAL section, thederivative subroutine calculates body acceleration using the state variable names.

Warning – allderivativescalculated

The problem in using RESET is that the process is not selective; calculation of all statevariable derivatives is attempted. In the above example, the output of theaccelerometer filter is used later and if initialized indefinite leads to an arithmeticerror. If the undefined initial conditions are preset in a CONSTANT statement (0.5 is auseful default number), then the calculation can proceed and the meaningless numberscan be disregarded. The important consideration is that all the calculations be able toproceed without arithmetic errors.

Implementation The RESET operator is defined in terms of a state vector (S) and an initial conditionvector (IC). The state derivative vector is given by:

S.

= f (S, T )

Now the RESET(a) action can be expressed:

S ← IC (move initial conditions into state table)T ← ZZTICG (move independent variable IC into independent variable)

IF(a = EVAL) evaluatef (S, T )

4.95 RSW

See LSW.

4. ACSL Statements 4.94 RESET


4.96 RTP

FORM: RTP(r, θ = x, y)

The rectangular to polar operator resolves the input Cartesian coordinatesx andy intopolar angleθ (which is in radians in the range− π to + π depending on the magnitudeand sign ofx andy) and radiusr (which has the same units asx andy) by the followingequations:

r = √x2 + y2

θ = ATAN2 (y, x )

Figure 4-17 shows the mechanization of this operator as a system macro. Note that thesecond argument of the arc tangent (ATAN2) is modified by the addition of a verysmall amount. This enables inputs of 0.0, 0.0 to return an angle of zero instead ofindefinite.

This form of the operator is not a functional representation since there are two outputs.Thus, this statement cannot be embedded in an expression; it can be used only in thestandalone form as shown.

An example of RTP is:

RTP(ra, tha = xa, ya)

4.97 SAVE

FORM: SAVE

The macro tables containing the macro names and packed definitions are written (inbinary) on the ACSL system macro file. The SAVE operation allows you to maintainyour own files of macros separate from the system file.

The normal operation of the system is to read into the macro definition tables thecontents of the user macro file before the translation begins. If such a file does notexist, no user macro definitions are present.

The action of SAVE is to write the current contents of the macro tables back on thisfile, thus destroying the original contents. To use SAVE, you must have WRITEpermission on the current macro file.

Since the procedure for writing a user macro file varies depending on the computersystem, it is described in theACSL Sim User's Guide.

MACRO rtp(r,th,x1,x2)r = SQRT((x1)**2+(x2)**2)th = ATAN2(x2,x1+1.0e-30)MACROEND

Figure 4-17. RTP operator macro

4.97 SAVE 4. ACSL Statements


4.98 SCALE

FORM: SCALE(smn, smx = ymn, ymx)

where:

ymn, ymx = minimum and maximum values

smn, smx = scaled minimum and maximum to be used on a plot(i.e., rounded multiples of 1, 2, 4, or 10).

The SCALE operator rounds the inputs so that they are suitable for plotting. Theinputsymnandymxare usually collected in the DYNAMIC section by keeping trackof the smallest and largest values of the variable of interest. The SCALE operator isthen used in the TERMINAL section of an explicit program to establish scale factorsfor subsequent PLOT commands. It is used only when two or more plots need thesame, originally unknown, scale factors.

The first two arguments need not be distinct from the second;i.e., the followingstatement replaces actual minimum and maximum values with the rounded ones:

SCALE(ymn, ymx = ymn, ymx)

4.99 SCHEDULE

FORM: SCHEDULE block/flag .AT. time-expressionSCHEDULE block/flag .XZ. real-expressionSCHEDULE block/flag .XP. real-expressionSCHEDULE block/flag .XN. real-expression

where:

block= optional block name of DISCRETE section to be executed after the statehas been advanced just over the boundary

flag = optional flag name that is automatically made type LOGICAL and setTRUE when the event has occurred (may not be an array)

.AT. = following expression specifies time at which block is to be activated(maynotbe used in a DERIVATIVE section)

.XZ. = zero crossing (positive or negative direction) of following expressioninitiates finding time of zero crossing (may be usedonly inDERIVATIVE section)

.XP. = zero crossing (positive direction only) of following expression initiatesfinding time of zero crossing (may be usedonly in DERIVATIVEsection)

.XN. = zero crossing (negative direction only) of following expression initiatesfinding time of zero crossing (may be usedonly in DERIVATIVEsection)

Theblock / flagis optional; however,flag cannot be used without ablockalso beingpresent. SCHEDULE can be used without ablockor flag in order to force integrationto a certain point.

Flag setting If a flag is specified, it is set TRUE just before the DISCRETE section is executed,stays TRUE during execution of the section, then is set back to FALSE.

4. ACSL Statements 4.98 SCALE


Flag example The flag is available to handle logic, generally within a single DISCRETE section, asin the following example:

PROGRAMINITIAL

y = 0.0END ! of InitialDERIVATIVE

x = SIN(t)SCHEDULE d/f1 .XZ. x+0.5SCHEDULE d/f2 .XZ. x-0.5TERMT(t .GE. tstop, 'Stop on time');CONSTANT tstp=4.9

END

DISCRETE dIF(f1) THEN

y = 2.5ENDIFIF(f2) THEN

y =-2.5ENDIF

END ! of DiscreteEND ! OF Program

Expressions Thetime-expressiondefines a time (real value) of the independent variable at whichthe event is to be activated. Thereal-expressiondefines a function, the zero crossingof which (in the appropriate direction) defines the event. Thisreal-expressionmust bea true function of the state variables in that the same set of state variables mustproduce identical values of the function no matter how many intermediate evaluationsoccur. If thereal-expressionis not a true function, the following error message may beproduced.

Event vanished - cannot proceed

WEDITG A summary of the activity at the time of an event (i.e., finding and narrowing thewindow and calculating the value of the expression at each evaluation) is produced atruntime at each occurrence of an event. In the example in Figure 4-18, the event finderis activated in the first line and the window is narrowed over five iterations. The lasttwo lines of the summary give the values of the independent variable and the zerocrossing expression along with the number of the DISCRETE section (i.e., the positionof the section among the DERIVATIVE and DISCRETE sections in the program)executed.

This output can be suppressed by setting runtime system symbol WEDITG (writeevent description, default TRUE) to FALSE.

Handlingdiscontinuities

The SCHEDULE operator handles the introduction of discontinuities into anotherwise continuous simulation. The integration algorithms used to solve equations inthe form:

x.

= F (x, t)

conventionally require the function F to be continuous and differentiable within anintegration step. The automatic variable step algorithms such Adams-Moulton orGear's Stiff (IALG = 1 or 2) or Fehlberg (IALG = 8 or 9) reduce the step size in theregion of a discontinuity in F at the expense of increased processing time, and it isdebatable how well the error control mechanism works in the event of a discontinuityin one of the state variables. Nature has no real discontinuities given a sufficiently finetime scale; discontinuities arise from simplifying the model and observing the systembehavior in a macro time scale.

4.99 SCHEDULE 4. ACSL Statements


Bouncing ballexample

In the example of a ball bouncing, the macroscopic view shows the velocity changingdiscontinuously (by the coefficient of restitution) at the instant of bounce. In themicroscopic view, the spring constant of the ball is taken into account and all theforces of deformation are calculated, significantly increasing the model complexity buteliminating the discontinuity.

Digital controllerexample

Another example is a digital controller. From a macroscopic viewpoint, the output isan analog control voltage through a digital to analog converter (DAC), which jumpsdiscontinuously at the output time points. At a microscopic level, voltages cannotchange discontinuously since finite capacitances are always present and must becharged through some sort of resistive network. A simulation normally takes themacroscopic view (i.e., a voltage jump) for efficiency, the designer deciding whichtime scale of events is important for model validity.

Switch point If a point of discontinuity can be located, the solution on either side of thediscontinuity can be treated as piecewise continuous. A possible penalty is that thevariable step algorithms may have to be restarted after a discontinuity since they keeptrack of an estimate of derivatives (a Nordsieck* vector) which is probably invalidatedat a switch point.

Time vs. stateevents

Two types of discontinuity are encountered in general simulation models; one we calla time event and the other a state event. Time events can always be defined as stateevents, but for efficiency they are extracted as a separate case. State events can bevisualized as occurring at surfaces in state space. Such surfaces include the zero heightplane in the bouncing ball problem, the zero velocity plane in Coulombstiction/friction, and the critical temperature plane for a reactor shutdown event. Theintegration algorithm advances in discrete steps which at some point takes the modelacross the critical surface; the problem is in finding the exact crossing point.

Event number 1 activated at 1.00000000 with value 0.00499994

Event number 1Window between -1.0000E+37 and 1.00000000Currently at 0.99500000 with value -0.04392740

Event number 1Window between 0.99500000 and 1.00000000Currently at 0.99948900 with value -1.1064E-05

Event number 1Window between 0.99948900 and 1.00000000Currently at 0.99949000 with value 4.4703E-08


Event number 1Window between 0.99949000 and 0.99949000Currently at 0.99949000 with value 4.4703E-08Event occurred at 0.99949000Event 1 with expression value 4.4703E-08 serviced with block 2

Figure 4-18 Event activity summary when WEDITG is TRUE

4. ACSL Statements 4.99 SCHEDULE


* Nordsieck, A., "On the Numerical Integration of Ordinary Differential Equations"Math. Comp(1962) pp. 22-49.

Finding the event In the special case of a time event which is a wall perpendicular to the time axis, theintegration step can always be taken as the minimum of the normal step or the time leftto the event, so no iteration is required. For state events, where the boundary is ageneral surface in state space, an iteration brackets the event to a finer and finertolerance until a specified accuracy is reached. Mathematically the problem is stated:

x.

= F1(x, t ) ; g(x, t ) ≥ 0x.

= F2(x, t ) ; g(x, t ) < 0

where the plane in state space distinguishing the event can be expressed by:

g(x, t ) = 0

whereg is a single-valued function of the state variables and time.

Changingboundaries

In actual fact, the situation can be complicated by the boundary function changingwhen the state equations switch fromF1 to F2. Examples of changing boundariesinclude backlash, hysteresis, and Coulomb friction. In the friction model, the boundaryfunction is zero velocity when the body is sliding and applied force exceedingbreakout force when the body is stuck.

Warning –IF constructs

State events cannot be scheduled from IF constructs because ACSL has to keep acount of the state event statements. Time events can be used inside IF or DOconstructs in unsorted sections such as DISCRETE or INITIAL. Multiple IFstatements are dangerous; instead, use an IF-THEN-ELSE construct, which covers allthe bases so a value is not left around inadvertently.

4.99.1 SCHEDULETime EventSpecification

A time event is defined by the .AT. form of the SCHEDULE statement. The timeevent SCHEDULE must be specified in a DISCRETE section (or in the INITIALsection) and may not be included in a DERIVATIVE section. Every execution of thetime event operator places a marker in the event list to execute a block at a particulartime. If this were executed in a DERIVATIVE section where the code is executed andre-executed many times under the control of the integration algorithm, the event listwould fill with these markers.

A simple example in an INITIAL section to execute DISCRETEswitch:

INITIALCONSTANT swtime = 10.0SCHEDULE switch .AT. swtime

...END

Execution time If the value of thetime-expressionis less than the current time, the block is executedimmediately after the current DISCRETE block has finished. Time in the continuoussection can never go backwards (with the exception of the entire model movingbackwards as described in Chapter 8).

Digital controllerexample

An example of the use of time events is the modeling of a digital controller with ananalog to digital converter (ADC) sampling values from the continuous process, adelay while control output values are computed, and then transfer of these values,usually as voltages through DACs, but also as switch closings to activate solenoidsand control valves. For example, for a sampling time of 10 msec and compute delay of4 msec, the code for the relevant DISCRETE sections could be as follows:



DISCRETE adcINTERVAL tsamp = 0.010outp = F(sampled inputs)CONSTANT dlt = 0.004SCHEDULE dac .AT. T + dlt

END ! of adc section

DISCRETE dac! Executed 4 msec after adcout = outp

END ! of dac section

The DISCRETE section ADC contains an INTERVAL statement which ensures thatthe section is executed every 0.010 sec. When it is executed, all the state variables inthe continuous section have been advanced to the sampling time, so they are allavailable as though they had been passed across an ADC channel, except for possiblequantization noise. The output can be calculated but must be hidden from thecontinuous world because it actually comes out of the DAC some time later. In theprogram, it is hidden by giving it a different name (OUTP). The SCHEDULEstatement in the ADC section asks for the DAC time event to be executed at T + 0.004sec after the ADC section has executed. The DAC block is entered on the event listand control returns to the integration algorithms to advance the continuous statevariables until the next event occurs. Time advances the 4 msec and the DAC block isexecuted, transferring the hidden output variable OUTP into OUT, the name used bythe continuous part of the simulation.

No INTERVAL Since the DISCRETE section DAC has no INTERVAL statement, the only time it isexecuted is when it is SCHEDULEd from the ADC section.

DISCRETEscheduling itself

As mentioned above, only DISCRETE sections can be scheduled for execution, andtime events must be specified within DISCRETE or INITIAL sections. Schedulingtime events in DERIVATIVE or DYNAMIC sections results in the same event beingscheduled many times (i.e., every time the DERIVATIVE or DISCRETE section isexecuted). A DISCRETE section can schedule itself for execution in the future, thusreplacing the INTERVAL statement.

Event list All time events are kept on the event list, which is ordered in time. Thecommunication interval for data recording is itself classed as an event and entered onthis list. When control is transferred to the continuous integration section, it firstchecks the event list for the next time event and makes this its goal, advancing with thenormal step size selection mechanism until a short step is required to reach the event.When all DERIVATIVE blocks have arrived within the tolerance EPMX (explained inthe section on the state event mechanization) of the time event point, the event isdeleted from the event list and the associated DISCRETE block (if any) is executed.

The Discrete Sampled Compensator example in Appendix A shows how time eventscan be used in a digital data system.

4.99.2 SCHEDULEState EventSpecification

Specifying an event boundary activates an iteration within the integration algorithm tocross the event boundary with a minimum step size. The forms of SCHEDULE whichapply to state events are .XZ. (cross zero), .XP. (cross positive), and .XN. (crossnegative). They may appear only in DERIVATIVE sections.



Bouncing ballexample

An example of a state event specification is finding the bounce point of a balldropping (under the acceleration of gravity) with the following statement:

SCHEDULE bounce .XN. h

which executes a DISCRETE block called BOUNCE when height H crosses zero inthe negative direction. In the BOUNCE section, velocity is reversed and modified bythe coefficient of restitution as follows:

DISCRETE bouncev = -kr*v

END

Flag vs. multipleDISCRETE

Handling multiple events with a single block usually requires a flag so that the eventscan be sorted out, but using SCHEDULE operators with separate DISCRETE blockscan remove that requirement.

Warning – don'tskip over stateevent operator

The state event SCHEDULE operator must be placed in a DERIVATIVE section. Itmay not be placed inside a PROCEDURAL. It may not be skipped over by the use ofGO TOs or other control transfer mechanisms (such as the various IF constructs) sinceACSL needs to keep a count of the SCHEDULE statements. The statement may beplaced anywhere in the DERIVATIVE section, but execution is slightly more efficientif it is placed at the beginning of the section since only the code necessary to evaluatethe event zero crossing expressions is executed when the time comes to test the event.

4.99.3 SCHEDULEState EventMechanization

At the beginning of a simulation run, the DERIVATIVE code is executed. Each call tothe state event handler increments a counter so that ACSL knows how many events arein operation. If no active state events are present, then there is no need to test for anevent at each step. All state SCHEDULE statements must be evaluated at everyDERIVATIVE evaluation because they are known by the count of order of appearance.

Implementation After the integration algorithm has been initialized, the integration system saves all thestate variables at the beginning of a step, makes the step without regard to any events,and then calls the DERIVATIVE evaluation block one last time to see if the stateshave crossed the event threshold. Testing is not done during intermediate evaluationsof the derivatives since these are extrapolations of much lower accuracy in generalthan the final step. Since this final evaluation is not part of the evaluation of thederivatives and states (its purpose is only to evaluate the expressions required toexecute the DISCRETE block associated with the event), a count is kept and when allexpressions corresponding to the state event definitions have been evaluated, then theremainder of the code is skipped. If the expressions are functions of only statevariables, the sorter does not have to move them. If they are functions of intermediatecalculated quantities (dynamic pressure, for instance), the event specification is sortedto a position just after the calculation of its inputs, thus minimizing the code executedat the threshold test phase.

The first derivative evaluation during the initialization process saves the current valueof thereal-expression(EXPR) as the previous value (EXPP). At each subsequent step,the current value is tested to see if EXPP and EXPR bracket zero. The code is asfollows:

IF(expr*expp .LT. 0 .AND. expp .NE. 0) GO TO event



Starting on zero Note that if the previous expression EXPP is exactly zero, then no event is signalled.An event is defined as starting from a non-zero value, with the new value crossing orlanding exactly on the zero point. An advantage of this method is that the expressioncan start at zero and no event is indicated until the expression returns to cross zero.

Multiple events Any number of events can be specified and they all are found in sequence. A crossingpoint is estimated for each event activated within a step, then the smallest value of theindependent variable (time) is selected.

Iterating to step The iteration within a step proceeds until the zero crossing is within a window lessthan the tolerance, in which case time is advanced to the most positive edge of thewindow by calculating the appropriate step size from the saved state condition (at thebeginning of the activating step).

ExecutingDISCRETE

Once the step has been taken, the DISCRETE block (if any) associated with eachactive event is executed so that model conditions can be changed. Usually there is onlya single event pending since it is separated in time from other events. However, it ispossible that more than one event occurs in the same step and then each associatedDISCRETE block (which may be the same one called by different events) is executedin servicing each event.

Re-evalutateDERIVATIVE

After each pending event has been serviced by executing the associated DISCRETEblock, the DERIVATIVE routine is executed one last time with a flag set to causereplacement of all previous values (EXPP) with current values. Any current events arethus taken off the active list since the expression must now cross zero from the otherside (.XZ.) or return to the other side in order to cross zero from the same direction(.XP.) for the next event.

DISCRETE canchange switching

function

Note that the execution of the associated DISCRETE block can set variables in such away as to change the switching function completely. In the case of friction, theswitching function FI can be written:

fi = RSW(stuk, ABS(force) - breakf, veloc)

where the function RSW (real switch) returns the value of the second argument if thefirst argument is TRUE; otherwise, it returns the third argument.

When the body is stuck (STUK is TRUE), the event occurs when the force acting onthe body (FORCE) exceeds a breakout force (BREAKF);i.e., when the expressionABS(FORCE) - BREAKF crosses zero. When the body is not stuck, it sticks when thevelocity crosses zero. The units of the zero crossing function thus change dependingon the regime in which the model stands;i.e., Newtons of force when the body isstuck, and meters per second for velocity when it is not stuck. This sticking/unstickingis discussed in more detail in the example on friction in Appendix A.

Window tolerance The tolerance for bracketting an event is chosen from the minimum step size (MINT)for the DERIVATIVE section and a machine-dependent fractional multiplier on time(referred to as EPMX). On 64 bit computers, EPMX is defined as 1.0E-9; thus thewindow at a simulated time of 50 seconds is 0.05µsec (50 x 1.0E-9), which is largerthan MINT (1.0E-10 by default). If MINT is increased from its default, then it wouldnormally become the control for tolerance, and you assume responsibility for choosingthe tolerance relative to the model dynamics. For 32 bit computers, machine accuracyfor single precision is only about one part in eight million, so the machine toleranceEPMX is taken as 1.0E-6. Steps of zero length must be avoided when stepping throughthe zero crossing; a factor of about ten to eighty times the machine precision seems tobe adequate.

Handlingdiscontinuities

Confining discontinuities to the DISCRETE event servicing block is a soundapproach. The DERIVATIVE equations can then remain continuous through the



event, which allows the event to be found, slopes and states changed, and theintegration routine restarted so that past derivative history is discarded. (SubroutineRSTART, described in Appendix B, can be used to help restart a variable stepalgorithm.)

SIGN example An example of a discontinuity to which the SCHEDULE operator can be applied is theSIGN function. The following statement:

force = SIGN(kslid, -veloc)

indicates that FORCE is to change discontinuously to oppose the velocity, whichaffects the integration step when the velocity crosses zero. The actual integration stepthat crosses the boundary has trouble with the discontinuity. In some cases it fails tocross the boundary entirely when the actual step is taken by adding up the weightedintermediate calculated (i.e., fixed step algorithms such as Runge-Kutta fourth orderwith first order extrapolators). For this case, a better implementation is as follows:

force = fslidSCHEDULE handl .XZ. veloc...

DISCRETE handlfslid = SIGN(kslid, -veloc)

END ! of discrete

Now the force is continuous and differentiable (a constant) in the continuous section,giving the integration algorithm an easier task.

Warning –state must bereproducible

It is not possible to ask the event finder to find an event introduced by anotherDISCRETE block. An event is defined as the zero crossing of a functiong(x) whichmust be reproducible;i.e., if g(xn) andg(xn+1) bracket a zero crossing, going back to

g(xn) must produce exactly the same answer as the first time. If the state changes insuch a way that it is not reproducible (something in the form of X=X+1, for example),the error messageEvent vanishedmay be generated.

To check whether the function is reproducible, get debug dumps by setting NDBUG tosome number at the region of the event (see Chapter 7). Look at the function value foreach debug dump when ZZFRFL (FiRst FLag) is TRUE, which occurs just once perintegration step.

Warning –memory

operators

The event finder also has a problem with the ACSL operators which have their owninternal memory (or state variables) when it is unable to back up and reproduce theprevious step before iterating to find the zero crossing. For example, the backlashoperator BCKLSH works by using the statement:

yl = MIN(MAX(yl, input - dl), input + dl)output = yl

Thus, OUTPUT is the previous value YL (Y last) unless INPUT exceeds YL by morethan the backlash value DL. Backing up may leave YL at the same value, so the zerocrossing finder may find the expression on the same side of zero after the single stepbackup, at which point it stops with the messageEvent vanished. The operators thathave internal state variables (potential sources of problems with SCHEDULE) are:

BCKLSH DBLINT DERIVT GAUSS IMPL LIMINT OU UNIF

Operators that are implemented as differential equations (such as REALPL, CMPXPL,and TRAN) have no problem. Algebraic operators (such as STEP and RTP), whichpass a signal directly with no memory, also work correctly. DELAY is configured sothat it works with SCHEDULE.



First order filter One workaround for these situations is to put the variable through a first order filterwith a fast enough time constant to act the same as a step so the event finder iterates onthe continuous (though steep) function. Such a high frequency pole can increasecomputer running time, however. Another approach is to write a routine to perform thesame function using integrators that can be handled by the zero crossing finder.

Warning –finding stopping

conditions

Be careful with trying to find a stopping condition at the boundary since theintegration algorithm must take a step thatcrossesthe boundary before recognizingthat an event has occurred. If you want to stop on impact with the ground, donotdothe following:

SCHEDULE .XN. heightTERMT(height .LE. 0)

The step that makes HEIGHT less than zero also sets the STOP flag so the run isterminated before it can back up and find the zero crossing. Instead use a DISCRETEsection; for example:

SCHEDULE stop .XN. height...ENDDISCRETE stop

TERMT(.TRUE., 'Stopped on zero height')END

Now the state event iteration takes the step to or just below the HEIGHT equal to zeroplane. Then the handler DISCRETE block is executed to set the STOP flag andterminate the run.

4.100 Separator (;)

FORM: statement ; statement

A semi-colon (;) separates any valid ACSL statements. Comments can be placed onlyafter the last statement on a line since everything after an exclamation point (!) isignored by the translator. An example using the separator is:

TERMT(t.GE.tstop) ; CONSTANT tstop=4.9 ! Stopping condition

4.101 SIGN

FORM: y = SIGN(x 1, x 2)

wherex1 andx2 are floating point constants, variables, or expressions. The outputy isthe sign ofx2 times the absolute value ofx1. SIGN could be used as follows:

z = k*SIGN(zbase, zsign)

Mathematical convention defines SGN as:

SGN(x) = + 1.0 ; x ≥ 0.0SGN(x) = − 1.0 ; x < 0.0

If you wish to achieve the following:

y = x*SGN(z)

4. ACSL Statements 4.100 Separator (;)


you can implement it with the SIGN function as follows:

y = x*SIGN(1.0, z)

Note that the result of SIGN(X, Z) is not the same as X*SIGN(1.0, Z).

4.102 SIN

FORM: y = SIN(x)

The output y is the sine of the floating point argumentx, which must be in radians; theresult is in the range (− 1.0 ≤ y ≤ + 1.0). The output and function type (REAL orDOUBLEPRECISION) depends on the type of the input. SIN could be used:

p = INTEG(y*SIN(w*t + fi), 0.0)

4.103 SMOOTH

FORM: smooth(y = 'datablock:argument')y = smooth('datablock:argument')

The argument inside the single quotes identifies the DATA block by name (in front ofthe colon) and which column of the data block to interpolate.

This operator interpolates between data points down a column of the given argument.The method used is due to Akima* and uses a third order polynomial to be placedthrough four bracketing points. The advantage of Akima's method is that smallchanges are localized and at abrupt discontinuities, the curve looks more like a manualfairing as opposed to a spline fit that tends to oscillate at discontinuities. As anexample, extractX as follows:

SMOOTH(x = 'foo:x')

or

x = SMOOTH('foo:x')

This looks up the value of the independent variable (in this case it has to beT, sincethis is a column of the data blockFOO), finds the data points that bracket this time,and then linearly interpolates to find the function value that is placed in the outputvariableX.

Example The simulation model in Figure 4-19 sweeps time from zero to ten and looks up thevalue ofX in two different ways, and the command file contains the DATA blockdefinition.

The result of running this simulation and the plot is shown in Figure 4-20. We haveoverlaid the data points using the /DATA=foo switch on the plot, showing that thepoints are marked with symbol number one (an octagon). The smoothed curve does agood job of fairing between time 5.0 when the plot is 8.0 and times 6.0, 7.0, etc. whenthe value of the function is identically equal to 2.0. No ringing is observed at thecorner.

4.103 SMOOTH 4. ACSL Statements


* Akima, Hiroshi, "A method of univariate interpolation that has the accuracy of a third-degree polynomial",ACMTransactions on Mathematical Software, Volume 17 Number 3, September 1991, pp. 341-366.

DERIVATIVECINTERVAL cint = 0.05CONSTANT tstp = 9.9! define 'y' so it can be specified as! argument (although unused) in data statementCONSTANT y = 0x = LINEAR('foo:x')xsmooth = SMOOTH('foo:x')TERMT(t.GE.tstp, 'Stop on time limit')END ! of derivative

(a) Model code

SET TITLE = 'Test of linear/smooth interpolation'PREPARE/ALLDATA foo(t, x, y)0.0 2.0 2.01.0 3.0 2.02.0 1.0 2.53.0 3.0 3.54.0 9.0 1.55.0 8.0 4.56.0 2.0 5.07.0 2.0 5.08.0 2.0 6.39.0 2.0 8.1ENDPROCEDURE p1PLOT x/WIDTH=3/CHAR=1/DATA=foo,xsmooth/STYLE=1END ! of procedure

(b) Command file

(c) Plot of LINEAR versus SMOOTH results

Figure 4-19. Testing LINEAR/SMOOTH interpolation

4. ACSL Statements 4.103 SMOOTH


4.104 SORT

FORM: SORT

The SORT keyword notifies the translator to sort all statements from the keyword tothe end of the section (INITIAL, DYNAMIC, DISCRETE, or TERMINAL). AllDERIVATIVE sections are sorted automatically.

This feature could be used for DISCRETE sections written under levels of ACSL at 9or below, when they were sorted automatically, or for INITIAL sections which havebeen built from a number of INCLUDE statements without regard to correct order.

4.105 SQRT

FORM: y = SQRT(x)y = SSQRT(x)y = FSQRT(x, lam)

The outputy is the square root ofx wherex is positive floating point variable orexpression. The type (REAL or DOUBLEPRECISION) of the output and functiondepend on the type of the input. A negative argument results in a exception trap onmost computer systems. An example using the SQRT function is:

miss = SQRT(xmt**2 + ymt**2 + zmt**2)

Alternativefunctions

Compilers on different systems handle situations such as negative arguments to thesquare root function differently. In order to catch and handle any errors gracefully,SSQRT (signed square root) and FSQRT (flow square root) functions have been addedto the library at Version 11.5. Both convert automatically to single or double precision.The functions are listed in Figures 4-20 and 4-21.

The signed square root function takes the square root of the absolute value of theinput, then gives the result the sign of the input. The flow square root functionswitches to laminar flow when the pressure drop equals the second argument.

function ssqrt(dlp)c-------------------signed square rootc won't abort when the input becomes negativec-@@--------------------------single/double

REAL dlp , ssqrtcc-------------------use signed root of absolute value

ssqrt = sign(sqrt(abs(dlp)), dlp)returnend

Figure 4-20. Signed Square Root Function (SSQRT)

4.105 SQRT 4. ACSL Statements


Some mathematical models are physically incorrect when the state of the systembrings the simulation to the point where it is taking the square root of a negativenumber. In this case, it should not only use SSQRT to avoid a numerical problem, butalso add a TERMT operator to stop the run and report the problem.

In some models, flows become zero and noise in the calculations can result in smallvalues on the negative side of zero. In these situations, the BOUND function wouldprobably be used to keep the variable from going negative.

4.106 STEP

FORM: y = STEP(tz)

The STEP function outputy changes from zero to one at a specified valuetzof theindependent variable. The result is

y = 0.0 ; T < tzy = 1.0 ; T ≥ tz

The step begins at the first integration step that equals or exceedstz. The effect of thefunction is diagrammed in Figure 4-22 with the default of time (T) as the independentvariable. An example of a statement using STEP is:

dle = 0.1*STEP(tz) + dlz

There is a potential conflict between the ACSL function STEP and a routine in theplotting package DISSPLA. We suggest either renaming STEP in the ACSL library(to, for example, STEPT) or replacing the statement in the model source code from:

function fsqrt(dlp, dlplam)c-------------------signed square root for flows. has switch toc laminar flow when the pressure drop equals the second argumentc the second argument may be zero so that there is no switchc to laminarcc-@@--------------------------single/double

REAL dlp , dlplam , absdlp , fsqrtcc-------------------take absolute value once

absdlp = abs(dlp)c-------------------if the absolute value below laminar thresholdc note cannot use equal since possible divide by zero

if(absdlp .lt. dlplam) thenc-------------------flow is linearly related to pressure drop

fsqrt = dlp/sqrt(dlplam)else

c-------------------use signed root of absolute valuefsqrt = sign(sqrt(absdlp), dlp)endifreturnend

Figure 4-21. Flow Square Root Function (FSQRT)

4. ACSL Statements 4.106 STEP


y = k*STEP(tz)

to the following, which is equivalent:

y = k*RSW(T .GE. tz, 1.0, 0.0)

4.107 TABLE

FORM: TABLE name, n, d /list/

where:

name= name of the function. The value is accessed byname(arg1),name(arg1, arg2), or name(arg1, arg2, arg3)for functions of one, two,or three variables, respectively. The arguments are of any arbitrarylevel of complexity.

n = an unsigned integer constant giving the number of independentvariables; this number must be 1, 2, or 3.

d = unsigned integer constants (may not be variable names); the number ofconstants must correspond to the value ofn. The values of the constantsgive the number of discrete data points for each successive independentvariable. A dimension of one is illegal.

list = floating point constants. The values of the independent variable arelisted first. The number of these points must equal the sum of thedimensions. Then the dependent values are listed with the fastestvarying argument first. The number of function data points must equalthe product of the dimensions.

The TABLE statement describes any arbitrary function of one, two, or three variables.A separate TABLE statement must be used to define each function.

Accessing aTABLE

TABLE statements must be defined before the table is referenced. The table isaccessed bynameand the independent variable; for example, if CLP has been definedas a table with one independent variable and MACH is a variable calculatedpreviously in the program:

cl = CLP(mach)

Figure 4-22. STEP Function

4.107 TABLE 4. ACSL Statements


Accessing as afunction

The table can also be accessed within a statement as with any function:

cd(1) = 0.5*CLP(mach)*b*wm(1)/mvm

More than onevariable

For a function of more than one variable, the independent variables are all listed in thecall, in the order given in the table:

cl = CLP(mach, al)

Breakpointsincrease

monotonically

All data points for the independent variables (breakpoints) must be of monotonicallyincreasing order;i.e., values may be identical but a breakpoint must never be less thana preceding value. Each TABLE statement may contain as many data points asdesired. Once the function has been defined, it may be referenced just like any otherACSL function.

Repeat counts Repeat counts may be used in the data specification (e.g., 5*6.7 results in 6.7 repeatedfive times). However, the breakpoints and data points are read into separate locationsby the translator and cannot be specified in the same repeat count. In the followingtables, the first statement is correct but the second results in a translator error message.

TABLE tab1, 1, 10 / 10*0.0, 10*0.0 /TABLE tab2, 1, 10 / 20*0.0 /...Bad break data count....

Examples Following are examples of tables of one, two, and three variables. The breakpoints are2 for F1ARG, 5 for F2ARG, and 9 for F3ARG and the number of data points are 2, 6,and 24, respectively. The first breakpoint appears first in the data.

TABLE F1ARG, 1, 2 / a 1, a 2, f 1, f 2 /

TABLE F2ARG, 2, 2 , 3 / a 1, a 2, b 1, b 2, b 3 &, f 11, f 21, f 12, f 22, f 13, f 23 /

TABLE F3ARG, 3, 2, 3, 4 &/ a 1, a 2, b 1, b 2, b 3, c 1, c 2, c 3, c 4 &, f 111, f 211, f 121, f 221, f 131, f 231 &, f 112, f 212, f 122, f 222, f 132, f 232 &, f 113, f 213, f 123, f 223, f 133, f 233 &, f 114, f 214, f 124, f 224, f 134, f 234 /

Linearextrapolation and

interpolation

If the calculated values of the independent variables lie outside the range specified bythe TABLE statement, the values for the function are obtained by extrapolatinglinearly from the last values given. Values between breakpoints in the table areinterpolated linearly.

Macro and arraydefined

The TABLE operator makes up a macro having the same name as the function so thatall references to the TABLE after its definition are caught. An array is also definedwith the same name and enough storage to contain both function data values and thecorresponding argument breakpoint values. This array name is entered into thedictionary and it may be accessed in by SET, DISPLAY, etc. runtime commands.

Order of dataentry

One point to note is the order of data entry into the array: The function data is listedfirst, then the breakpoint values follow. This order is the opposite from that listed inthe TABLE statement since it was considered that the more normal operation atruntime is changing function values rather than breakpoints. As an example, consider apitching moment table as a function of Mach number:

TABLE cm, 1, 5 / 0.0, 0.8, 1.2, 1.5, 2.5 &, 0.50, 0.51, 0.92, 0.83, 0.15 /

4. ACSL Statements 4.107 TABLE


This statement produces an array CM(10) in which the first five elements contain thefunction values 0.50, 0.51, 0.92, 0.83, 0.15 and elements six through ten contain thebreakpoint values 0.0, 0.8, 1.2, 1.5, 2.5. To change the function value at Mach 1.5, thefollowing runtime command can be used:

SET cm(4) = 0.65

To change the breakpoint from Mach 1.5 to Mach 1.6, the position in the table iscalculated (5 + 4) and the command becomes:

SET CM(9) = 1.6

Multidimensionaltables

For multidimensional tables, the function data is all listed in the array first, then thebreakpoint data in the order of first, second, third argument.

Function vs. array The function name followed by parentheses (cm(2.0), for example) on the right handside of an equal sign implies a call to look up the function value, while the tablefunction name without parentheses stands for the array thatcontainsthe function andbreakpoint values. The elements of the array cannot be accessed in the programbecause parentheses indicate a function call, but the array name can be passed to aFORTRAN subroutine (or function) to return the value of the array element. Forexample, to access the third element of array CM, returned in array value D, call:

CALL getav(cm, 3, d)

where the subroutine is defined at the end of the ACSL program:

SUBROUTINE getav(f, n, av)DIMENSION f(1)av = f(n)RETURNEND

Reading datainto array

Data can be read into a TABLE array, either by calling a subroutine within the modelor at runtime. Set up the table in the model, but fill the data by using a multiplier; forexample:

TABLE k, 1, 10 / 10*0.0, 10*0.0 /

or, if the breakpoints are known and only the data is to be filled in later:

TABLE k, 1, 10 &/ 0.0, 0.0, 0.2, 0.4, 0.5, 0.6, 0.8, 0.9, 1.0, 1.0 &, 10*0.0 /

Subroutine call Thus, to fill a TABLE from outside data, call a subroutine as follows:

CALL getk(k, 10)

The subroutine then is defined as follows:

SUBROUTINE getk(table, n)REAL table(1)DATA lu / 55 /OPEN(UNIT=lu, FILE='myfile')

C--------------read function valuesREAD(lu, 99) (table(j) , j = 1, n)

C--------------read breakpoint valuesREAD(lu, 99) (table(j) , j = n+1, 2*n)

CLOSE(lu)RETURN

99 FORMAT( < match file data > )END

4.107 TABLE 4. ACSL Statements


Placement ofsubroutine call

The fill subroutine must appearafter the definition of the function by the TABLEstatement. If the TABLE statement is specified and a variable with the same name hasalready been seen, this causes an error.

Since the data needs to be read in only once, the call can be put in the pre-INITIALsection, or else on a switch in the INITIAL section as follows:

LOGICAL firstCONSTANT first = .TRUE.IF(first) CALL getk(k, 10)first = .FALSE....

Runtime SET orACSL Math

At runtime, use a SET command, either interactively or defined in a command file tochange TABLE data. The order of the data at runtime is data first, then breakpoints.Another option is to generate the data in ACSL Math; when control is returned toACSL, the new values are read in automatically.

Warning –statement labels

We recommend that labels not be attached directly to statements containing referencesto table functions. When used in a program, the function referenced is translated intoan assignment to a dummy variable from the function look up subroutine; for example,for the statement:

q = 0.5*ro(h)*v**2

the translation becomes:

Z99999 = ZZF1(10, Z99998, RO, H)Q = 0.5*Z99999*V**2

where the first argument of ZZF1 (the 10) is the number of breakpoints, the secondargument is the current breakpoint interval, the third argument is the array name thatcontains the function value, and the fourth argument is the expression that is theoriginal argument.

If the original statement is labeled so that control can be transferred by other GO TOs;for example:

L1: q = 0.5*ro(h)*v**2

the label is still attached to the Q statement in the translated text and thus the Z99999assignment is bypassed unless control flows directly. Labels in general should beavoided and when used should be attached only to CONTINUE statements to preventthis flow problem (see Chapter 2 for more about labels).

4.108 TAN

FORM: y = TAN(x)

The outputy is the tangent of the real argumentx, which must be expressed in radians.The output and function type (REAL or DOUBLEPRECISION) depends on the typeof the input. TAN could be used as follows:

a = b + TAN(theta)

4. ACSL Statements 4.108 TAN


4.109 TERMINAL

FORM: TERMINAL...END

The TERMINAL keyword identifies the beginning of the block of code performed atthe end of each run. It must be paired with a matching END statement. Code in theTERMINAL section is not sorted automatically; however, you can specify sortingwith the SORT keyword.

In order to save calculating certain variables over and over again during the simulationrun, the calculations can be placed in the TERMINAL section and executed only at theend of the run. Radial miss distance is an example of this type of variable. The rangecomponents XMT, YMT, and ZMT are available throughout the flight, and radial missdistance is calculated from the equation:

miss = SQRT(xnt**2 + ymt**2 + zmt**2)

Placing this in the TERMINAL section saves the extra computer time to evaluate thisexpression every integration step or communication interval.

MultipleTERMINAL

sections

Any number of TERMINAL sections can be used within a program. They may appearin any other section (INITIAL, DYNAMIC, DERIVATIVE, and DISCRETE) exceptPROCEDURAL. This feature is particularly useful in conjunction with INCLUDEfiles and/or ACSL macros. Modules can be developed in separate files with their ownTERMINAL sections, then brought into a DERIVATIVE section in a larger programby means of INCLUDE statements.

The translator collects all the TERMINAL sections in the order given. This means thatcode introduced in DERIVATIVE or DISCRETE sections appears before code in theexplicit TERMINAL section. If the sections of code need to be in a particular order (sothat a variable is defined before being used, for example), use the SORT keyword.

Parametric runs One method of setting up parametric runs is to loop from the TERMINAL sectionback to the INITIAL section. See Chapter 8 for details of this procedure.

4.110 TERMT

FORM: TERMT(logical expression[, 'string'])

A run terminates when the logical expression in the TERMT statement becomesTRUE. Any number of termination conditions may be specified, and the firstcondition to become TRUE terminates the run. A minimum of one terminationcondition is required; usually a time limit is specified.

The 'string' argument is an option for printing out user information on thecondition that terminates the run. It is considered low volume data and so appears onthe screen as well as in the print file. It is useful to include this argument even whenthere is only one stopping condition since it confirms the run terminating normally.

All models must contain some specification for terminating the run; the TERMTstatement is the usual and best method of accomplishing this. In an explicit program,control transfers to the TERMINAL section and then to the runtime executive. In animplicit program, control goes to the executive directly.

4.110 TERMT 4. ACSL Statements


Example An example of a typical TERMT statement is:

TERMT((h .LE. 0.0) .OR. (v .LE. vmin) .OR. (T .GE. tmax))

or, to provide information at runtime on which condition actually terminated the run:

TERMT(h .LE. 0.0, 'Termination on hitting ground')TERMT(v .LE. vmin, 'Termination on flying backwards')TERMT(T .GE. tmax, 'Termination on TMAX time limit')

Placement inprogram

TERMT statements can be placed in any of the DYNAMIC, DERIVATIVE, orDISCRETE sections. A TERMT statement placed in the DYNAMIC section of anexplicit program stops the run at a communication interval. In a DERIVATIVEsection, it stops the run at the integration step following the logical expressionbecoming TRUE. In a DISCRETE section, the run stops at the execution following theexpression becoming TRUE.

With SCHEDULE In some cases, a DISCRETE section is executed solely to terminate the run when astate event is detected. For example, SCHEDULE finds the state event ofH (height)crossing zero, and a DISCRETE section contains the TERMT statement:

SCHEDULE stop .XN. h...

END ! of derivativeDISCRETE stop

TERMT(.TRUE., 'Termination on hitting ground')END ! of discrete stop

This procedure is useful for stopping runs at precise events (see, for example, thedescription of stopping missiles at intercept in Chapter 8).

Do not at the same time use an additional statement:

TERMT(h .LE. 0.0, 'Termination on hitting ground')

For the SCHEDULE operator to work,H must actually cross zero. However, if thestatement above is around, it sets the stop flag, thereby stopping the run beforeSCHEDULE has iterated to find the zero crossing. The result is that the run stops onthe other side of the zero crossing rather than precisely on it.

4.111 TRAN

FORM: y = TRAN(nn, nd, qn, qd, x)TRAN(y = nn, nd, qn, qd, x)

where:

nn = integer constant or PARAMETER name (may not be a variable name);the order of the numerator polynomial

nd = integer constant or PARAMETER name (may not be a variable name);the order of the denominator polynomial

qn = coefficient array for the numerator (can be an expression); may be areal constant ifnn is zero

qd = coefficient array for the denominator

x = input; an arithmetic expression of arbitrary complexity

4. ACSL Statements 4.111 TRAN


Transfer functions in the form of a ratio of polynomials in the Laplace operator,s, maybe directly implemented in ACSL by the transfer function simulation operator. Thesimple first order transfer functions REALPL and LEDLAG and second orderCMPXPL should be used when possible since the code generated is more efficientthan that for TRAN. TRAN is appropriate for higher order operators.

Order The transfer function polynomials are in the form of highest power ofscoefficientfirst and any missing order with its coefficient input as zero. Note thatnn+1 andnd+1numbers are required in the numerator and denominator arrays since it is the order thatis defined, not the number of coefficients.

Warning The order of the denomenator must be greater than or equal to that of the numerator. Ifthe order of the numerator and the order of the denominator are the same and there is afeedback path around the operator, anunsortable statement blockmay result.

macro tran(out,nn,nd,p,q,in)macro assign nmacro redefine i,z,zd,zicmacro relabel l1,l2macro multiply 0macro increment nnmacro 10: if(n=nd)20macro if(n=1000)999macro increment 1macro goto 10macro 20: continuearray z(nd),zd(nd),zic(nd)constant zic=nd*0.0procedural(zd=p,q,in)zd(1)=in-z(1)*q(2)macro if(nd=1)25do l1 i=2,ndzd(1)=zd(1)-z(i)*q(i+1)l1: zd(i)=z(i-1)macro 25: continuezd(1)=zd(1)/q(1)endmacro decrement nnmacro if(nn=nd)26procedural(out=p,z)macro if(nn=0)30out=p(1)*z(n)macro goto 27macro 26: continueprocedural(out=p,z,zd)out=p(1)*zd(1)macro 27: continuedo l2 i=1,nnl2: out=out+p(i+1)*z(i+n)macro goto 40macro 30: continueout=(p)*z(nd)macro 40: continueendz=intvc(zd,zic)macro exitmacro 999: print Numerator greater than denominator in TRANTRAN: out, nn, nd, p, q, inmacroend

Figure 4-22. TRAN operator macro

4.111 TRAN 4. ACSL Statements


Requirements All initial conditions are taken as zero, andnnandndmust be literal integer constantsor PARAMETER names, but not variable names. The order cannot be changedartificially by setting the highest power of the denominator polynomial to zero. QD(1)must be nonzero; otherwise division by zero results. Order can be changed byarranging for common factors in the numerator and denominator polynomials.

Example In the following example, note that thes1 term has to be filled in as a zero in the Q(denominator) array. Note also thatnnandnd must be entered as the numbersthemselves; variable names are not allowed. For the transfer function:

G(s) =3s + 2

s3 + 2 s2 + 5

the model code becomes:

DIMENSION p(2), q(4)CONSTANT p = 3.0, 2.0 , q = 1.0, 2.0, 0.0, 5.0out = TRAN(1, 3, p, q, in)

Arrays Variable names as well as literal constants can be used in the arrays. When thenumerator is a single value (zero order), it does not need to be declared in an array.Some way of calculating the value (constant, array element, assignment statement, orexpression) must be provided, however. For a transfer function in the following form,for example:

G(s) = K

s3 + 1

only one array is required and the code could be:

DIMENSION d(4)CONSTANT d = 1.0, 0.0, 0.0, 1.0z = TRAN(0, 3, k, d, 5*x + COS(th))

Macroimplementation

Figure 4-22 lists the mechanization of the TRAN operator as a system macro. Thislisting is an example of the complexities that can be implemented using macros.

Integration stepsize

When choosing the integration step size for the model, the reciprocal roots of thedenominator polynomial should be considered.

4.112 TRANZ

FORM: y = TRANZ(nn, nd, qn, qd, x)TRANZ(y = nn, nd, qn, qd, x)

where:

nn = integer constant or PARAMETER name (may not be a variable name);the order of the numerator polynomial

nd = integer constant or PARAMETER name (may not be a variable name);the order of the denominator polynomial

qn = coefficient array for the numerator (can be an expression or real constantif nn is zero)

qd = coefficient array for the denominator

x = input; an arithmetic expression of arbitrary complexity

4. ACSL Statements 4.112 TRANZ


Transfer functions in the form of a ratio of polynomials in Z-1 may be directlyimplemented in ACSL by the TRANZ operator.

Order The transfer function polynomials are in the form of highest power of Z-1 coefficientfirst and any missing order with its coefficient input as zero. Note thatnn+1 andnd+1numbers are required in the numerator and denominator arrays since it is the order thatis defined, not the number of coefficients. Usually the qd(1) element is unity (1.0).

In the following example, note:

G(z) =1 + 0.5z−1

1 − 0.166667z−1 − 0.166667z−2

for which the model code becomes:

DIMENSION pn(2), qn(3)CONSTANT pn = 1, 0.5CONSTANT qn = 1,-0.166667,-0.166667out = TRANZ(1, 2, pn, qn, in)

Coefficients If the number of coefficients in the numerator exceeds those in the denominator, makethe denominator order the same as the numerator and fill the trailing coefficients withzeros. When there are no denominator coefficients, use a denominator coefficientarray with unity in the first element (qn(1) = 1.0) and the remainder zeros; for example,

DIMENSION pn(4), qn(4)CONSTANT pn = 1, 2, 3, 4CONSTANT qn = 1, 0, 0 ,0out = TRANZ(3, 3, pn, qn, in)

matches:

outn = 1*inn + 2*inn+1 + 3*inn+2 + 4*inn+3

but this is probably better implemented using the HISTORY operator.

Complex filters For complex Z transform filters, a warning is in order concerning the accuracy of thecalculations. It is very easy to come up with a filter design that doesn't behavecorrectly and needs double precision in order to work. (See the method for selectingglobal double precision for the entire model in theACSL Sim User's Guide.)

The TRANZ statement must be placed inside a DISCRETE section.

4.113 Type

FORM: DIMENSION v1, v 2, ..., v n

REAL v1, v 2, ..., v n

DOUBLEPRECISION v1, v 2, ..., v n

INTEGER v1, v 2, ..., v n

LOGICAL v1, v 2, ..., v n

CHARACTER v1*n, v 2*n, ..., v n*n

where thevi are either simple variable names or else subscripted arrays with up to sixinteger constant subscripts separated by commas. The variables are typed and(optionally) dimensioned at the same time. Subscripts must be numerical or a symboldefined in a previous PARAMETER statement; variable names are not allowed.Examples of type statements include:

4.113 Type 4. ACSL Statements


INTEGER k, jj(10), fred(2, 2)LOGICAL flagCHARACTER mytitle*480REAL x(5,5), k1DOUBLEPRECISION vm(3), dot

FORTRANconvention

The Fortran convention that names starting with I, J, K, L, M, or N are integer doesnot hold. Variables are considered to be floating point, either single or doubleprecision depending on the translation mode, unless typed otherwise. Integer variablesmust be typed specifically.

LOGICAL LOGICAL variables can take on values of .TRUE. or .FALSE.

CHARACTER The length of CHARACTER variables defaults to 1 if not specified.

Floating point REAL or DOUBLEPRECISION should be used only to force a variable to single ordouble precision specifically since variables declared DOUBLEPRECISION arealwaysdouble and variables declared REAL arealwayssingle. DIMENSION isrecommended for specifying the dimensions of an array; the array then becomes singleor double precision depending on the translation mode.

System symbols System symbols such as T, CINT, MAXT, and MINT, and also states, derivatives, andinitial conditions, are changed automatically by the ACSL system; you cannot specifytheir type.

Duplicatespermitted

Duplicate declarations are permitted starting at Version 11.5. This is useful in graphicmodels when declared variables are output from ACSL blocks. The variables can bedeclared in all of the blocks that are wired together, rather than only in the block thatcomputes the variable. Declarations must match exactly, or a diagnostic is produced.

Arguments A potential problem with mixed single and double precision variables in a program isin their being passed as arguments to subroutines and being returned from functions.All the ACSL subroutines change type automatically, but if any other routines areused, provision must be made to force the appropriate type. For example, the DOTproduct function returns the dot product of two three-component vectors. A totalvelocity magnitude could be obtained by:

REAL vm(3)mvm = SQRT(DOT(vm,vm))

If DOT is written to accept double precision arguments and return a double precisionresult, then ACSL must type these appropriately rather than relying on automatictyping unless double precision mode isalwaysused:

DOUBLEPRECISION vm(3), DOTmvm = SQRT(DOT(vm, vm))

If DOT is single precision, the opposite must be specified;i.e.,

REAL vm(3), DOTmvm = SQRT(DOT(vm, vm)

The Fortran generic SQRT adjusts automatically to the type of its argument and result.

Literal constants Other problems occur when using literal constants as arguments to subroutines. Forexample, quantizing a signal to 0.1 increments could be written:

CONSTANT increment = 0.1out = QNTZR(increment, in)

Although it is not good programming practice since the value cannot be changed atruntime, some people put the increment value directly into the code:

4. ACSL Statements 4.113 Type


out = QNTZR(0.1, in)

If the double precision runtime library has been specified, the QNTZR subroutineexpects a double precision value for the increment and without modification wouldpick up extra undefined bits behind the 0.1 value. In order to solve this problem, theACSL translator adds a D0 to the end of each real constant;i.e., on the compile file,the line becomes:

OUT = QNTZR(0.1D0, IN)

and the function sees a true double precision quantity. If you really want a singleprecision quantity in this situation, you can use the REAL function to force it:

out = mysub(REAL(0.1D0), ...)

An alternative is to use an exponent form to force double precision:

out = mydoublesub(1.0D-1, ...)

Missile example An example of converting external subroutines is shown in the two versions of themissile simulation model (MISSGL.CSL and MISDBL.CSL) in Appendix A. In thesubroutines, two at-signs (@) mark that the following line (the input and output)should be changed from REAL to DOUBLEPRECISION or vice versa. For example,in the vector rotate subroutine VECROT, the argument definition line is:

SUBROUTINE VECROT(VIN, RMX, VOUT)C-@@--------------------------DOUBLE/SINGLE

DOUBLEPRECISION VIN(3), RMX(3,3), VNT(3)

This is followed by code to effect the transformation. ACSL changes the argumentsautomatically, so you must edit the subroutine o maintain compatibility.

LINPACK LUdecomposition

Another example of maintaining an external subroutine is the use of the doubleprecision LINPACK routine for factoring (i.e., LU decomposition) which is calledDGEFA. The calling sequence is:

CALL DGEFA(A, LDA, N, IPVT, INFO)

To use this, we would have to ensure that the matrix A is always double precision:

INTEGER ldaPARAMETER (lda = 10)DOUBLEPRECISION a(lda, ida)INTEGER ipvt(lda), infoCALL DGEFA(ipvt, info=a, lda, lda)

In general, it is better to use default types rather than forcing to single or doubleprecision via REAL or DOUBLEPRECISION statements.

Warning –errors not found

The translator cannot check the type of arguments to subroutines compiled separatelyfrom ACSL, or in general external library routines. It would be possible to have atemplate for all ACSL routines, but do so would reduce flexibility in redefining themeaning of the ACSL functions and subroutines. This is a common problem andcannot be overcome unless the compiler is given access to the subroutine and its call inthe same compilation run. Most compilers even then won't check matches acrosssubroutine boundaries. In the following example, the literal integer input argument isan error because the bit pattern for the integer 3 seen on the calling side will probablybe zero (exponent all zeros) when seen from the subroutine side as a real number.

4.113 Type 4. ACSL Statements


SUBROUTINE foo(ri, ro)REAL ri, ro...CALL foo(3, ro)

4.114 UNIF

FORM: y = UNIF(bb, tb)

The outputy is a random variable uniformly distributed between a bottom boundbband a top boundtb. UNIF could be used as follows:

drive = k*UNIF(dlo, dhi)

This operator is not intended for use in a DERIVATIVE section because the powerdensity (or, what is usually more important, the low frequency power) depends on theintegration step size. Variable step integration methods can produce peculiar results.See OU for details on generating noise in a DERIVATIVE section.

4.115 UNIFI

See GAUSI.

4.116 USEDBV

FORM: usedbv('datablock:variable')

USEDBV stands for Use Data Block Variable. When a model is connected to theACSL Math or ACSL Optimize, it is useful to be able to know what data blocks andwhat variables are used in a model so that they can be selected through a pull downmenu. Unfortunately, the presence of the LINEAR or SMOOTH function is notrecognized by the runtime system until the user has issued the first START command.It at this time that the derivative evaluation code is evaluated and DATA blocks arelooked for to satisfy any lines containing these LINEAR or SMOOTH functions.

So that the ACSL Optimize can tell what data blocks are needed prior to execution, wehave added the routine USEDBV (Use Data Block Variable) that can be placed in thepre-INITIAL section of the ACSL model. The pre-INITIAL code is executed once atthe very beginning of the simulation, before any runtime commands have beenexecuted (and only once per runtime session).

If the DATA block used in the model is unnamed, then the datablock name in theabove (part in front of the colon) can be eliminated. Reference to unnamed blocksrequires them to be specified as a switch to the start command (START/DATA=...).

Examples:

programusedbv('foo:x')usedbv('foo:y')initial...end...end

4. ACSL Statements 4.114 UNIF


This says that somewhere in the derivative evaluation code there is a statement of theform:

smooth(x = 'foo:x')linear(y = 'foo;y')

For the unnamed data block we might see:

programusedbv(':x')usedbv(':y')...

For models that are not used in conjunction with ACSL Optimize, this function can beignored.

4.117 VARIABLE

FORM: VARIABLE name [, ic name [= floating point constant]]

The default independent variable is called T. It has an initial value of 0.0 and the initialcondition name is not accessible. Using the VARIABLE statement allows you todesignate the independent variable with a nonsubscripted name; the initial conditionname is then also accessible. Thevaluefor the initial condition cannot be a name.

If the variable name T is to be used for temperature, for example, the independentvariable could be called TIME and be given a negative initial condition as follows:

VARIABLE time, timeic=-5.0

4.118 WRITE

See I/O.

4.119 XERROR

See MERROR.

4.119 XERROR 4. ACSL Statements


4. ACSL Statements 4.119 XERROR


5. ACSL Runtime Commands

5.1 Runtime executive

Runtime is the point at which the program has been translated, compiled, linked, andexecuted. It is waiting at the ACSL runtime prompt for your commands to exercise themodel. The commands are sequential. The order of execution is the order given, andalthough procedures can be called, no branching or looping commands are available.

Data values (i.e., names defined in the program by CONSTANT or TABLEstatements) may be set at runtime; once set, they remain the same until changed by asubsequent command or else recalculated by code in the program.

Control Control stays in the runtime executive until you issue a START or CONTINUEcommand; then control is released to the program and integration begins. Somemethod of terminating the run must be present in the model definition code; otherwisethe runtime executive never regains control. (See TERMT operator, Chapter 4.)

For typical command sequences used to exercise various types of models, see theexamples in Appendix A.

Runtimecommand file

Runtime commands can be entered into a file (default name model.CMD) and read inautomatically at the beginning of the runtime session (see theACSL Sim User'sGuide). We recommend command files for commands such as OUTPUT andPREPARE, for setting system symbols (for the plotting environment, for example),and for defining PROCEDUREs. In general, we recommend issuing executioncommands such as START interactively, either directly or by executing aPROCEDURE.

Names;quotation marks

Throughout the description of these runtime commands, symbols (variable names)imply the value stored in the location corresponding to the name. Strings in quotationmarks however stand for themselves; they are general character data and are usuallytitles, comments, or file names.

! & ; * ? The use of these characters at runtime is described under Comment (!), Continuation(&), Separator (;), and Wild cards (* and ?). The comment, continuation, and separatorare also available for use in program code (see Chapter 4).

Commands andswitches

Runtime statements begin with a command. Qualifying switches are introduced byslashes (/). Both commands and switches may be abbreviated to just enough charactersfor uniqueness (PL for PLOT, PRI for PRINT, PRE for PREPARE, PRO forPROCEDURE, for example). The exceptions are the single character D for DISPLAYand S for SET, since these are such frequently used commands. The requiredcharacters are shown in boldface in the command definitions. A command such as:

PLOT x /CHARACTER=1 /TYPE=102 /RUN=2

can be reduced to:

PL x /CH=1 /TY=102 /R=2

Although abbreviations save time in interactive sessions, we recommend spelling outthe commands and switches in command files to improve readability.


Data types Data must be given in the appropriate format;i.e., integer, real, logical, or character.An integer is a string of digits with no decimal point; a real number is a string of digitswith an optional decimal point and/or exponent; and a logical is.TRUE. or .FALSE.(with short forms of.T. and.F. ). Integers used for real variables are automaticallyfloated prior to use.

Data entered at runtime is converted to binary format before the type of the receivingdata is looked at. If double precision accuracy is needed, use a D exponent to signifyconversion to double precision immediately (2.56D3, for example). If E format is used(2.56E3), the number is converted to single precision and then, if it is to be set into adouble precision variable, this single precision quantity is extended with trailing zeros.

CHARACTER Character variables can contain any printable character, and case is maintained incharacter strings used for titles and plot tags. Character variables can be assigned withthe SET command by using a string delimited with single quotation marks:

SET charvar = 'This is a string'

To include a single quotation mark within a string, enter the quote twice:

SET charvar = 'This is ACSL''s possessive'

Symbolic data A symbol can be substituted for an expected data element; the program considers thedata element to be that contained in the symbol. The datatypeis that associated withthe symbol in the model definition. As an example, consider:

OUTPUT t, a, b /NCIOUT=i

The switch /NCIOUT expects an integer to define the number of communicationintervals between OUTPUTs. The current value in the symbol I is used to specify thisnumber. Since variables not typed INTEGER or LOGICAL are considered REAL, thesymbol I must have been typed explicitly in the model definition by:

INTEGER i

Arrays Arrays may have up to six dimensions and can be referenced at runtime by thesedimensions. For example, an array could be defined in the model:

DIMENSION vbody(3,5)

and an element accessed at runtime by:

DISPLAY vbody(2,4)

5.2 ACTION

FORM: ACTION /VARIABLE = <real-variable> &/VAL UE = <matching-variable> &/L OCATION = name

SWITCH: /C LEAR

Actions can be scheduled at specified values of the independent variable. Examples ofvariables you can control with the ACTION command are NDBUG (number of debugdumps), NCIOUT (number of communication intervals per output), and variablesdefined in the program by CONSTANT statements.

The ACTION command is issuedbeforethe START command that executes it. Theaction occurs at the first integration stepafter the time specified by /VARIABLE.

5. ACSL Runtime Commands 5.2 ACTION


Switches /VARIABLE specifies the value of the independent variable (usually time) at whichthe ACTION is to occur. /VALUE is the value to be placed into location/LOCATION. The type (INTEGER, REAL, DOUBLEPRECISION, or LOGICAL) ofthe value in /VALUE must match the type of the name in /LOCATION. /VARIABLEand /VALUE must precede the /LOCATION they refer to;i.e., /LOCATION must bethe last switch specified for a given action.

Order ACTION statements are cumulative. Each action scheduled is inserted into to a linkedlist of existing actions. It is not necessary to order the values of the independentvariables;i.e., you can command an earlier action after a later one. Each time/LOCATION is mentioned, an ACTION is set up using the then current values for/VARIABLE and /VALUE; thus, /VARIABLE and /VALUE need not be explicitlystated with each ACTION command if they do not change.

/CLEAR Since the ACTION statement is cumulative, repeated commands, rather thancorrectingprevious commands, simplyaddto them. To remove all accumulatedactions and start over, use:

ACTION /CLEAR

Variable namesfor data

As with all other commands, you can use a variable name where a data item isexpected and the contents of this variable are automatically substituted. The valueused, however, is the value at the time the ACTION statement isanalyzed, not that atthe time the ACTION isperformed(after the START).

Debug dumps The ACTION command can be used, for example, to produce debug printouts atvarious times during a run. This ability is particularly useful for debugging a programwhen something pathological occurs at a given time in the run. When the systemsymbol NDBUG is an integer greater than zero, the debug dump is written out andNDBUG is decremented by one. Issuing the following command before a STARTproduces five debug listings at time T=0.0 and two debug listings at T=1.0:

ACTION /VARIABLE=0.0 /VALUE=5 /LOCATION=ndbug/VARIABLE=1.0 /VALUE=2 /LOCATION=ndbug

ControllingOUTPUT rate

OUTPUT rates can be controlled by scheduling similar action on NCIOUT (thenumber of communication intervals per output), which has a default of integer one.Another example illustrates how /VARIABLE and /VALUE need not be explicitlystated if they do not change:

ACTION /VARIABLE=0.0 /VALUE=5 /LOCATION=ndbug/VALUE=2 /LOCATION=nciout &

/VARIABLE=1.0 /LOCATION=ndbug &/VALUE=10 /LOCATION=nciout

In this example, two actions each are scheduled at 0.0 and 1.0, and /VALUE of 2 is setinto both NCIOUT (at /VARIABLE=0.0) and NDBUG (at /VARIABLE=1.0).

Model constants Constants specified in program code can be controlled by the ACTION command. Forexample, if a CONSTANT named GAIN has been defined, it could be set as follows:

ACTION /VARIABLE=0.0 /VALUE=1.0 /LOCATION=gainACTION /VARIABLE=5.0 /VALUE=2.0 /LOCATION=gain &

/VARIABLE=10.0 /VALUE=4.3 /LOCATION=gain

However, using a variable in /LOCATION does not work if the variable is computedin a DERIVATIVE section.

Warning –don't change

IALG

The integration routine allocates table space to handle the specified algorithm before arun begins. After once determining IALG for a run, ACSL never looks again to see ifit has changed. Trying to change the algorithm with ACTION has no effect.

5.2 ACTION 5. ACSL Runtime Commands


5.3 ANALYZE

FORM: ANALYZE

SWITCHES: /BODE/CL EAR/E IGEN/INV NYQ/J ACOBIAN [= 'filename']/NIC HOLS/NYQUIST/ROOTLOCUS/S TATUS/T RIM/Z EROS

LISTS: /CO NTROL = name, ..., name/FREEZE = name, ..., name/OBSERVE = name, ..., name/REL EASE = name, ..., name

QUALIFIERS: /CI NDEX = <integer-variable> [1]/DEGREE = <logical-variable> [.TRUE.]/DEL AY = <real-variable> [0.0]/DI SPLAY = <logical-variable> [.FALSE.]/FL OGSC = <logical-variable> [.TRUE.]/FRACDL = <real-variable> [1.0]/FRACPM = <real-variable> [1.0]/FREQMN = <real-variable> [1.0]/FREQMX = <real-variable> [1000.0]/GAIND B = <logical-variable> [.TRUE.]/GAINMN = <real-variable> [RMX]/GAINMX = <real-variable> [RMX]/GL OGSC = <logical-variable> [.TRUE.]/H ERTZ = <logical-variable> [.TRUE.]/IMAGMN = <real-variable> [RMX]/IMAGMX = <real-variable> [RMX]/INC = <real-variable>/L IST = <logical-variable> [.FALSE.]/MI NC = <real-variable> [0.0001]/MUMAX = <integer-variable> [2000]/NIT RMX = <integer-variable> [50]/OI NDEX = <integer-variable> [1]/PHASMN = <real-variable> [RMX]/PHASMX = <real-variable> [RMX]/REALMN = <real-variable> [RMX]/REALMX = <real-variable> [RMX]/RMSEMX = <real-variable> [0.0001]/V ECTORS = <logical-variable> [.FALSE.]/X INC = <real-variable> [0.0001]

The ANALYZE command invokes a linear analysis capability to evaluate theJacobian, trim the state variables to null the rates, calculate eigenvalues and theirassociated eigenvectors, and generate frequency response analysis and plots.

Executing an ANALYZE command before a START causes the initial conditionvector to be copied to the state vector, and the following informational message isproduced:

States not initialized. Moving IC vector to state vector.

5. ACSL Runtime Commands 5.3 ANALYZE


This initialization procedure however does not execute code in the INITIAL section. Ifany initial conditions are calculated in the INITIAL section, execute the model at timezero before using the ANALYZE commands as follows:

SET tstop=0.0 ! or equivalent termination conditionSTARTANALYZE ...

The various switches, lists, and qualifiers are explained in the sections below. The lastsection contains examples and further discusses use of the ANALYZE command.

5.3.1 ANALYZE lists

Switches are used to set up control variables and observables and to freeze and releasestates. The lists associated with these switches are cleared with ANALYZE /CLEAR./MINC, /XINC, and /INC control perturbation of the control variables. These topicsare discussed in the following sections.

5.3.1.1 ANALYZE/CONTROL/OBSERVE

Switches /CONTROL and /OBSERVE define lists of controls and observables;e.g.:

ANALYZE /OBSERVE=y1,y2 /CONTROL=u1,u2,u3ANALYZE /JACOBIAN

The /JACOBIAN following the /OBSERVE and /CONTROL lists the A, B, C, Dmatrices in turn from the state space model formulated as:

X.

= [A] X + [B] UY = [C] X + [D] U

Matrixdimensions

The matrix dimensions for the above example, assuming N state variables, are: [A], Nby N; [B], N by 3 (controls); [C], 2 (observables) by N; and [D], 2 by 3.

Restrictions oncontrols

There are normally no restrictions on the observables, but the controls must not becalculated (i.e., they must be defined in CONSTANT statements). This is because thestate variable and control variable lists are joined together and then each is perturbedin the positive then negative direction, calculating a column in the combined matrix:

AC

BD

In most models, control variables are calculated quantities since potential controllersare built into the model, so terms are in the form:

U1 = G1(s)∗EP1U2 = G2(s)∗EP2

For the linearized model, extra variables are required so they can be adjusted. Thecode should be written in the form:

CONSTANT kc1=1.0, uz1=0.0u1 = kc1*G(S)*EP1 + uz1

5.3 ANALYZE 5. ACSL Runtime Commands


where the perturbation term UZ1 is a constant zero and is added on to the output of thecontroller. For ANALYZE to obtain the open loop state matrix, first set KC1=0.0;i.e.,

SET kc1 = 0.0ANALYZE /CONTROL=uz1 /JACOBIAN

Error messages If an attempt is made to include a nonconstant (calculated) variable to the /CONTROLlist, the following error message is produced when the matrices are calculated:

...Independent variable changed in Jacobian evaluation

...State changed in Jacobian evaluation

If the feedback path has a nonzero value, then setting KC1 to zero makes the controlzero and possibly disturbs the operating point. The constant value UZ1 can be adjustedto keep the control value constant so that U1 keeps its value;i.e.,

SET uz1=u1, kc1 = 0

Other error messages may be produced when the Jacobian is evaluated. They includemessages relating to nonlinearity (a warning that the slope obtained by a positiveperturbation is different from that obtained by a negative perturbation) andrepeatability (which implies that the derivative evaluation routine is not a purefunction since one of the results is not repeatable with identical state values). SeeChapter 7 for a discussion of these messages.

Row and columndesignation

Error messages stating row and column numbers refer to the combined matrix and socan be outside the limits of the simple Jacobian. For example, consider a model withfive states, two observables (Y1, Y2), and three controls (U1, U2, U3). The actualmatrix being evaluated:

AC

BD

has seven (5+2) rows and eight (5+3) columns. A message referring to row sixindicates the first observable (Y1), and column seven indicates the second control(U2). Use the ANALYZE /JACOBIAN command to get a listing of the rows,columns, and matrix elements.

5.3.1.2 ANALYZE/FREEZE/RELEASE

/FREEZE The /FREEZE switch eliminates the listed variables from the state vector; its purposeis to eliminate open loop integrators before initiating the trim operation. Open loopintegrators are those states which have no effect on themselves or on other states or onwhich other states have no effect.

An example of a state having no effect is a horizontal distance, obtained by integratinghorizontal velocity in an airplane simulation. Vertical motion affects density, which inturn affects all forces and moments, but horizontal position is not usually usedanywhere in the model (unless position is important, for example in a landing controlsystem model). Variables of this type produce a zero column in the Jacobian.

State variables which are not affected by other states usually have a derivative that is aconstant or a function of only the independent variable. These are sometimes used asforcing functions;e.g.,

force = INTEG(F(t), 0.0)



Since no other states affect the state, this produces a zero row in the Jacobian. If theJacobian contains either a zero row or a zero column, its inverse does not exist.

Once frozen, variables stay frozen until you reset them with ANALYZE /CLEAR.

/RELEASE The /RELEASE switch is the complement of /FREEZE. The unfreezing or RELEASEof a small number of states shortens the list when the user wants to study a smallsubsystem embedded in a much larger model. The switch is not often used by itself.

/CLEAR with/RELEASE

/CLEAR is equivalent to freezing all the states, but this applies only to the rest of theline following the /CLEAR. If the ANALYZE command starts operating and finds allstates frozen (or no states active), then it automatically releases all the states. Torelease a few states, use:

ANALYZE /CLEAR /RELEASE=x,y,z

rather than:

ANALYZE /CLEARANALYZE /RELEASE=x,y,z

which does not work since all states are automatically released at the beginning of thesecond ANALYZE.

5.3.1.3 ANALYZE/CLEAR

The ANALYZE lists are cumulative. In order to remove all previous lists and startover, use the /CLEAR switch; for example:

ANALYZE /CLEAR /OBSERVE=y1,y4

The /CLEAR switch resets only lists of variables affected by /FREEZE, /CONTROL,and /OBSERVE (i.e., states and derivatives), not processing flags such as /LIST=.T.,etc. It also does not reset variables such as /MINC or /NITRMX to their defaults.

The /CLEAR switch can be included within the ANALYZE command line; it executesin sequence according to a left-to-right scan of the line.

5.3.1.4 ANALYZE/MINC/XINC/INC

These three switches control perturbation of the /CONTROL variables. /MINC is thefractional perturbation, /XINC is the absolute perturbation, and /INC overrides /MINCand /XINC by specifying an actual increment for perturbation of the immediatelypreceding /CONTROL variable. /MINC and /XINC apply to all /CONTROL variablesfollowing their specification.

Perturbation of the state variables is taken to be the allowable error, as calculated bythe current values of MERROR and XERROR.An example using these switches is:

ANALYZE /XINC=1.0E-6 /CONTROL=u1,u2 /INC=0.01

Perturbation is calculated (and saved away) at the ANALYZE command that sees the/CONTROL switch. In order to change the perturbation, the /CONTROL list must becancelled by /CLEAR. /CLEAR should be on a line by itself.



ANALYZE /CLEARANALYZE /XINC=1.0E-7 /CONTROL=u1 /INC=0.001, u2/INC=0.01

The actual perturbation used is the maximum of /MINC and /XINC unless overriddenby /INC. The algorithm, which obtains a value even if the control variable is zero, canbe expressed:

∆ Uj = MAX ( XINCj, MINCj |Uj | )

where∆ Uj is the perturbation applied to the jth control variableUj.

5.3.2 ANALYZE/JACOBIAN

/JACOBIAN calculates the Jacobian about the current point in state space bynumerical perturbation. The result is then printed out as a large matrix as shown inFigure 5-1 where the rows are states and the columns are derivatives. This isconventionally known as the A matrix.

If CONTROL or OBSERVE has been used to define lists of control or observablevariables, respectively, then the elements of the B, C, and D matrices are calculatedand displayed along with the A matrix by /JACOBIAN.

In order to simplify transfer of the state description to auxiliary programs, it can bewritten to a file by specifying a file name in quotes as follows:

ANALYZE /JACOBIAN='myfile'

The file is binary. For an ASCII file, we suggest editing the runtime log file (.log).

5.3.3 ANALYZE/EIGEN/VECTORS

/EIGEN calculates the Jacobian and then evaluates and lists the complex eigenvaluesand optionally the eigenvectors.

/VECTORS determines whether eigenvectors are to be calculated; so, if used, itshould precede /EIGEN. Once set, /VECTORS stays the same until explicitlychanged. These switches could be used as follows, with results as shown in Figure 5-1:

ANALYZE /JACOBIAN /VECTORS=.T. /EIGEN

5.3.4 ANALYZE/TRIM/MUMAX/FRACDL/FRACPM/RMSEMX/NITRMX

/TRIM /TRIM transfers the initial conditions to the state variables, computes the Jacobian,and then, using a combination of Newton-Raphson and steepest descent steps, adjuststhe state variables until the derivatives go to zero.



If control and observable variables are specified, then /TRIM adjusts the combinedstate and control vector to drive the combined derivative and observable vector tozero. The requirement is that there be the same number of adjustable variables asvariables to be driven to zero. Since there is always an identical number of (unfrozen)derivatives and states, this means that the number of controls and observables mustalso be equal.

/MUMAX, /FRACPM, /RMSEMX, /NITRMX, /FRACDL, and /LIST should be set,if desired,beforeinvoking /TRIM; each of these switches, once set, remains the samefor any subsequent calls to /TRIM until explicitly changed.

The trim or steady state finder computes the Jacobian matrix [A] and then a Newtonstep and the steepest descent step by:

∆ XNT = [ A ]−1 εX Newton

∆ XSD = [ A ] T εX steepest descent

and then uses a parameterµ to choose between the two:

∆ X = ∆ XNT ∗ 2−µ + ∆ XSD∗ µ ∗ 2−µ

If the step fails,µ is incremented; if the step succeeds,µ is decremented with a floor ofzero. Whenµ is zero, the step is a pure Newton step. Whenµ rises to four, a newJacobian is evaluated. Asµ rises, the step becomes smaller and is biassed increasinglytowards the steepest descent step; improvement is guaranteed in this direction if theJacobian is correct.

/MUMAX /MUMAX stops the indefinite increase in the value ofµ which will force very smallsteps. Setting MUMAX to zero ensures that every step is a Newton step. Whenµequals MUMAX, Jacobians are evaluated repeatedly, however, not just whenµexceeds four.

/FRACDL /FRACDL is an arbitrary multiplier (of value between 0.0 and 1.0) on the calculatedstep length. The default of one (1.0) can be changed to a smaller number on the basisthat one of the usual problems with convergence is that too large a step moves thecalculation into a different region even though the direction is inherently correct. Ifdifficulty with convergence is encountered, try /FRACDL = 0.5 and /FRACDL = 0.1;

Row vector namesTH 1 THD 2

Column vector namesZ09997 1 Z09998 2

Matrix elements - rows across, columns down1 2

1 0. 1.00000002 -8.6975100 -0.0286102

Complex eigenvalues in ascending orderREAL IMAGINARY FREQUENCY DAMPING

1 -0.01430510 +/-2.94912000 2.949150 0.004851

Complex eigenvectors1 2

1 0.3211180 0.0015576 0.3211180-0.00155762 0. -0.9470380 0. 0.9470380

Figure 5-1. ANALYZE /JACOBIAN /VECTORS=.TRUE. /EIGEN



keep in mind, however, that the convergence rate will be affected and morecomputation time required.

Iteration failure is reported when all of the steps are below /FRACPM of the allowablestate error and the system is considered to be at a local minimum. Convergencesuccess is reported when the weighted sum of squares becomes less than /RMSEMX.

/FRACPM /FRACPM multiplies the minimum step for each state in order to determine when theiteration should terminate. Normally, when each step is less than the allowable stateerror (determined by XERROR and MERROR values), then the iteration terminatessince the assumption is that the system is caught in a local minimum where not all thederivatives have been driven to zero. Sometimes this is too loose a criterion and can betightened to force the iteration onward by using the /FRACPM qualifier;e.g.,

ANALYZE /FRACPM=0.01 /TRIM

where the iteration will stop only when each state step is less than one hundredth ofthe state allowable error value.

/FRACPM can be set to zero to remove this stopping condition so that iteration willterminate only on /RMSEMX or on the maximum number of iterations /NITRMX.

/RMSEMX /RMSEMX specifies the allowable error at which trim convergence is obtained. Eachstate is associated with an allowable errordXj in the usual fashion by:

dXj = MAX ( XEj, MEj∗| Xj | )

whereXEj andMEj are the absolute and relative errors specified for the particularstate. This quantity is used in the Jacobian calculation as from:

X.i = Fi ( X1, X2, ..., Xj, ⟨ )

∂ (Fi)∂ (Xj)

=Fi ( ..., Xj + dXj, ⟨ ) − Fi ( ..., Xj − dXj, ⟨ )

2 dXj

During trim, the weighted residual R is computed from:

R =√∑j =1

N

X.j

dXj

2

∑j =1

N

1dXj

2

We are trying to drive the derivatives to zero, and this quantity R serves to measure ina weighted RMS sense. However, it does have the units of reciprocal time and so canbe influenced by time unit changes (seconds to hours to days to fortnights, etc.).Change the value of /RMSEMX to a smaller value if the derivatives at convergenceare not small enough (see /FRACPM for keeping the iteration going if it terminatesprematurely, which may mean it thinks the iteration is caught in a local bowl).

/NITRMX /NITRMX specifies the maximum number of iterations before the trim or steady statefinder gives up.

At each step, the Jacobian is modified using the Broyden update method to attempt totrack changes due to nonlinearities along the iteration trajectory.



Initial conditions Remember that /TRIM uses the initial condition values as its starting point for findingthe steady state. For a nonlinear system, judicious choice of initial condition valuesmay be necessary before a steady state can be achieved. It may be necessary toSTART the simulation with a time limit of zero before using the /TRIM switch if anyinitial conditions are computed in the model INITIAL section. Letting the system runfor a short time can bring high frequency components to steady state and cansometimes help the steady state finder. Use REINIT to transfer states to initialconditions prior to using /TRIM.

5.3.5 ANALYZEFrequency response

This section describes the frequency response analysis in general, and the followingsections describe the switches and parameter settings in more detail. System symbolsthat affect the frequency response analysis have names ending in the three charactersFPL and are described in Appendix C.

Frequency response plots are produced by the following commands:

ANALYZE /B ODE BodeANALYZE /INV NYQ Inverse NyquistANALYZE /NIC HOLS NicholsANALYZE /NYQUIST Nyquist

The commands may be issued separately or all on one line. When the command is allon one line, there is no pause between the plots.

The data for these plots is all obtained as a result of a frequency sweep, calculating thephase and gain as a complex number(Gcosθ, Gsinθ) from a given control input(CINDEX) to an observable (OINDEX).

The nonlinear simulation model is defined functionally by:

x.

= f (x, u)y = g (x, u)

which is linearized to:

x.

= Ax + Buy = Cx + Du

and the transfer function from control to observable becomes:

yu

= C ( sI − A )−1 B + D

If y andu are scalars, C is a row vector, B is a column vector, D is a scalar, and I is theidentity matrix, then the expression can be factored into:

yu

= K

∏i =1

m

(s − zi )

∏i =1

n

(s − pi )



where thepi are the eigenvalues of A (poles) and thezi are the zeros. The zeros can beprinted out separately by using the /ZEROS switch;i.e.,

ANALYZE /ZEROS

This lists the finite zeros in order except that zeros corresponding to poles areconsidered cancelable (see system symbol EPDFPL) and are listed separately.

Once the transfer function is expressed as a ratio of a product of zeros over a productof poles, the frequency response can be obtained by sweeping frequency (s = 0, jω)over a given range. The range is set by /FREQMN and /FREQMX, which should bedefined before (i.e., first in a left-to-right scan) the plot drawing verb (e.g., /BODE).

ANALYZE /FREQMN=1 /FREQMX=1000 /BODE

Units The units interpretation of the frequencies defined is modified by the /HERTZ switch,which may be set TRUE or FALSE to specify frequencies in Hertz or radians/secondrespectively; for example,

ANALYZE /HERTZ=.T. /FREQMN=10 /FREQMX=1.0E4ANALYZE /BODE

sweeps from 10 to 10,000 Hz, obtaining the phase and gain of the transfer functionalong the way; the following command keeps the same frequency end points butinterprets them as 10 to 10,000 radians/second.

ANALYZE /HERTZ=.F. /BODE

Frequency sweep During the frequency sweep from FREQMN to FREQMX, the frequency at any pointis multiplied by a number between DWNFPL and DWXFPL. If the phase changebetween the two frequencies is greater than DFXFPL, then the multiplier is changedby multiplying the part greater than one by a half and limiting the result to be nosmaller than DWNFPL;i.e.,

DWN = MAX(DWNFPL, 0.5*(DWN - 1) + 1)

and recalculating the frequency point. If the phase change is acceptable, it is thentested for being less than one quarter of DFXFPL. If it is, then the fractional part of themultiplier greater than one is doubled, with a limit of DWXFPL;i.e.,

DWN = MIN(DWXFPL, 2.0*(DWN - 1) + 1)

Restriction onsweep

The value of DWXFPL must be greater than that for DWNFPL, and both must begreater than 1.0.

Accumulatingdata

At each point in the frequency sweep, frequency, gain, and phase are saved for lateruse in the plotted outputs (Bode, Nyquist, etc.). The last frequency point is limited toFREQMX irrespective of the last multiplier in use.

5.3.5.1 ANALYZE/BODE

Bode plots are produced by plotting phase and gain as separate curves againstfrequency as the frequency is swept from the specified FREQMN to FREQMX. Seethe section above for details on the frequency sweep.

Qualifiers affecting the plot are as follows: GAINMN and GAINMX force the scalefor the gain axis, and the numeric interpretation is governed by the GAINDB logicalvalue: if TRUE, the gain is in dB; if FALSE, it is a numeric ratio. PHASMN andPHASMX force the scales on the phase axis, and the numeric interpretation is



governed by the DEGREE logical value: if TRUE, the plot is in degrees; if FALSE, inradians. FLOGSC sets a logical flag to control whether the gain axis is logarithmic(TRUE) or linear (FALSE). If GAINDB is TRUE, GLOGSC has no effect and thescale is automatically linear. The defaults are gain in dB (linear scales), frequency inHz (logarithmic scales), and phase in degrees.

Since two curves are drawn in Bode plots, you have the option of drawing them eitherboth together in the same plot area or separately. This option is controlled by thesetting of the system variable DTCFPL (draw two curves). If TRUE, the Y axis lengthis halved and rounded down to a whole number, and two curves are drawn in strip plotformat. For the default Y axis length YINFPL of 5.0 inches, this results in two 2x5plots, with gain plotted above phase.

If the two curves are drawn on the same plot, line type (style, width, and color) iscontrolled by FLTFPL (first line type) and SLTFPL (second line type).

5.3.5.2 ANALYZE/INVNYQ

Inverse Nyquist plots are obtained in a manner similar to normal Nyquist plots(described under /NYQUIST), with the exception that the points plotted correspond tothe reciprocal of the complex gain;i.e.,

Nyquist G cosθ against GsinθInverse Nyquist cosθ ⁄ G against sin(−θ) ⁄ G

for different values of the frequency. Plot scale bounds and frequency tick marks arecontrolled in the same manner as for Nyquist plots.

5.3.5.3 ANALYZE/NICHOLS

Nichols plots are gain plotted against phase. Conventional Nichols diagrams usuallyhave fixed scales, but in ACSL these plots are sized as usual to the data range orforced via GAINMN, GAINMX, PHASMN, and PHASMX. Frequency is indicatedby tick marks on the side of the curve at every decade (large tick and printed power often) and smaller ticks at integer values in between;i.e., 1, 2, 3, ... 9.

5.3.5.4 ANALYZE/NYQUIST

Nyquist plots are phase and gain plotted as points on the complex plane as thefrequency is swept from FREQMN to FREQMX. Scales for the real and imaginaryaxes are chosen automatically unless specified directly by REALMN, REALMX,IMAGMN, and IMAGMX. Frequency is indicated by tick marks on the side of thecurve at every decade (large tick and printed power of ten) and smaller ticks at integervalues in between;i.e., 1, 2, 3, ... 9.

Placing the exponent symbols and handling the spacing of the tick marks can becomeproblematical. The exponent symbols can be removed altogether with the systemsymbol NESFPL (no exponent symbol) set TRUE. An alternative is to control thewindow within which exponents are written by EMNFPL (exponent minimum) andEMXFPL (exponent maximum). Once one decade tick is established, then the othersare reasonably easy to count. If the ticks crowd too close together, then the tick marks



are suppressed and you will have to magnify the region with REALMN, REALMX,IMAGMN, and IMAGMX for the ticks to appear again.

5.3.5.5 ANALYZEFrequency analysisqualifiers

This section describes (in alphabetical order) the ANALYZE qualifiers that setnumeric values for later use by the verb switches. The input may be a number or avariable of the type indicated;i.e., floating point, INTEGER, or LOGICAL.

Some default values are listed as RMX. RMX is a large machine-dependent number(1.0E+38 on 32-bit computer systems, for example) used as a flag to triggerautoscaling. It is generally preferable to use zero for a flag, but unfortunately, foritems such as axis maxima and minima and phase and gain, zero is a perfectly legalvalue and thus cannot be used as a flag.

/CINDEX Specifies the control variable for the single input/single output transfer function fromthe list of control variables (specified in the /CONTROL switch). The default of 1selects the first variable on the list.

/DEGREE Specifies the units for phase values: TRUE for degrees; FALSE, radians.

/DELAY Specifies the value of loop delay to be added into the transfer function expression. Anapproximation for a discrete controller delay is half the sample time plus the full valueof the compute time delay or time between ADC input to the next DAC output.

/FLOGSC Specifies whether the frequency axis of a frequency plot is scaled logarithmically(TRUE) or linearly (FALSE).

/FREQMN/FREQMX

Specify the minimum and maximum values through which the frequency is swept.FREQMN can't be zero because (1) it is used as a multiplier for the next frequencyand (2) we must be able to take the logarithm of the number. The units of the numbers(Hertz or radians/second) are determined by the current setting of HERTZ when theaction using the frequency takes place.

/GAINDB Specifies whether the gain axis scale is in dB (TRUE) or a ratio (FALSE). If FALSE,it is recommended to use GLOGSC (logarithmic scales) for the gain axis. GAINDBcontrols the interpretation of the units of the GAINMN and GAINMX axis settings.

/GAINMN/GAINMX

Specify the minimum and maximum values on the gain axis, forcing the plot scales.The default is a machine-dependent large number that implies scales calculated bynormal rounding of the calculated minimum and maximum gain during the frequencysweep. The units depend on the setting of GAINDB at the time the plot command isentered.

/GLOGSC Specifies whether the gain axis of a Bode or Nichols plot is scaled logarithmically(TRUE) or linearly (FALSE). If GAINDB is TRUE, GLOGSC has no effect and thescale is automatically linear (in deciBels).

/HERTZ Specifies the units of the frequency range and the display of the frequency axisvariable on Bode plots and the frequency ticks on Nichols, Nyquist, and inverseNyquist plots. The units are Hz (TRUE) or rad/sec (FALSE).

/IMAGMN/IMAGMX

With REALMN and REALMX specify the view window onto the complex plane. Theunits are reciprocal time units. The default value is a machine-dependent large numberthat implies scales calculated by normal rounding to define an area which contains allthe poles (root locus) or real/imaginary range (Nyquist and inverse Nyquist).



/OINDEX Specifies the observable variable for the single input/single output transfer functionfrom the list of observables (specified with the /OBSERVE switch). The default of 1selects the first variable on the list.

/PHASMN/PHASMX

Specify the minimum and maximum values on the phase axis, forcing the plot scales.The default value is a machine-dependent large number that implies scales calculatedby normal rounding of the calculated minimum and maximum phase during thefrequency sweep. Units (degrees or radians) depend on the setting of /DEGREE at thetime the plot command is entered.

/REALMN/REALMX

Together with IMAGMN and IMAGMX specify the view window onto the complexplane. The units are reciprocal time units. The default is a machine-dependent largenumber that implies scales calculated by normal rounding to define an area thatcontains all the poles (root locus) or real/imaginary range (Nyquist, inverse Nyquist).

5.3.6 ANALYZE/ROOTLOCUS

The root locus plot follows the roots of the linear system as they vary with changinggain fed back from the observable output to the control input. If G(s) corresponds tothe transfer function from input to output and is expressed as a product of zeros over aproduct of poles, then the closed loop system has a transfer function of:

G(s)1 + KG(s)

The root locus follows the roots of this or the zeros of 1+KG(s) as K is varied. Theregion of the complex plane is determined by REALMN, REALMX, IMAGMN, andIMAGMX. Locus tracks start at any poles within the region or at the edges of theregion for incoming tracks (going towards a zero).

Controls System symbols control details of the root locus tracker. At each step along a locus, aniteration is performed to minimize the phase angle to below EPFFPL (epsilon phase).Once this iteration has converged, a check is made by going sideways to left and rightby a distance tolerance measure EPDFPL (epsilon distance) to make sure the phasecrosses zero in between. If not, the iteration continues, so at step exit, the reportedpoint is within the distance tolerance of the exact locus.

The default settings for SSXFPL, SSNFPL, and EPDFPL are all zero to indicate thatthe system should take a reasonable default. For the step size maximum (SSXFPL),this is taken to be 5% of the diagonal distance across the plot; for the step sizeminimum (SSNFPL), it is 0.4% of the maximum step size (1/250); and the distancetolerance (EPDFPL) is a tenth of the minimum step size.

In order to find incoming loci, each edge is searched by dividing it up into NEDFPL(number of edge division) parts, where a phase zero crossing is tested. If the phasecrosses zero between two points, the point is refined by iteration.

During plotting of the curve, tick height is controlled by TKHFPL, exponent minimumby EMNFPL, and exponent maximum by EMXFPL.

With /LIST If the LIST flag is TRUE (specifying output of internal details), the complex point,gain, and step size are listed at each step. This data is considered high volume, so itappears only on the PRN until unless HVDPRN or ANALYZE/DISLPLAY are setTRUE to direct high volume data to the screen as well.



If the list is requested, HVDPRN or ANALYZE/DISPLAY is TRUE, and the plot isdrawn on the screen, the printed output overwrites the plot. If switching HVDPRN,DISPLAY, and/or the list off doesn't solve the problem, probably error messages arebeing written to the screen. Direct the plot to a hardcopy device or file until the errorshave been diagnosed and fixed.

5.3.7 ANALYZE/ZEROS

/ZEROS calculates the poles (eigenvalues) and finite zeros and attempts to cancelusing as a cancellation radius the current value in system symbol EPDFPL. This actionis invoked by:

ANALYZE /ZEROS

The transfer function gain K is listed as a fraction and an exponent since the productsof the poles and zeros can exceed the floating point range. After the gain, the transferfunction zeros are listed, followed by the cancelled zeros/poles in pairs.

5.3.8 ANALYZE/LIST/DISPLAY/STATUS

/LIST /LIST turns on a flag so that internal details of various operations are written out. Thisaffects output from the following commands:

/T RIM /ROOTLOCUS/B ODE /NIC HOLS /NYQUIST /INV NYQ

When used with /TRIM, details of the iteration (i.e., successive values of the statevector, the derivative vector, and the residual) are written out.

ANALYZE /LIST=.T. /TRIM

With the frequency response verbs, the gain and phase at each frequency pointcalculated are written out.

With /ROOTLOCUS, the complex plane location, gain, and step size are listed. If thelist is requested, HVDPRN or ANALYZE/DISPLAY is TRUE, and the root locus plotis drawn on the screen, the printed output overwrites the plot. If switching HVDPRN,DISPLAY, and/or the list off doesn't solve the problem, probably error messages arebeing written to the screen. Direct the plot to a hardcopy device or file until the errorshave been diagnosed and fixed.

Setting the /LIST parameter back to its default value of FALSE suppresses all thisoutput. The /LIST flag remains as set until you change it explicitly.

/DISPLAY In general, ANALYZE operations are considered high volume operations and are thuswritten only on the PRN unit (as are PRINT and debug dumps). If /DISPLAY is setTRUE, output is repeated on the DIS unit (if different from PRN) for monitoring at theterminal. The /DISPLAY flag remains as set until you change it explicitly.

/STATUS To review the current status of all the internal ANALYZE qualifiers, use the command:

ANALYZE /STATUS



which lists the names alphabetically with their respective values and definitions asshown in Figure 5-2. To review the current status of the system symbols relating tofrequency analysis, find all the variables with six characters ending in FPL by usingwild cards with the DISPLAY command;i.e.,

DISPLAY ???fpl

For a listing of the state matrices, see ANALYZE /JACOBIAN.

5.3.9 ANALYZE examples

Following are some examples of the ANALYZE command. In general, qualificationstatements appear before action statements. The sequence of operations is from left toright. You can use as many continuation lines as necessary.

ANALYZE /LIST=.T. /FREEZE=x /TRIM /EIGEN /JACOBIAN

This command turns on the request for a detailed listing, eliminates (with /FREEZE)the state X and its corresponding derivative from the Jacobian, finds the steady state,and then evaluates the eigenvalues and Jacobian at the steady state point in state space.

STARTANALYZE /JACOBIAN /VECTORS=.T. /EIGEN

This command determines the Jacobian about the point in state space where thesimulation terminated, specifies that eigenvectors are required, and then calculatesboth eigenvalues and eigenvectors. Note that if /TRIM had been used, the endingstates would have been overwritten with the initial conditions.

Control index (CINDEX ) 1Degrees instead of rads (DEGREE ) .TRUE.

Value of pure delay (DELAY ) 0.Display results flag (DISPLAY) .FALSE.

Freq logarithmic scale (FLOGSC ) .TRUE.Fractn change multiplier (FRACDL ) 1.00000000

Min fractional multiplier (FRACPM ) 1.00000000Minimum frequency (FREQMN ) 1.00000000Maximum frequency (FREQMX ) 1000.00000

Use gain in db (GAINDB ) .TRUE.Minimum gain (GAINMN ) 1.0000E+38Maximum gain (GAINMX ) 1.0000E+38

Gain logarithmic scale (GLOGSC ) .TRUE.Hertz instead of rad/sec (HERTZ ) .TRUE.

Min imag on complex plane (IMAGMN ) 1.0000E+38Max imag on complex plane (IMAGMX ) 1.0000E+38

List internal working (LIST ) .FALSE.Rel increment of control (MINC ) 1.0000E-04

Max value of mu (MUMAX ) 1000Max number of interations (NITRMX ) 50

Observer index (OINDEX ) 1Minimum phase (PHASMN ) 1.0000E+38Maximum phase (PHASMX ) 1.0000E+38

Min real on complex plane (REALMN ) 1.0000E+38Max real on complex plane (REALMX ) 1.0000E+38

Rms error max (RMSEMX ) 1.0000E-04Eigen vector flag (VECTORS) .FALSE.

Abs increment of control (XINC ) 1.0000E-04

Figure 5-2. ANALYZE /STATUS output



ANALYZE /TRIMREINIT

This command uses the current initial conditions to establish a steady state, and thenthe REINIT command writes the current state vector back over the initial conditionvector. Every subsequent START now starts from a trim, or steady state, condition.

Model definition The use of ANALYZE presupposes that the model is defined by a sequence ofnonlinear equations of the form:

X.

= F ( X1, ..., Xj, ..., Xn, t )

Restrictions The use of self-contained states within the model (those not defined by INTEG andINTVC) usually prevents the correct evaluation of the Jacobian. Likewise, memoryoperators such as BCKLSH should not be present.

State description Following is an example of extracting the full state space description:

ANALYZE /XINC=1.0E-6 /CONTROL=u1,u2 /INC=0.01ANALYZE /OBSERVE=y1,y2,y3ANALYZE /JACOBIAN

Here the default value for the absolute perturbation for the control variables isspecified as 1.0E-6, the control variables are listed, and then an overriding controlvariable perturbation of 0.01 is applied only to U2. The observable list is defined, andthen the Jacobian, which prints out the four [A, B, C, D] matrices, is requested.

Lists Note that the ANALYZE lists are cumulative;i.e, the lists of the control variables andobservables, for instance, remain in effect from one call to another until explicitlyCLEARed.

Initial conditions Another point to keep in mind is that all initial conditions must be defined before/TRIM is invoked. Executing any ANALYZE command prior to START triggerscopying of the initial condition vector to the state vector. However, if some initialconditions are calculated in the INITIAL section, set a run time of zero and execute(START) the simulation prior to using ANALYZE. For example:

SET tstop=0.0STARTANALYZE /LIST=.T. /TRIMREINITSET tstop=99.9START

Figure 5-3. System for Frequency Response Analysis



Use REINIT after the /TRIM to move the trimmed state variables back into the initialcondition values so that the steady state point in state space becomes the starting pointfor any subsequent run (START).

Third orderexample

Figure 5-3 is a block diagram of a third order plant with compensator to be analyzedfor frequency response. This example also appears in Appendix A as Linear AnalysisExample (model TRUXAL). As the diagram shows, the feedback path is completedthrough a gain K. Constant terms EZ and UZ are added in the forward path. Theseterms are initialized to zero but used as control inputs in addition to the reference R sothat the open loop response can be determined for either the complete system, theplant alone, or the compensator alone by selecting the appropriate input/output pair.The following commands generate an open loop Bode plot as shown in Figure 5-4.

SET k=0, TITLE(41)='Open Loop Response', SLTFPL=100ANALYZE /CONTROL=r,ez,uz /OBSERVE=y,uANALYZE /CINDEX=2ANALYZE /HERTZ=.F. /FREQMN=0.1 /FREQMX=1000ANALYZE /BODE

Open loop The open loop response is obtained by setting the loop gain K to zero, establishing thelist of control and observable variables, setting the control index to EZ (the seconditem on the list of control variables), specifying the frequency range and units, andthen requesting the Bode plot. Setting SLTFPL to 100 results in the gain curve being adotted line.

To get the plant response, Y/UZ, set the control index to 3; for the compensator, U/EZ,set the control index to 2 and the observable index to 2.

To get a root locus plot of the open loop system, follow the commands above with:

ANALYZE /IMAGMN=-10 /IMAGMX=10 /REALMN=-10 /LIST=.T.ANALYZE /ROOTLOCUS

The first command sets the area of interest on the complex plane; the second commandplots the loci. If the boundaries of the plot are not specified, the area is sized from the

Figure 5-4. Examples of frequency response plots(a) Bode, (b) root locus, (c) Bode in strip plot form



poles (-20 to zero on the real axis) and -1 to +1 on the imaginary axis, resulting in asomewhat distorted view. Position, gain, and step length are printed out during thelocus tracking since /LIST is TRUE.

Closed loop For a closed loop Bode plot, the gain K is specified. Separate plots are chosen withthe system symbol DTCFPL (draw two curves), and the Y axis length and a plot scalefactor are also modified. The control index is changed to R (first on the list of controlvariables) and the Bode plot requested.

SET TITLE(41)='Closed Loop Response'SET k=1438, DTCFPL=.T., YINFPL=6, PSFFPL=0.9ANALYZE /CINDEX=1 /BODE

5.4 Comment (!)

FORM: ! <string>

Comments may be included in the runtime statements. Any characters after anexclamation point (!) to the end of the line are considered comment and are notexecuted. For example:

! Select stiff integration algorithmSET IALG=2START ! Execute the model

Comments are retained inside PROCEDURE text but are ignored on execution when aPROCEDURE is invoked. However, they are shown when a PROCEDURE isdisplayed or when system symbol HVDPRN is TRUE (the default at Version 11).

5.5 Continuation (&)

The continuation character is the ampersand (&). The runtime executive appends thesubsequent line to the end of the continued line without any trailing blanks, butleading blanks on the continuation line are not suppressed.

PLOT /XAXIS=w /XLOG /XLO=wmn /XTAG='(Hz)' &pgd /TAG='Phase (deg)', gdb /TAG='Gain (dB)'

Any number of continuation lines may be used at runtime. Splitting a symbol betweenlines is allowed, but be careful not to accidentally insert any blanks into the resultingstring. Delimiters between symbols (usually commas) must not be overlookedbetween lines; they can be placed at the end of the line before the ampersand or at thebeginning of the following line. The latter is preferred mainly because the commasstand out more so you are less likely to make errors.

Comments can be added to a continued line since the runtime executive stripscomments off before looking back from the end of the line for an ampersand.

PLOT /XAXIS=w /XLOG /XLO=wmn /XTAG='(Hz)' & ! Log scalepgd /TAG='Phase (deg)', gdb /TAG='Gain (dB)'

5. ACSL Runtime Commands 5.4 Comment (!)


5.6 CONTINUE

FORM: CONTINUE

SWITCHES: /CHARACTER = '<character>' ['<blank>']or <integer-variable>

/H I = <real-variable> [1.0]/L O = <real-variable> [0.0]/P LOT/R ESCALE/T YPE = ijk [000]

A run may be continued where it was stopped by changing the stopping condition andusing the CONTINUE command. The switches control plotting of output variablesduring the simulation run and are described under START.

Initial conditions The CONTINUE operation bypasses the INITIAL section and does not put the initialconditions into the state vector; therefore, the program continues to integrate from thecurrent point in state space.

CONTINUE makes sense only after a START or ANALYZE/TRIM command hasestablished the states. Also, the termination condition of the previous run must havebeen changed; otherwise, the CONTINUE run will terminate immediately.

For example, using the following definitions in the model:

CONSTANT tf=10.0TERMT(T .GE. tf, 'Run terminated on time TF'))

and runtime commands:

SET NRWITG=.F. ! Erase results of any previous runsSTART ! Run to 10.0 secSET NRWITG=.T. ! Add results to previous run recordSET tf=15.0 ! Extend stopping condition to 15.0 secCONTINUE ! Run 10.0 to 15.0 sec

results in the model running to 10.0 seconds, stopping (at which time any variablescan be examined), then continuing to 15 seconds. Note that by default START andCONTINUE overwrite the data logging scratch file (i.e., NRWITG = .FALSE.). If thedata is to be accumulated, the no rewind option should be set TRUE as in the example.

/RESCALE One difference in plotting with CONTINUE compared with START is that if/RESCALE is used with CONTINUE, the scales for the X axis must be overridden./RESCALE takes its data from the previous run, which stopped at the point where thenew run continues on, so /LO and /HI should be used to specify the new scales:

CONTINUE /PLOT /RESCALE t /LO=10 /HI=15

After RESTORE CONTINUE may be used after RESTORE, but with care. If the model containsDISCRETE sections or SCHEDULE statements, for example, the event list should besaved (see SAVE/EVENT).

5.6 CONTINUE 5. ACSL Runtime Commands


5.7 DATA

FORM: DATA name (arg1, arg2[, arg3...])d11 d12 [d13 ...]d21 d22 [d23 ...]d31 d32 [d33 ...]d41 d42 [d43 ...]...END

Measured data can be defined at runtime, either interactively or in a command file, andplotted alongside the simulation-generated variables. The measured data is plottedwith symbols at the data points and no curve drawn between the points.

Definition The definition begins with the keyword DATA, followed by the name of the DATAblock and a comma-delimited list of arguments in parentheses. The data follows,delimited by a space or a comma. The number of data items must be an integermultiple of the number of arguments. An END statement concludes the definition.

Not inPROCEDURE

The definition cannot be in a PROCEDURE, but any number of DATA blocks can bedefined, at any time. The appropriate one can be accessed from a PROCEDURE.

The DATA statement (with word DATA, the name of the block, and the list ofarguments) is intended to be one line; if it is written on more than one line (to line upcolumns with the data which follows, for example), it must be explicitly continued bythe ampersand (&). No continuation characters are needed for the lines of data, whichmay contain any number of data items. Lining up the data in columns improvesreadability but is not required.

The independent variable (usually time) must be included in the definition; it isgenerally the first argument. A minimum of two arguments is required.

Missing orquestionable

data points

Data may be marked as missing by entering a question mark (?) in place of the datapoint. A question mark can also be placed directly after a data point (with no spacebetween the data and the question mark) to imply questionable data. Indicatingmissing data is necessary for completing the data table even though no data can beplotted. For questionable data, however, the point is plotted with the same symbol asthe other data points but with an I-beam twice the size of the symbol added. ThisI-beam does not scale the error, it just marks a point of questionable data.

PLOT /DATA The PLOT command has a switch /DATA for specifying that measured data beplotted. The measured data in the DATA definition is plotted with a symbol at eachdata point. The default symbol begins with the letter A and increments through thealphabet for each variable on a given plot. Symbols can be specified using the PLOT/CHARACTER switch.

The simulation results are plotted with a line connecting the values, so the measureddata points can be compared with it. To see only the data from the DATA block, setLINCPL (line between data points) to FALSE so that no line is drawn between thesimulation data points, then the calculated values do not appear. It may be necessary toforce the scales in this case since the axes are scaled to the hidden simulation values.

Example Following is an example of data entered for the VANDPL example (distributed witheach ACSL system). The DATA statement is defined:

5. ACSL Runtime Commands 5.7 DATA


DATA test1 &(t, x, xd)0.4 0.5 -0.31.2 0.0 -0.52.0 -0.2? -1.02.8 ? 0.0?3.4 -1.4 0.54.2 -0.4 0.95.0 0.6 1.75.4 1.3 1.3?5.8 1.7 0.06.6 1.3 -0.67.0 1.0 ?7.8 0.0? -2.28.2 -1.0 -1.89.2 -2.2? 0.09.8 -1.5 0.8END

Figure 5-5(a) shows the data plotted with simulation results from the command:

PLOT /DATA=test1 /CHARACTER=2 xd,x

Figure 5-5(b) shows the measured data for XD by itself from the commands:

SET LINCPL=.F.PLOT /DATA=test1 /CHARACTER=2 xd

Figure 5-5. Measured data (a) with simulation results and (b) alone

5.7 DATA 5. ACSL Runtime Commands


5.8 DISPLAY

FORM: DISPLAY name, ..., name

SWITCHES: /ALL/C ONSTANTS/P ROCEDURE [= <procedure-name>]/VA RIABLES/VE RSION

DISPLAY displays the current values of the items listed. This command is usuallyused at the end of a run to determine final values, or before a run to confirm inputconstants before starting the run (when running interactively). To display values at aspecified time during a run, use the window feature of either RANGE or PRINT.

Wild cards Wild cards may be used with this command. An asterisk (*) stands for zero or morecharacters, and a question mark (?) stands for any one character.

Wild cards find not only user variable names, but also extend through the ACSLsystem dictionary; for example, the system symbols relating to frequency plots(six-character symbols ending in FPL) can be listed by:

DISPLAY ???fpl

All symbols of zero or more characters in both program and system dictionary arelisted by:

DISPLAY *

This is useful for finding hidden symbols in the system dictionary (i.e., those coveredby duplicates in the model).

/ALL /ALL displays all user variables and constants (but not ACSL system symbols) indictionary order (i.e., system symbols, states with their derivatives and initialconditions, then algebraic variables) when the /ALL switch is invoked. See Figure 5-6.

DISPLAY /ALL

Arrays are listed completely with the /ALL option only if their dimensions do notexceed MALPRN, the system symbol specifying maximum array length for printing.If MALPRN (default 10) is exceeded, the array dimension and the value of the lastelement are listed.

/CONSTANTS /CONSTANTS displays the values of all symbols defined in CONSTANT statements.

/VARIABLES /VARIABLES displays the values of all variables which are not CONSTANTs ordummy variables of the form Z0nnnn.

Both /CONSTANTS and /VARIABLES listings are in alphabetical order rather thandictionary order as in the /ALL listing. See Figure 5-6.

Arrays Arrays, if not explicitly referred to by element, are listed in total (except with the/ALL option, as noted above). For example, if RM and A are both arrays, thecommands

STARTDISPLAY t,x,y1,rm(3),a

produce a list including only the third element of array RM but all elements in thearray A. Displaying T (time) is often useful in determining if the run has beencompleted as anticipated.

5. ACSL Runtime Commands 5.8 DISPLAY


/PROCEDURE After defining a number of PROCEDUREs, it is sometimes difficult to recall whatprocedure commands are available, or, even if the names are known, what they do.The names of all procedures are listed in response to the command:

DISPLAY /PROCEDURE

If the name of one of the defined PROCEDUREs is specified, then the PROCEDUREarguments are listed, followed by default strings if given, and then the text listing. Forexample:

PROCEDURE pp(xl=0.0, xh=5.0, tag='LongTag', a, b)PLOT /XLO=&xl /XHI=&xh &a /TAG=&tagPLOT &b /TAG=&tagEND...

DISPLAY /PROCEDURE=ppPP

ARGUMENTS (DEFAULT VALUES)

1 XL (0.0)2 XH (5.0)3 TAG (LongTag)4 A5 B

DISPLAY/CONSTANTSCINT 0.02500000 G 32.2000000 IALG 4

KDAMP 0.00500000 LENGTH 2.00000000 MAXT 0.01250000MINT 1.0000E-09 NSTP 1 THDIC 0.THIC 1.00000000 TSTP 4.90000000 WEIGHT 5.00000000

ZZSEED 55555555

DISPLAY/VARIABLEST 4.91250000 TH 0.88881500 THD 0.87794500

THDD-12.4949000

DISPLAY/ALLT 4.91250000 ZZTICG 0. CINT 0.02500000

ZZIERR F ZZNBLK 1 ZZICON 0ZZSTFL T ZZFRFL F ZZICFL FZZRNFL F ZZJEFL F ZZNIST 2ZZNAST 0 IALG 4 NSTP 1

MAXT 0.01250000 MINT 1.0000E-09

State Variables Derivatives Initial ConditionsTH 0.88881500 Z09997 0.93044900 THIC 1.00000000

THD 0.87794500 Z09998-12.4949000 THDIC 0.

Algebraic Variables

Common Block /ZZCOMU/G 32.2000000 KDAMP 0.00500000 LENGTH 2.00000000

THDD-12.4949000 TSTP 4.90000000 WEIGHT 5.00000000ZZSEED 55555555

Figure 5-6. DISPLAY /CONSTANTS /VARIABLES /ALL

5.8 DISPLAY 5. ACSL Runtime Commands


PROCEDURE TEXT

PLOT /XLO=&001 /XHI=&002 &004 /TAG=&003PLOT &005 /TAG=&003

All arguments in the argument list are transformed to upper case, but any text in thelisting of default values and the text in the PROCEDURE TEXT listing retain theiroriginal case.

Argument substitution is indicated in the listing of the PROCEDURE TEXT by anampersand followed by a three-digit number (&007 for the seventh argument, forexample) rather than the text in the definition.

/VERSION The version of ACSL in use can be determined at runtime with this switch. Forexample,

DISPLAY /VERSIONACSL Version 11.2.2

5.9 END

FORM: END

The END command at runtime defines the end of a PROCEDURE or DATAdefinition. To terminate an ACSL runtime session, use the QUIT command.

5.10 EXIT

FORM: EXIT

EXIT is a synonym for QUIT; it terminates the ACSL runtime session.

5.11 FILE

FORM: FILE

SWITCHES: /CMDFILE = 'filename' [keyboard]/DISFILE = 'filename' [screen]/PLTFILE = 'filename' [screen]/PRNFILE = 'filename' ['model.LOG']/RRRFILE = 'filename' ['model.RRR']

FILE specifies a file name for any of the runtime logical units, which are:

Name Default Description

CMD 5 command file (model.CMD), keyboardDIS 6 display file (primary output)PLT 6 plot filePRN 9 print (or log) fileRRR 8 data logging file (raw run record)

5. ACSL Runtime Commands 5.9 END


The default number is the internal logical unit number. Display output and plotsappear on the screen unless directed otherwise. The command file is read inautomatically and the RRR and log files are written out automatically to the defaultnamed files unless directed otherwise. SeeACSL Sim User's Guidefor moreinformation on these files.

On recognition of the FILE command, the system checks for the next unused Fortranlogical unit number starting at 99 (this number may be system dependent) and workingdownwards. When an open unit number is found, it is assigned to the appropriateinteger variable (CMD, DIS, PLT, PRN, RRR) and the file is opened. In order toprevent excess open files, for every file except the CMD input file, the previouslogical unit is closed. The command input file is not closed since it must normally readto end-of-file, at which point the file is closed and the previous file is recovered from astack.

Multiple RRR files Figure 5-7 shows the use of multiple RRR files. The first command is:

FILE/RRRFILE='test1.bin'

This closes logical unit 8 (the default RRR logical unit number) and opens logical unit99 as the new file. The next file assignment closes unit 99 and opens 98 (the test forthe next available open unit is done before the first file is closed). For the third FILEcommand, unit 99 is free again, and so this is opened after closing unit 98.

Specify CMD file On most computer systems, ACSL reads in a command file (default namemodel.CMD) if it is available. Figure 5-8 show the sequence for changing this file.The command:

FILE/CMDFILE='doit.cmd'

opens logical unit 99 as this file, which is then read to an end-of-file when controlreverts to the previous file, which in this case is the keyboard (unit 5).

Warning –logical unit

numbers

If Fortran logical unit numbers are used in a program, we recommend avoidingnumbers below 10 and from 99 downwards for probably ten to twenty possible unitsopened.

ACSL> FILE/RRRFILE='test1.bin'ACSL> Closing logical unit 8 as file VANDPL.RRR;1ACSL> Opening logical unit 99 as file TEST1.BIN;1ACSL> STARTACSL> ...ACSL> FILE/RRRFILE='test2.bin'ACSL> Closing logical unit 99 as file TEST1.BIN;1ACSL> Opening logical unit 98 as file TEST2.BIN;1ACSL> STARTACSL> ...ACSL> FILE/RRRFILE='test3.bin'ACSL> Closing logical unit 98 as file TEST2.BIN;1ACSL> Opening logical unit 99 as file TEST3.BIN;1ACSL> STARTACSL> ...

Figure 5-7. FILE command switching RRR unit

5.11 FILE 5. ACSL Runtime Commands


5.12 HELP

FORM: HELP [command [/switch] ]

The HELP command brings up a help facility for the runtime commands. Becauseimplementing this facility depends on the computer operating system, it may not beavailable on every system.

If no command is specified, a list of the commands appears. If a command is specified,that command is explained and the switches for the command are listed.

HELP plot

To go directly to information about a switch, list the command and then the switch:

HELP plot /xaxis

Help for the ACSL system symbols is found under topic SYMBOLS.

5.13 MATH

ACSL provides plotting capabilities with the PLOT command and linear analysiscapabilites with the ANALYZE command, but a more powerful approach to plottingand analysis is available in ACSL Math. For complete details on ACSL Math, see theACSL Math User's GuideandACSL Math Reference Manual.

ACSL Math is a software package that provides:

. A platform for running ACSL models

. Tools for plotting

. Tools for analysis

. Scripting language

. Means of comparing model output to empirical data

First, build a model in ACSL, then run and analyze it in ACSL Math. The ACSLruntime commands are available in ACSL Math. ACSL Math comes up in an Outputwindow that shows output text and a prompt for typing commands:

MATH>

ACSL> ...ACSL> file/cmdfile='doit.cmd'ACSL> Opening logical unit 99 as file DOIT.CMD;1ACSL> startACSL> display x,xdACSL> X-1.45462417 XD 0.96626579ACSL> End of file found on unit 99ACSL> Reverting to logical unit number 5ACSL> ...

Figure 5-8. FILE command switching CMD unit

5. ACSL Runtime Commands 5.12 HELP


Other windows appear as needed for figures.

You can toggle back and forth between the ACSL Math prompt and the ACSL promptwith two exclamation points (!!):

MATH> !!ACSL> !!MATH>

You can also issue ACSL commands directly from ACSL Math by preceeding thecommand with two exclamation points:

MATH> !!start

ACSL Math is case sensitive. Its syntax is similar to that used by many mathematicalpackages on the market, so the functionality of these packages is availablealong withyour ACSL command files.

All the variables in an ACSL model can be read and written from ACSL Math. To seea list of all variables in the ACSL Math workspace, typewho at the command prompt.For the ACSL Van der Pol example model (VANDPL), after it has been loaded andrun, the results are:

MATH> whoYour Variables are:

CINT IALG LA MAXT MINT NSTP T TSTP X XD XDDXDIC XIC ZZSEED _t _x _xd _xdd

ACSL model variables are in uppercase, and the time history variables begin with anunderscore (_). The items with underscores are on the Prepare list in the VANDPLcommand file. Only variables on the Prepare list are collected for time history, andthey appear in this list only after a run has been initiated with a START command.

You can examine final values from the model by typing the names of the variables atthe ACSL Math prompt:

MATH> TT =

10

Capitalization is significant. If you were to type the names in lower case, you wouldsee the following error message:

MATH> t! ErrorUndefined variable or function "t"

Variables can be changed from the ACSL Math command line and the model rerun;for example, change the damping factor LA and rerun the VANdPL model as follows:

MATH> !!set LA = 0.2; start

You can plot the the time history variables in ACSL Math. Following are the basiccommands to plot X against time, label the axes, and add a title.

MATH> plot(_t,_x)MATH> xlabel('T (time)')MATH> ylabel('X (position)')MATH> title('Van der Pol Oscillator')

See the ACSL Math documents for more information on importing data, writingscripts, and many other features of ACSL Math.

5.13 MATH 5. ACSL Runtime Commands


5.14 MERROR, XERROR

FORM: MERROR name = <real-variable>XERROR name = <real-variable>

The relative and absolute errors allowable during variable order, variable stepintegrations may be individually specified by MERROR and XERROR.

Each state is associated with a corresponding entry in the relative error table(MERROR) and absolute error table (XERROR). These two commands behave like aSET command except that they access the error table corresponding to the state namerather than the state name itself. For example:

MERROR sv1=1.0e-3, sv2=0.01XERROR sa1=5*0.0001, sa2(3)=0.02

whereSVi andSAi are state variables and state arrays, respectively.

Note that arrays may be filled by a repeat count (for example, 5*0.0001). This actionmay overflow the array, but that should not be a problem. An individual array elementmay be specified at runtime; at model definition time, the same allowable error mustbe specified for all elements in an array.

During the integration step, the estimated error for each state variable is compared tothe allowable error,Ei, obtained from:

Ei = MAX ( Xi, Mi |Yi |max )

where |Yi |max is the maximum absolute value of the state achieved so far during therun.

5.15 OUTPUT

FORM: OUTPUT name, ..., name

SWITCHES: /ALL/CHARACTER = '<character>' ['<blank>']

or <integer-variable>/CL EAR/H I = <real-variable> [1.0]/L O = <real-variable> [0.0]/N CIOUT = <integer-variable> [1]/T YPE = ijk [000]

The OUTPUT command designates variables to be listed or plottedduringa run.

The OUTPUT command is given before a START; output of the values occurs inresponse to a START or CONTINUE command

If listed, the output appears at each time step on both the low volume output file (DIS)and high volume output file (PRN) as the run progresses. This is distinguished fromthe PRINT command, which lists data in columnar form on the high volume outputfile (PRN) only after the run has been completed.

Independentvariable

Note that the independent variable is not included on the OUTPUT list automatically;you must list it explicitly to see it.

5. ACSL Runtime Commands 5.14 MERROR, XERROR


Wild cards Wild cards can be used in the OUTPUT list specification (* for zero or morecharacters and ? for any one character); for example:

OUTPUT t,v*,k??

/ALL /ALL adds to the OUTPUT list all the model variables listed out by the debug dump,except for constants and ACSL dummy variables (those of the form Z0nnnn).

/NCIOUT The values of the list elements are normally written out at every communicationinterval. If this rate is too high, it can be reduced with /NCIOUT (number ofcommunication intervals between output listings). For example, the followingcommand results in an output every five communication intervals:

OUTPUT t,a,b /NCIOUT=5

Only one value for /NCIOUT can be in effect at one time; the last value set stays ineffect until changed in a subsequent OUTPUT command. It is not possible todesignate different variables to be recorded at varying data rates as all elements on thelist are output together.

NCIOUT is a system variable which can be SET or DISPLAYed in addition to beingcontrolled with the OUTPUT switch.

SET NCIOUT=100

ACTION (another runtime command) can be used to change NCIOUT at differentvalues of the independent variable; thus, although all the list elements will be recordedat the same rate, that rate can be changed over the course of a run.

ACTION /VARIABLE=2.0 /VALUE=10 /LOCATION=nciout/VARIABLE=4.9 /VALUE=1 /LOCATION=nciout

Forcingadditional data

logging

LOGD can be called from within the model source code toincreasethe number oftimes data is logged and thus the amount of output. Data is logged automatically ateach communication interval, at the end of the DYNAMIC section code. It is oftenhelpful to see output when a DISCRETE section is executed, for example. Insert a callto LOGD at the end of a DISCRETE section and then include variables calculated orchanged in that section on the OUTPUT list to see their progress at critical times. SeeAppendix B for more details on LOGD.

DISCRETE swswitch = .TRUE....CALL LOGD(.TRUE.)

END

Arrays Array elements can be listed by referring to the specific element; for example, A(3). Ifthe name listed is an array, but no specific element is called for, all elements are output.

/CLEAR The OUTPUT commands are cumulative;i.e, rather thancorrectingpreviousspecifications, additional commands simplyaddvariables to the list. This can lead toinadvertently long and/or duplicated lists. To clear the list and start over, use the/CLEAR switch; for example,

OUTPUT /CLEAR t,x,y,z

Width of listing OUTPUT is considered low volume and is written to both the DIS and PRN units ifthey are different. The width of the line is controlled by system variable TCWPRN(terminal character width), which controls data sent to the DIS logical unit. IfTCWPRN is 80 (the default), output is three variables across; if 132, five variables

5.15 OUTPUT 5. ACSL Runtime Commands


across. For the PRN print log file, PCWPRN controls the printer character width(default 132).

Plotting OUTPUTdata

START/PLOT and CONTINUE/PLOT commands result in the OUTPUT variablesbeing plotted rather than listed. The first variable on the OUTPUT list is used for theX axis (the independent variable);all the other variables appear as Y axes. SeveralOUTPUT switches establish default characteristics of the plots. The same switches areavailable with START and CONTINUE and override the values specified in OUTPUT.

Plot scales /HI and /LO specify the scales of the Y axes. If given with OUTPUT itself, they applyto all variables not otherwise given specific scales. For a particular variable, the switchapplies to the variable immediately to its left.

OUTPUT /LO=-10 /HI=10 t /LO=0, a,b,c

The scales for T are zero to +10 and for A, B, and C are -10 to +10. The independentvariable is scaled in the same way as the dependent variables, the only differencebeing that it is the first item in the list.

/CHARACTER /CHARACTER specifies a character symbol to appear on the curve if SYMCPL isTRUE. The use of characters is the same as for the PLOT command except that thedefault character is blank rather than "A".

/TYPE /TYPE specifies the style (i), width (j), and color (k) of a curve as described for thePLOT command.

5.16 PAUSE

FORM: PAUSE

The PAUSE command simply waits for a carriage return from the keyboard. Its mainuse is to wait between plots in a sequence of PLOT commands, usually specified in aPROCEDURE in interaction operation.

In a series of plots, each new PLOT command erases the screen and writes over theprevious plot. This action usually occurs too quickly to view the plot in any detail.With the PAUSE command, each plot can be viewed as long as needed before movingon to the next one.

A PROCEDURE using the PAUSE command could be in the form:

PROCEDURE p3PLOT thPAUSEPLOT thdPAUSEPLOT thddEND

5. ACSL Runtime Commands 5.16 PAUSE


5.17 PLOT

FORM: PLOT name, ..., name

SWITCHES: /ALL/CHARACTER = '<character>' ['A']

or = <integer-variable>/CL OSE/COLOR = <integer-variable> [0]/D ATA = <name-of-DATA-block>/H I = <real-variable>/LO = <real-variable>/LOG/O VER/R UN = <integer-variable>/S AME/S TYLE = <integer-variable> [0]/TA G = '<string>'/TY PE = ijk [000]/WIDTH = <integer-variable> [0]/XA XIS = name/XH I = <real-variable>/XLO = <real-variable>/[NO]XLOG [/NOXLOG]/XT AG = '<string>'

Line plots, strip plots, and/or printer plots can be generated for any variables on thePREPARE list. The form of the plots is controlled by system symbols CALPLT (forline plots), STRPLT (for strip plots), and PRNPLT (for printer plots); the default formis line (continuous) plots. Frequency analysis plots are described under ANALYZE.

Wild cards Wild cards (* and ?) can be used with the PLOT command. To limit the number ofvariables plotted, only ten matches are allowed before an error message is printed out.

The order of commands is generally:

PREPARE ... ! Establishes list of variables to be savedSTART ! Runs model, logs values of PREPARE variablesPLOT ... ! Makes plots using data saved during run

The order of items on the PLOT command is: first, any X axis switches, then Y axisvariables separated by commas, with Y axis switches immediately to the right of thevariables to which they apply.

PREPARE list The PLOT command uses the current PREPARE list to find the data for each variableon the intermediate data file (RRR); therefore, the PREPARE list cannot be changedbetween the START command and the PLOT command that uses the data generatedby the START.

X axis variable The X axis variable can be specified with the /XAXIS switch, explained below. If novariable is specified, the plotting routine assumes that the first variable on thePREPARE list is the independent variable and is to be plotted on the X axis.

Plot number A vertical text string containing a plot number (from the start of the session) and thedate and time at which the session was initiated is drawn at the right of the plot imageunless suppressed by setting DPNPLT to FALSE.

Automatic scaling Automatic plot scales are chosen by rounding to multiples of 1, 2, 4, or 5. If thedifference between the maximum and minimum is less than ten percent, the scale isexpanded.

5.17 PLOT 5. ACSL Runtime Commands


Switches The first section describes the PLOT switches relating to the X axis, the seconddescribes the Y axis qualifiers, and the third describes several miscellaneous switches.Some examples of typical PLOT commands are given in the last section. Exampleprograms which include commands and the resulting plots are found in Appendix A.

System symbols Plot size, grid lines, and other characteristics are set with system symbols which areaccessible by SET commands at runtime. See Appendix C for an explanation of thesystem symbols related to plotting and a list of device drivers.

5.17.1 PLOT X axis switches/XAXIS/XLO/XHI/[NO]XLOG/XTAG

Order ofspecification

The X axis qualifiers should always be specified first on the PLOT command linebecause the automatic scaling for the Y axis variables is determined by pickingmaxima and minima within the current X axis window for each Y axis variable as it isreached in the left to right scan by the executive.

Resetting X axisqualifiers

X axis related parameters, once set, stay the same for all subsequent PLOT commandsunless either they are respecified or the X axis variable itself is changed. Changing theX axis variable resets all parameters to their default values, which are: no tag string,linear scales, and automatic scaling. Thus, changes to any of the X axis qualifiers mustfollow (reading left to right) the specification of the XAXIS variable. Respecifying thesame X axis variable also resets all the related parameters to their defaults.

/XLOG can be reset with /NOXLOG without affecting the other X axis qualifiers.

/XAXIS The independent variable is assumed by the plot driver to be the first item on thePREPARE list; however, you can specify it with /XAXIS instead;e.g.:

PLOT /XAXIS=th, thd

Phase plane plots and trajectory plots are examples of plots where the X axis variableis usually specified.

/XLO /XHI /XLO and /XHI set the limits of the X axis scales. Specifying the plot scale limits isoften used to expand an area of interest on a plot and to control scales from run to runso that anomalies in the results are easily detected.

PLOT /XAXIS=al /XLO=-5 /XHI=5, bePLOT /XAXIS=t /XLO=0 /XHI=2, th

/XLOG /XLOG specifies a logarithmic scale for the X axis. Zero or negative scale limits arenot permitted with logarithmic scales and produce a diagnostic message andreplacement with linear scales. The automatic scaling chooses a low value forlogarithmic scales which is the power of ten below the lowest value of the variable inthe window;e.g., if the variable to be plotted has a lowest value of 0.002, automaticscaling chooses a low value of 0.001. /XAXIS, /XLO, and /XHI can be used with/XLOG as with linear scales, with the exception that /XLO cannot be zero or negative.

The logarithmic scale for the X axis can be turned off with /NOXLOG or by changingthe X axis variable with /XAXIS.

5. ACSL Runtime Commands 5.17 PLOT


/XTAG /XTAG specifies a character string to be appended to the right of the X axis variablename on the plot label. This string is often used to identify units or spell out thevariable name:

PLOT /XAXIS=w /XTAG='Frequency (rad/sec)' /XLOG &/XLO=wmn /XHI=wmx gain, phase

One space is automatically placed between the variable name and the character string.The number of characters available for the tag depends on the length of the axis. If thevariable name plus the tag contains more characters than are available on one line, theexcess characters are simply dropped.

5.17.2 PLOT Y axis switches/CHARACTER/COLOR/LO/HI/LOG/STYLE/TAG/TYPE/WIDTH

These PLOT switches all follow the Y axis variable names as qualifiers, applying tothe variable name to the immediate left. In contrast to the X axis qualifiers, Y axisqualifiers are not carried from plot to plot and must be specified each time they areneeded.

Y axis scales/LO /HI

If scales are not specified for any given variable, they are chosen automatically. Themaximum and minimum values of the variable are determined while the X axisvariable is between its limits of /XLO and /XHI; checking first for the X axis windowensures that the appropriate scales are chosen for a particular plot since it may be thatonly a small fraction of the total simulation run is being plotted. You can specify the Yaxis plot scales with the switches /LO and /HI; for example:

PLOT y1 /LO=0 /HI=10, y2, y3 /LO=5 /HI=10

results in Y1 scaled from zero to 10 and Y3 scaled from 5 to 10, while the scales forY2 are chosen automatically.

Variable names can be used in the scale specifications. These variables can be set atruntime, but must first have been defined in the model code. It is also sometimesuseful to set a group of scales to the same, originally unknown, value. If maximumand minimum values can be collected in the model definition (preferably in theDYNAMIC section), they can be used to set scale factors as follows:

PLOT y1 /LO=ymin /HI=ymax

/LOG /LOG sets a logarithmic scale for the Y axis. Zero or negative scale limits are notpermitted with logarithmic scales and produce a diagnostic message and replacementwith linear scales. The automatic scaling chooses a low value for logarithmic scaleswhich is the power of ten below the lowest value of the variable in the window;e.g., ifthe variable to be plotted has a lowest value of 0.07, automatic scaling chooses a lowvalue of 0.01.

PLOT w2 /LOG /LO=0.001 /HI=10.0



/TAG /TAG specifies a character string or tag to be appended to the right of the variablename on the plot label; for example:

PLOT v3 /TAG='Vehicle velocity (ft/sec)'

The number of characters available on the plot axis depends on the length of the axis.On strip plots, if the variable name plus the tag contains more characters than areavailable on one line, the variable name appears on one line and the tag characterstring on a second line. If the tag character string still exceeds the length of the axis,the excess characters are simply dropped. On regular line plots, excess characters aresimply dropped.

/TAG applies only to the variable name immediately to its left on the PLOT command.

/CHARACTER /CHARACTER specifies a character (or symbol) to be placed on the plot curve. Forprinter plots (PRNPLT), the character forms the curve itself; for line (CALPLT) andstrip (STRPLT) plots, no character appears unless SYMCPL or SYMSPL is TRUE,when the character is drawn at each NPCCPL or NPCSPL data points (default of 10).

A sample of the symbol is drawn at the right of the axis label.

Once a character has been specified, symbols for subsequent curves follow in orderfrom the ASCII character set through the letters, then the digits, then back through theletters, etc. The thirteen centered symbols (shown in Appendix C) correspond tointeger values of one through thirteen (normally non-printing ASCII controlcharacters). To access these centered characters, use a non-quoted integer. Thefollowing results in the picnic table character being centered on the plot curve:

PLOT x /CHARACTER=7

The centered symbols also cycle in sequence within the set of centered symbols. Anysymbol other than a letter, digit, or centered symbol (e.g., percent, colon, etc.) repeatsitself. This includes the blank, so that the following command results in a blanksymbol on all three curves:

PLOT /CHARACTER=' ' x,y,z

The character can be specified prior to naming the first ordinate, which is useful with/ALL. The following command plots three plots per page (i.e., the default of NPPPLT)with each curve given a character in sequence 1, 2, 3, etc.:

PLOT /CHARACTER='1' /ALL

/TYPE /TYPE specifies the style, width, and color of the curve for devices that support thosefeatures. The three digits (ijk) are integers;i is extra width (in units of line width);j isthe style (0=solid, 1=dotted, 2=dashed); andk is the device dependent color.

PLOT y1 /TYPE=213PLOT y2 /TYPE=400PLOT y3 /TYPE=026

In this example, Y1 is dotted, width of two lines plus the original, and color three. Y2is solid, four lines added to the width, and default color (usually black). Y3 is dashed,single line width, and color six.

/COLOR /COLOR, /STYLE, and /WIDTH are alternatives to /TYPE. They can be used if onlyone of the options is needed, or more than ten selections within an option. If only coloris to be specified, for example, but the color palette has sixteen or sixty-four colors:

PLOT y1/COLOR=12, y2 /COLOR=8, y3 /COLOR=15



Setting system symbol ALCPLT (automatic line color) to TRUE results in automaticcycling through the colors starting with color number 1. Specifying a color of zeroturns off color for the variable to its immediate left and all variables to the right.

PLOT /COLOR=0 x,y,zPLOT x,y,z /COLOR=0PLOT x,y /COLOR=0, z,a,b,c

In the first example, color is turned off for the whole plot; in the second, X and Y havecolors of 1 and 2 but Z has no color; and in the third, only X is colored.

Selecting a non-zero color initializes the color sequence. This can be done as a switchto the PLOT command itself (which initializes the sequence beginning with the firstvariable to be plotted) or to a variable (which initializes the sequence beginning withthe variable to its immediate left).

PLOT /COLOR=5 x,y,zPLOT x,y /COLOR=5, z

/STYLE /WIDTH /STYLE specifies solid, dotted, or dashed lines, depending on the device capabilities./WIDTH adds the specified number of line widths to the original line, with half on oneside and half on the other so that the original line is always in the middle. /STYLEmay not work correctly on some systems.

PCs On the PC, the /WIDTH switch does not function for window plots. Also, the middledigit of /type doesn't do anything. The hundreds digit (left-most) has the followingeffects:

value style width----- ----- -----

0 solid 11 - - 12 .... 13 -.-. 14 -..-.. 15 solid 26 solid 37 solid 48 solid 5

The ones digit (right-most) gives the following colors, which have been enhanced atVersion 11.5 so they will appear darker on PC screens:

value color RGB intensities----- ----- ---------------

0 black 000 000 0001 blue 000 000 2552 green 000 128 0003 red 255 000 0004 purple 128 000 1285 teal 000 128 1286 peasoup 128 128 0007 gray 128 128 1288 purple 128 064 1289 peasoup 128 128 064

Plot devicecapabilities

If a device does not have the requisite capability, /TYPE, /COLOR, /STYLE, and/WIDTH are ignored. Sometimes the selected color can be the background color andthe curve is invisible. Some installations may not have colors available but still havethe capability to implement the style and width options; some screens handle colors



but not style or width. See the machine specific instructions for details of plottercapabilities at a given site.

Multi-run cyclingof color and

symbol

When system symbol FTSPLT (flyback trace suppression) is set TRUE for multi-runplots, character and color are cycled automatically for each run if they are specified.Multi-run plots are accumulated by looping from TERMINAL to INITIAL in themodel source code, by multiple START commands with system symbol NRWITG (norewind) set to TRUE, or by deferring plots with system symbol DEFPLT. Thecriterion for incrementing the character or color is when the first variable on thePREPARE list becomes more negative than its previous value.

Arrays When an array is plotted, the array name by itself stands for all its elements, and anyqualifiers such as scale factors explicitly given apply to all elements of the array. Toapply individual qualifiers, each element of the array must be individually specified onthe PLOT command. For the array Z:

PLOT z ! Each scale chosen automaticallyPLOT z /LO=5 /HI=10 ! All elements have same scalePLOT z(1) /LO=5,/HI=10 & ! Each scale specified separately

,z(2) /LO=0 /HI=20 &,z(3) /LO=0 /HI=10

5.17.3 PLOT switches/ALL/CLOSE/DATA/OVER/RUN/SAME

/ALL /ALL plots all the variables on the PREPARE list; this is normally used for debuggingpurposes. This is not recommended for plots on a CRT plot device because the screenis cleared after each plot. System symbol NPPPLT (default 3) specifies the number ofplots per page.

PLOT /ALL

/CLOSE The /CLOSE switch closes the plot file (logical unit PLT) so that any existing plotscan be spooled to a plot queue if available. Spooling can be done at runtime via theSYSTEM command. The /CLOSE switch must be the only switch on the PLOTcommand when it is used since plotting after closing a file will open the file again anddestroy the old contents. An error message is produced as follows:

PLOT x,y /CLOSEThe /CLOSE switch must be alone on the PLOT command

/DATA /DATA specifies the name of a defined DATA block for plotting measured data alongwith the simulated values. See the section on the runtime command DATA for thedefinition of the data. The measured data points are plotted using symbols (specifiedwith /CHARACTER) and are not connected by lines.

PLOT /DATA=test1 y1,y2,y3

Data is plotted for any of these variables for which DATA has been defined. Datacould be defined for all the variables, or for only some of them. Variables for which nodata has been defined are plotted from the simulation results as normal, without anyDATA information.



Symbols do not appear on the simulation curves unless system symbol SYMCPL orSYMSPL is set TRUE, so the unconnected symbols of the measured data are clearlydistinguished from the simulation results.

/DATA qualifying a specific Y axis variable selects from the specified DATA block,which may be different from the default.

PLOT /DATA=test1 y1,y2,y3 /DATA=test2, y4

The independent variable must appear in every DATA block definition.

/RUN /RUN extracts data from a specified run if more than one run has been collected on theRRR intermediate data file. Collecting runs is accomplished either by looping fromTERMINAL to INITIAL in the model source code or by executing separate STARTcommands with system symbol NRWITG (no rewind) set TRUE. If the switchappears with PLOT, it becomes the default for all the variables:

PLOT /RUN=2 y1,y2,y3

When attached to individual variables, it applies to the variable immediately to its left:

PLOT y1/RUN=2, y2/RUN=3, y1/RUN=1

/SAME /SAME applies the scales selected for the first element on the list to the rest of theelements;i.e., normally the scale is that of the first element on the list, but it can beoverridden by choosing scales for another element to the left of the /SAME switch.For example:

PLOT y1 /LO=0 /HI=10, y2,y3 /SAME

results in all plots having the specified scale of zero to 10.

PLOT y1,y2,y3 /SAME

results in all plots having the same scale, a scale chosen automatically from the valuesof Y1 and not taking into account the values of Y2 or Y3.

/OVER The switch /OVER is used to suppress extraneous printing of axes and is normallyused in conjunction with /SAME. The command:

PLOT y1,y2,y3 /OVER

draws and labels the vertical axes for Y1, the first element on the list, but suppressesthe separate axes and labels, even though the scales may be different, of Y2 and Y3.To ensure the same plot scales, use /SAME:

PLOT y1,y2,y3 /OVER /SAME

The main use for /OVER is to overlay plots using the strip plot option; the default isfor each variable on the list to be drawn on a separate area of the plot.

5.17.4 PLOT examples

PLOT commands can be simple, taking advantage of defaults and automatic scaling,especially for initial runs and debugging. More elaborate specifications can be addedas the need arises. For a first look at a model, the following commands could be given:

SET TITLE='Rigid Pendulum Model'PREPARE t,th,thd,thddSTARTPLOT th,thd



Figure 5-7(a) shows the resulting plot, with the first item on the PREPARE listassumed to be the independent variable and both curves on the same plot. The scalesare chosen automatically.

In order to differentiate the curves, the system symbol SYMCPL (symbols on lineplots) and LTFCPL (line type fragment) are turned on and /CHARACTER is added asshown in (b). A sample of the curve, including the symbol, appears at the right of thecorresponding Y axis label. The specification for the character is unquoted, so thesymbol is taken from the special centered character set shown in Appendix C.Additional information is added to both the X and Y axis text with /XTAG and /TAG.X axis qualifiers always appear before the Y axis variables.

SET SYMCPL=.T., LTFCPL=.T.PLOT /XTAG='(sec)' th /CHARACTER=1 /TAG='(rad)' &

, thd /TAG='(rad/sec)'

If not specified, the characters are letters starting with 'A'. The variables could also beplotted separately:

PLOT th ; PLOT thd

To stack the plots as in (c), turn off the line plot option (CALPLT) and turn on thestrip plot option (STRPLT). The X axis tag remains in effect, but the Y axis tags mustbe respecified each time they are needed since they apply only to the variable to theirleft and only for the immediate plot. Note that tags and titles retain their case althoughvariable names are drawn in all upper case.

SET CALPLT=.F.,STRPLT=.T.PLOT th /TAG='(rad)', thd /TAG='(rad/sec)'

No symbols appear on the curves in the strip plot because SYMSPL is not TRUE.

The X axis variable can be changed, which is useful for phase plane plots. The lengthof the X and Y axes are controlled with XINCPL and YINCPL. The line typefragment is set back to FALSE since there is only one curve. The following commandsproduce Figure 5-10(a).

SET STRPLT=.F., CALPLT=.T., XINCPL=4, YINCPL=4, LTFCPL=.F.PLOT /XAXIS=th /XTAG='(rad)' thd /TAG='(rad/sec)'

Figure 5-9. PLOT examples with (a) defaults, (b) symbols and tags, (c) strip plots



Now the plot is square, but the scales are not. Although the X axis is automaticallyscaled from -1 to +1, the Y axis is -5 to +5, so in (b) the limits of the Y axis scale areset to ±4. A centered symbol is chosen, and its frequency is controlled with NPCCPL(number of points per character). The communication interval CINT for this programis 0.025 sec, so NPCCPL of 40 results in symbols appearing at one-second intervals.Information is added to the title on the second line;i.e., beginning at character 41.

SET NPCCPL=40, TITLE(41)='Time ticks at each 1.0 sec'PLOT thd /TAG='(rad/sec)' /HI=4 /CHARACTER=3

Once set, all X axis qualifiers stay the same until either they are reset or else the Xaxis variable itself is changed. If the next plot specifies T as the independent variable,the scale and tag revert to the default;i.e., linear scale, automatic scaling, and no tag,as shown in (c):

SET TITLE(41)=40*' 'PLOT /XAXIS=t th

The second line of the title is cleared by specifying blanks for all the characters in theline. A symbol still appears on the curve at the rate specified previously by NPCCPL,but it is the default character since the character has not been specified. The axislengths remain as previously set.

In addition to the system symbols mentioned above, others enable deferred plotting(DEFPLT), specifying grid line type (GLTPLT), moving the plot origin (XZPPLT andYZPPLT), and scaling the size of the whole plot (PSFCPL and PSFSPL). The plotdevice driver is selected with DEVPLT, and the plot unit with PLT. The valuesavailable for these last two symbols depend on the computer system.

Several plots can be given the same scale, the scale either specified or left to automaticscaling. When chosen automatically, the scale for thefirst item affected by /SAME isused for all the others; in other words, the scale chosen does not necessarily fit all thevariables.

PLOT x,y,z /SAMEPLOT x /LO=0 /HI=10, y,z /SAME

Array elements are treated individually in automatic scaling, but if scales are specified,they apply to all elements of the array.

Figure 5-10. PLOT examples with (a) phase plane plot, (b) scales, (c) respecifying X axis



PLOT a /LO=-50 /HI=50

If /SAME is used with automatic scaling for an array, the scale chosen for all elementsis that of the first element (a(1) in the following example):

PLOT a /SAME

Array elements can be plotted individually by specifying the element:

PLOT a(3)PLOT /XAXIS=a(1), a(2)

The logarithmic scale is available for both the X and Y axes:

PLOT w /LOG /TAG='(Hz)'PLOT /XAXIS=w /XLOG /XLO=0.01 /XTAG='(rad/sec)' &

x /LOG /LO=0.001 /HI=100 /TAG='Gain'

Further examples of plots are in the example programs in Appendix A. The systemsymbols that affect plots are described in Appendix C.

5.18 PREPARE

FORM: PREPARE name, ..., name

SWITCHES: /CLEAR/A LL

PREPARE specifies the variables whose values are to be recorded on the intermediatedata (RRR) file during subsequent runs. The PREPARE statement is given before aSTART command. These variables can be printed and plotted after the START hasbeen executed and control returned to the ACSL prompt.

Only variables listed by PREPARE are available to the RANGE, PRINT, and PLOTcommands. DISPLAY displays the current values ofanyvariables and/or constants atthe termination of the run. The OUTPUT command is not affected by PREPARE.

Data logging Data is logged on the scratch file at each communication interval (CINT)automatically. Additional logging can be forced with calls to LOGD in the model (seeAppendix B).

Independentvariable

The PLOT programs assume as a default that the X axis variable is the first one on thePREPARE list. The independent variable is not included in the PREPARE listautomatically; it must be explicitly listed to be seen and to be made available for thePLOT programs.

Wild cards Wild cards can be used in specifying the variable list. The asterisk (*) stands for aname with zero or more characters, and the question mark (?) stands for any onecharacter.

PREPARE t,x*,k??

Arrays Array elements can be listed by referring to the specific element; for example, A(3). Ifthe name given is an array, but no specific element is called for, all elements arePREPAREd.

/CLEAR The PREPARE list is cumulative;i.e., additional commands do notcorrectthe list butadd to it. To clear previous lists and start over, use the /CLEAR switch.

PREPARE /CLEAR t,a,v,w(1)

5. ACSL Runtime Commands 5.18 PREPARE


/ALL /ALL adds all the model variables as listed in the debug dump (except for constantsand ACSL dummy variables;i.e., those of the form Znnnnn) to the PREPARE list.

5.19 PRINT

FORM: PRINT name, ..., name

SWITCHES: /ALL/F ILE = 'filename' [model.LOG]/IH I = <real-variable> [RMX]/IL O = <real-variable> [-RMX]/IV AR = <name> [first PREPARE]/NCIPRN = <integer-variable> [1]/NOHEADER [header]/R UN = <integer-variable> [all]

PRINT lists the values of the variables on the PREPARE list in columns after a runhas been completed. The default format is ten columns per page, with line numbersincluded automatically. With the /FILE switch, the default is 999 columns per pagesince in this case the purpose is to create a data file rather than print a page.

PRINT differs from OUTPUT in that OUTPUT operatesduring the run while PRINToperates afterwards. The OUTPUT listing is in blocks rather than columns. PRINTtakes its data from the intermediate data file (RRR) collected during the run.

Logical unit PRN PRINT data is considered high volume and is listed on the PRN logical unit (print file)for later disposal to the printer queue. If HVDPRN (high volume display) is TRUE,the listing also appears on the low volume unit (DIS), usually a terminal.

Width of listing System symbol PCWPRN (printer character width) controls the width of the print file.The default of 132 holds ten columns of PRINT data. For A size paper (81⁄2 x 11 in.),set PCWPRN to 80, which holds five columns. TCWPRN (terminal character width)controls the width of printout to the screen; its default of 80 results in five columns ofPRINT data on the screen if high volume data is directed to the screen.

Wild cards Wild cards can be used in specifying the list of variables. An asterisk (* ) stands forzero or more characters, and a question mark (?) stands for any one character.

PRINT t,k*,?d??

Arrays Array elements can be specified; if an array is named but no element specified, thecomplete array is printed. Assuming X, XD, and XDD to be three-element arrays, thefirst command prints only one element of each array; the second, the complete arrays.

PRINT t,x(1),xd(1),xdd(1)PRINT t,x,xd,xdd

/ALL /ALL prints all the variables on the PREPARE list. Some thought in setting up thePREPARE list can result in more useful printouts; for example, including theindependent variable with each set of data. In the following example, the independentvariable T is first on each line, the first two lines contain three-element arrays and thethird line scalar variables, so three lists of ten columns are printed.

PREPARE t,x,xd,xddPREPARE t,w,wd,wddPREPARE t,k1,k2,q,th,fi,si,switch,zSTARTPRINT /ALL

5.19 PRINT 5. ACSL Runtime Commands


/NCIPRN /NCIPRN (number of communication intervals per print) controls PRINT volume.You may wish to log data at a high rate for plotting, but then print at a lower rate. Forexample, to print every tenth line of logged data:

PRINT /NCIPRN=10 t,x,y,z

It is important that /NCIPRN be given first. In the following example, all the variablesare printedbeforethe PRINT command sees the /NCIPRN qualifier:

PRINT /ALL /NCIPRN=10

This statement should be written:

PRINT /NCIPRN=10 /ALL

NCIPRN is also a system symbol which can be SET or DISPLAYed at runtime. Onceset, NCIPRN stays the same until you change it explicitly.

PRINT window /IHI, /ILO, and /IVAR together establish a window for printing in a region of interest.The window ranges from /ILO to /IHI for the variable /IVAR (any variable on thePREPARE list). The values of the other variables are printed over this window.

PRINT /ILO=20 /ALLPRINT /IVAR=t /ILO=5 /IHI=6 x,y,zPRINT /IVAR=x(1) /ILO=200 /IHI=300 t,w,th

If /ILO is greater than /IHI, the regionoutsidethe window is printed;i.e., in the firstline of the following example, everything in the window from 5 to 7 is printed, but inthe second line, everythingexceptwhat's in the window from 5 to 7 is printed:

PRINT /ILO=5 /IHI=7 x,y,zPRINT /ILO=7 /IHI=5 z,b,c

Once set, /IVAR, /ILO, and /IHI remain the same for subsequent PRINT commandsunless explicitly changed. Respecifying /IVAR resets the values of /ILO and /IHI totheir defaults. The defaults for /ILO and /IHI are -RMX and RMX, respectively, whereRMX is the largest floating point number available on the computer. The default for/IVAR is the first variable on the PREPARE list.

/RUN /RUN extracts data for a specified run if more than one run has been collected on theRRR intermediate data file. Collecting runs is accomplished either by looping fromTERMINAL to INITIAL in the model source code or by executing separate STARTcommands with system symbol NRWITG (no rewind) set TRUE.

PRINT /RUN=3 t,x,y,z

/RUN applies to all the variables specified by the PRINT command. It is not possibleto specify different runs for different (or the same) variables. The RRR file issequential and ACSL makes only one pass to PRINT data (as opposed to PLOT,which makes a pass for each variable being plotted).

/FILE When a PRINT file is specified with this switch, the data is written with a singleheader at the beginning of the file, a column on the left with line numbers, anduninterrupted columns of data. Figure 5-9 shows the results of a command:

PRINT/FILE='testrun.dat' t,x,xd,t

The secondT is just to show that variables can be duplicated if necessary.

Only one set of data is kept in a file. If the same file is specified in a subsequentPRINT command, it is opened and the new data written into it, erasing the old data.

5. ACSL Runtime Commands 5.19 PRINT


/NOHEADER This switch eliminates all headers at the top of the columns of data. The main use isfor importing data into external applications such as Lotus and Excel.

This switch should in general appear first; in particular, itmustprecede /ALL in thePRINT command line to take effect.

Each PRINT command reverts to the default of generating headers unless the/NOHEADER switch is applied again.

5.20 PROCEDURE

FORM: PROCEDURE name [(arg1[=<default-value>] &[,arg2[=<default-value>]] ...)]

... <runtime commands>END

CALLS: namename <arg1val>, <arg2val> ...name arg2=<arg2val>, arg1=<arg1val> ...

A PROCEDURE is a block of commands which begins with the PROCEDUREstatement (with optional arguments and default values) and terminates with an ENDstatement. It is invoked at runtime by calling its name. The commands in the body ofthe PROCEDURE may be any runtime commands, including calls to otherPROCEDUREs. PROCEDUREs can be nested to any level.

PROCEDUREs are defined to avoid repeating long command sequences. They areuseful, for example, in setting up runs and plot sequences.

The PROCEDURE (a runtime statement) should not be confused with thePROCEDURAL, which is used in a sorted section of a model source program.

Names Names of PROCEDUREs may be any legal symbol;i.e., starting with a letter,continuing with letters or digits, and delimited by anything not a symbol (e.g., space,period, etc.). Don't choose a name which is already a runtime command. Since theruntime executive checks PROCEDURE names first and then runtime commands,using a runtime command as a PROCEDURE name means the runtime command cannever be executed. For example, if the following procedure is defined, the short formof the SET command (S) is hidden:

Line T X XD T0 0. 0.50000000 0. 0.1 1.00000000 0.22806700 -0.55097100 1.000000002 2.00000000 -0.52946100 -0.84948000 2.000000003 3.00000000 -1.07931000 -0.08726660 3.000000004 4.00000000 -0.64942700 0.92205200 4.000000005 5.00000000 0.72023700 1.64531000 5.000000006 6.00000000 1.67220000 0.01099750 6.000000007 7.00000000 1.06116000 -1.11657000 7.000000008 8.00000000 -0.60672500 -2.15435000 8.000000009 9.00000000 -1.93461000 -0.08165130 9.00000000

10 9.90000000 -1.45462000 0.96626600 9.90000000

Figure 5-9. Output of PRINT /FILE command

5.20 PROCEDURE 5. ACSL Runtime Commands


PROCEDURE sSET k=0.4,xic=1.0STARTEND

Example An example of a typical PROCEDURE without arguments is:

PROCEDURE goSET NDBUG=2STARTPRINT /ALLPLOT /XAXIS=t n,mPLOT /XAXIS=x y,zEND

Execution The set of commands is saved when defined, but not executed until the PROCEDUREname is given as a command, at which time the entire sequence is executed. Thefollowing commands change a model parameter then run, print, and plot for eachcondition by calling the GO PROCEDURE. These commands could themselves bedefined in a PROCEDURE.

SET a=5.0 ; goSET a=5.5 ; goSET a=6.0 ; go

Arguments Arguments may be specified in the PROCEDURE header, with substitutions indicatedin the body by an ampersand (&), as in the following example:

PROCEDURE df(val)SET a=&val, b=&val, c=&valEND...df 20

Defaults Default values may be given to the arguments, as in this plot command:

PROCEDURE p1(x, lo=0, hi=10)PLOT &x/LO=&lo /HI=&hiEND...p1 Ap1 B, -2, 2

In the first call to this PROCEDURE, the variable to be plotted is named, but thedefault values of HI and LO are used. In the second call, different values are given tothe arguments.

Positional orkeyword

argument calls

In the previous example, the arguments were called in the same order as they had beengiven in the definition. These are calledpositionalarguments. Arguments can also becalled out of order bykeywordassignments; the previous PROCEDURE could becalled with the arguments out of order as follows:

p1 hi=20, x=th

Once a keyword assignment appears on a call line, all the subsequent arguments mustalso be by keyword. The following, for example, is illegal:

p1 y2 /lo=0, 5

Set value andTITLE

A handy way to set a value and include that information in the TITLE array is with theargument to a PROCEDURE.

5. ACSL Runtime Commands 5.20 PROCEDURE


PROCEDURE setk(val)SET k=&val, TITLE(41)="Gain=&val'END

setk 0.7

Use ofampersand in

TITLE string

The ampersand can be used for substituting arguments into the TITLE array and otherstrings; therefore, it cannot also be used simply as a character in a string. In thefollowing example, the first ampersand sets a value, the second sets the informationinto the TITLE array, and the third is illegal, producing the error message.

PROCEDURE run1(val)SET a=&valSET TITLE="Actuator gain = &val"SET TITLE(41)="DB&K simulation"END

Argument K is not defined in procedure header.Replaced by null string

If the procedure is then invoked, the ampersand and the following character aredropped.

run1 5SET a=5SET TITLE="Actuator gain = 5"SET TITLE(41)="DB simulation"

There is no restriction on using the ampersand as a character in strings when thestrings are not inside a PROCEDURE. The line above that produced the error messagewhen inside the procedure, for example, would not be an error if it were simply in acommand file but not in a PROCEDURE.

Display PROCEDURE names, arguments, defaults, and text can be displayed at runtime. SeeDISPLAY for further information.

DATA definition DATA definitions cannot be in PROCEDUREs, but any number of DATA blocks canbe defined, at any time. The appropriate one can be accessed from a PROCEDURE.

5.21 QUIT

FORM: QUIT

The QUIT command tells the runtime executive that no more commands follow andcontrol is to be returned to the operating system.

This command should always be the last command issued so that all the files and plotsestablished by the executive are cleaned up or terminated correctly.

5.21 QUIT 5. ACSL Runtime Commands


5.22 RANGE

FORM: RANGE name, ..., name

SWITCHES: /ALL/IH I = <real-variable> [RMX]/IL O = <real-variable> [-RMX]/IV AR = name [first PREPARE]/R UN [all]/T IMES

The RANGE command determines the maximum and minimum values of variables onthe PREPARE list. A typical sequence of commands is:

PREPARE t, ..., zSTARTRANGE t, ..., z

Wild cards Wild cards can be used in specifying the list of variables. An asterisk (* ) stands forzero or more characters, and a question mark (?) stands for any one character.

Arrays Elements of arrays can be specified. If an array name is given and no element isspecified, the entire array is assumed.

Error message If any name on the RANGE list is not defined in the PREPARE list, an error isreported.

RANGE th,kTH-0.91880100 1.000000000

Can-t find K

/ALL /ALL results in RANGE reporting on all the items in the PREPARE list. RANGE withno list and no /ALL produces no output.

/TIMES /TIMES produces a listing of the times at which the maxima and minima of thevariables occur. For the following command, for example,

RANGE /TIMES th,thd,thdd

the answer is in the form:

TH-0.91880100 AT 0.82500 1.00000000 AT 0.THD-3.69781000 AT 0.40000 3.42172000 AT 1.25000

THDD-13.5477000 AT 0. 12.8163000 AT 0.80000

Windows Windows for sub-ranges may be defined. The independent variable is specified by/IVAR along with its low /ILO and high /IHI to define the test. For example,

RANGE /IVAR=x /ILO=50 /IHI=100 /ALL

would report the maximum and minimum values of all the elements on the PREPARElist when the variable X lies between 50 and 100.

Once set, /IVAR, /ILO, and /IHI remain the same for subsequent RANGE commandsunless you change them explicitly. Respecifying /IVAR resets the values of /ILO and/IHI to their defaults. The defaults for /ILO and /IHI are -RMX and RMX,respectively, where RMX is the largest floating point number available on themachine. The default for /IVAR is the first variable on the PREPARE list.

Switch order The /TIMES and /IVAR switches must be given before the list of variables (in a left toright scan) so that the value of IVAR at the maximum and minimum can be found; forexample, use /TIMES before /ALL as follows:

5. ACSL Runtime Commands 5.22 RANGE


RANGE /TIMES /ALL

/RUN /RUN extracts data for a specified run if more than one run has been collected on theRRR intermediate data file. Collecting runs is accomplished either by looping fromTERMINAL to INITIAL in the model source code or by executing separate STARTcommands with system symbol NRWITG (no rewind) set TRUE.

RANGE /RUN=3 x,y,z

/RUN applies to all variables specified in the RANGE command. It is not possible tospecify different runs for different (or the same) variables. The RRR file is sequentialand ACSL makes only one pass to access RANGE data (as opposed to PLOT, whichmakes a pass for each variable being plotted).

5.23 REINIT

FORM: REINIT

REINIT (REINITialize) writes the current values of the state variables into theircorresponding initial conditions, thereby destroying the original initial conditions.

For example, this command could be used for a missile flight, where the simulation isstopped just before the terminal phase. This point is then established as the startingpoint for subsequent runs. The runtime command sequence could be:

SET tstop=30START ! Run through flight midcourseREINIT ! Establish initial conditions at this pointSET tstop=50 ! Otherwise run will stop again immediatelySTART ! Run terminal phase of flightSET rtic(1)=50000 ! Change target positionSTART ! Run terminal phase again

With SAVE andRESTORE

The SAVE command can be used to save the original conditions if needed:

STARTSAVE /FILE='state1' ! Saves original initial conditionsREINIT

The saved files can then be called in by RESTORE to restore the desired initialconditions. This can be useful in restarting the whole problem since REINIT changesthe entire initial condition table and it can be difficult otherwise to get back to theoriginal point in state space.

Calculated initialconditions

If initial conditions are calculated in the INITIAL section, you need a provision forskipping over this code after REINIT; otherwise, the current state values, which aremoved into the initial condition vector by REINIT, are recalculated after the START.For example, code in the model could be in following form:

INITIALLOGICAL reinitf ; CONSTANT reinitf=.FALSE.IF(reinitf) GO TO skipin... [INITIAL section calculations]

skipin..CONTINUE

Then at runtime, the following commands result in the calculations being skipped:

5.23 REINIT 5. ACSL Runtime Commands


REINITSET reinitf=.TRUE.START

Initial conditionsin operators

Initial conditions in operators (DELAY, EXPF, etc.) must be given variable namesrather than be expressed in literal constants (0.0, for example) in order for theoperators to work with REINIT. REINIT can write the new initial condition into avariable name, but not into a literal constant.

REINIT versusSAVE/RESTORE

For simple models without DISCRETE sections or events, START/REINIT/START isstraightforward and usually sufficient. For more complex model, however, it isprobably better to use START/SAVE/RESTORE/CONTINUE.

CONTINUE notallowed after

REINIT

CONTINUE should not be used after REINIT. CONTINUE causes certain operatorsto continuously reinitialize themselves by computing their initial conditions until aSTART occurs.

5.24 RESTORE

FORM: RESTORE [name, ..., name]

SWITCHES: /[NO]E VENTS [/NOEVENTS]/F ILE = 'filename'/S TATES

The RESTORE command restores data by variable name from an external file that hasbeen generated by a SAVE command. The variable list is optional, but a file namemust be specified. The default file name for SAVE is ACSLSAV.

Warningmessages

If no list of names is given, then RESTORE reads each variable from the given filewith its associated data value, looks it up in the model dictionary, and then replacesthe current value with the value from the file. Names with no match are identified bythe message:

No match in model for file variable AAAAAA

If not all variables are restored, the untouched ones are identified by:

No restore for model variable AAAAAA

Wild cards Wild cards can be used in specifying the variable list. An asterisk (*) stands for zero ormore characters, and a question mark (?) stands for any one character.

/STATES /STATES specifies restoring only the state variables defined by integration statements.There is no check thatall the state variables inthis model have been restored; ACSLreads in the names on the file that correspond to state variables in the current model.

/EVENTS /EVENTS specifies restoring the event list if one was saved on the file. /NOEVENTSignores any event list on the file. If the event list is restored, it is usually possible toCONTINUE from the restored situation.

File format The /BINARY and /ICS switches used with the SAVE command are not needed withRESTORE. ACSL senses the file format and handles it appropriately, and the initialconditions restore automatically from the file.

5. ACSL Runtime Commands 5.24 RESTORE


Examples Following are examples of typical RESTORE commands.

RESTORE /FILE='acslsav'RESTORE /FILE='case1.bin' /STATES /NOEVENTSRESTORE /FILE='gains.sav' k*RESTORE /FILE='mysave.asc' a,v,x,w /EVENTS

5.25 SAVE

FORM: SAVE [name, ..., name]

SWITCHES: /[NO]B INARY [/BINARY]/E VENTS/F ILE = 'filename' ['ACSLSAV']/I CS/S TATES

SAVE saves the user's data block on an external file. The variable list is optional. Thedefault file name is ACSLSAV.

The runtime SAVE command should not be confused with SAVE when used in aprogram. In the program, SAVE writes macro definitions to a macro file.

Defaults If no variable list is specified, all model variable values are written to the file,including initial conditions and states. If noswitchesare given, events are notincluded. If a variable list is specified, initial conditions and states are not added.

Modified model Variables are saved by name and value so that on RESTORE they are brought back tothe same location even though the model may have been changed.

Znnnnn variables One potential problem when a model has been modified between the SAVE andRESTORE is in the saving of internal ACSL variables;i.e., those of the form Znnnnn(Z99987 for instance). These variables are also saved and restored. A change in themodel, while keeping the model names intact, can result in a reordering of theseinternal variables. If the internal variables names have changed, RESTORE couldbring data values back into the wrong locations.

/NOBINARY /NOBINARY results in the data being written out as a text file. The advantage of thetext file is that it can be read and edited. The disadvantage is that decimal fractions cannever be represented exactly on a binary machine, so a subsequent RESTORE bringsback numbers that are slightly different from the values at SAVE time. If /BINARY isin effect, then the RESTORE is exact, but the file produced cannot be listed or edited.

/NOBINARY must be specified with each SAVE command for which it is desired.

/STATES /STATES specifies saving only the state variables defined by integration statements.Other state variables arenotsaved. These are for example when a variable isaccumulated in the form:

x = x + dlx

/ICS /ICS specifies saving only the initial condition names corresponding to the namesdefined by integration statements. These are sometimes more meaningful than the statenames. Initial conditions defined as literal constants (0.0 for example) are assignednames in the form Znnnnn and are not restored by /ICS.

5.25 SAVE 5. ACSL Runtime Commands


/EVENTS /EVENTS specifies adding a copy of the event list at the end of the file. /BINARYmust be in effect when using /EVENTS. Including the event list on the SAVE file isimportant if SCHEDULE statements or DISCRETE sections are used in the model.

Examples Following are examples of typical SAVE commands.

SAVESAVE /FILE='case1.bin' /EVENTSSAVE /FILE='mysave.asc' /NOBINARYSAVE /FILE='gains.sav' k*,x*,y*SAVE /FILE='case3' /STATES /ICS /EVENTS

5.26 Separator (;)

The command separator is the semicolon. More than one command can be written onthe same line, as, for example:

SPARE ; START ; SPARE

Comments can be placed only after the last command since everything after anexclamation point (!) is ignored by the runtime executive.

SET k1=0.5 ; START ; DISPLAY x,xd ! Case 1

5.27 SET

FORM: SET name = <matching-variable> [, name = ...]

Data can be set into any known constant, array, or variable by the SET command;however, normally it is used only for constants, either system symbols or modelvariables defined in CONSTANT statements.

Data type The data type must match the type of the symbol (i.e., REAL, DOUBLEPRECISION,INTEGER, LOGICAL, CHARACTER), except that integer values may be set intoreal variables (automatic floating point conversion takes place). Single precisionnumbers are automatically changed to double and vice versa as required. Integervalues must not have a decimal point, and logical variables can be only .TRUE. or.FALSE. (short forms .T. and .F.).

Once set, a variable holds its value until explicitly changed by another SET commandor, after a START, by code in the model.

Arrays Individual elements of arrays can be set. Arrays can also be filled by a data list, wheresucceeding data items will be stored in subsequent array slots. Attempting to exceedthe array length results in a diagnostic message. In the following example, B has fiveelements:

SET a(2)=5.5SET b=3*4.5,6.7,5.4,2.1Reference out of limit of array B

Arrays can have up to six dimensions, and they can be accessed with the dimensions;for example:

SET b(3,5)=8.5

5. ACSL Runtime Commands 5.26 Separator (;)


Symbolic data Data can also be obtained from another symbolic location by using the symbol name:

SET rm1=rng, rmt=rng

This statement results in the variables RM1 and RMT containing the value of thenumber stored in the symbol RNG after execution. This concept is useful if a data itemmust be stored in many places; it can be stored by value once and then picked up byname subsequently, so the value need be changed in only one place.

Array elements can also be accessed symbolically as well as by number; for example,assuming KBOIL contains an integer 3, the following are synonymous:

SET gain(kboil)=0.3SET gain(3)=0.3

Character data Character data can be set into a symbol or array that is of type character. Generallyonly the system array TITLE uses character data.

TITLE The TITLE array can be accessed as one long string or as a series of characters. Thenumber of characters in the TITLE array has a default of 120 but can be expanded toas many as 480 with system symbol NCTPRN.

One advantage to accessing separate characters in TITLE is to change selectedportions for different runs while leaving others the same from run to run. For example:

SET TITLE='Project XYZ Simulation ABC'SET TITLE(41)='09/09/99'SET TITLE(61)='Gain=5'START ; PRINT /ALLSET gain=10, TITLE(61)='Gain=10'START ; PRINT /ALLSET TITLE=120*' ' ! Erase title

The TITLE can be erased by setting it (or portions of it) to blanks. In the last lineabove, a space is required between two single quotes to indicate a blank.

DCVPRN To confirm a variable as it is modified by a SET command and reinforce that the valuebeing changed is really what you thought, both the old and new values are listed whensystem symbol DCVPRN (Display Changed Variables) is TRUE. For example:

SET DCVPRN=.T.SET y1z=3, y2z=4, xarray(2)=3.1

Y1Z (Old value) 2.50000000 (New value) 3.00000000Y2Z (Old value) 3.70000000 (New value) 4.00000000

XARRAY(2) (Old value) 2.80000000 (New value) 3.10000000

Examples Typical legal SET commands include the following:

SET nstp=10, rm(1)=5.6E3, mass=4.6, gain=5.2D2SET logvar=.TRUE., array(5)=4.3, switch=.T.SET array(2)=2.0,3.0,4.0, tstop=9.99, count=20 &

,TITLE='Doppler Study', array(6)=5*0.0

5.27 SET 5. ACSL Runtime Commands


5.28 SPARE

FORM: SPARE

The SPARE command is provided to link to a user-supplied runtime subroutine namedSPARE. A default subroutine provided by ACSL lists the central processor time, bothaccumulated from the start of the run and elapsed since the previous use of SPARE.SPARE is useful for timing simulation execution. Execution of the default subroutineresults in output in the following form:

SPAREACCUMULATED CP TIME nnn.nnn SEC. ELAPSED CP TIME nnn.nnn SEC

The accumulated time is normally the time from the beginning of the job; the elapsedtime is the incremental time from the previous invocation of SPARE. The ELAPSEDCP TIME resulting from the following sequence shows the simulation execution time:

SPARE ; START ; SPARE

When a user supplies a subroutine called SPARE, the SPARE runtime commandexecutes the user subroutine rather than ACSL's. A user subroutine such as thefollowing could be used to create a new runtime command implemented by asubroutine called, for example, "foo":

SUBROUTINE spareCALL fooRETURNEND

The runtime sequence then could be:

PROCEDURE fooSPAREEND

5.29 START

FORM: START

SWITCHES: /CHARACTER = '<character>' ['<blank>']or = <integer-variable>

/H I = <real-variable> [1.0]/L O = <real-variable> [0.0]/P LOT/R ESCALE/T YPE = ijk [000]

The START command starts execution of the simulation model. It allows the model tointegrate over the state trajectory.

With the START command, control is handed over to the model definition at the topof the INITIAL section. All states are given their initial conditions at the end of theINITIAL section. The DERIVATIVE and DISCRETE sections are evaluated in order,the DYNAMIC code is evaluated, then integration begins.

The simulation is allowed to run until a termination condition (usually defined in aTERMT statement) is met. Finally, the TERMINAL section is executed once before

5. ACSL Runtime Commands 5.28 SPARE


control is returned to the runtime executive for the next runtime command. A typicalsequence for executing a run is:

PREPARE t,x,xd,xddOUTPUT t,x,xd /NCIOUT=20START

Switches The switches for START control plotting of variables on the OUTPUT listduringasimulation run. This is different from the PLOT command, which operates only afterthe run has been completed and control returns to the ACSL prompt.

All the switches except /PLOT and /RESCALE follow the name of a variable. Thevariable must also have been specified on the OUTPUT list. Once values have beensspecified, they remain in effect until explicitly changed. The values established by/RESCALE also remain in effect until explicitly changed. However, /PLOT must bespecified for a plot to be generated; otherwise, numerical data appears.

/PLOT /PLOT specifiesplotting the variables on the OUTPUT list (rather than printing thenumeric values). The first variable on the OUTPUT list is plotted as the X axis; aseparate Y axis is drawn for each other variable on the list. At least two variables mustbe present for a plot to be drawn.

Scales Scales are established by switches on the OUTPUT statement but can be modified atthe START (or CONTINUE) command. If /RESCALE is specified, the maximum andminimum values for each variable from the previousplottedrun are converted toround numbers for the current scale factors. /HI and /LO must follow a variable name;they specify the plot scales for that variable.

OUTPUT t,x,ySTART /PLOTSTART /PLOT /RESCALESTART /PLOT t/HI=10, x/LO=-4/HI=4, xd/LO=-20/HI=20

/CHARACTER /CHARACTER specifies a character to be drawn on the curve at NPCCPL data points.

START /PLOT x/CHARACTER=1START /PLOT u/CHARACTER='U',v/CHARACTER='V',w/CHARACTER='W'

/TYPE /TYPE specifies line color, width, and style (solid, dotted, dashed), as described underPLOT. /TYPE results are device-dependent.

Plot controls The system symbols for line plots (i.e., those ending in CPL) can be used to controlsuch characteristics as axis length, plot scale factor, etc. See Appendix C fordescriptions of the system symbols.

5.30 SYSTEM

FORM: SYSTEM [<operating-system-command>]

The SYSTEM command allows escape to the computer operating system on systemswhich allow such a procedure. The command accepts any character string.

If an operating system command is specified with the SYSTEM command, control isreturned to the ACSL runtime prompt when the command has completed execution.On most systems, the SYSTEM command with no arguments spawns a subprocessfrom which general computer commands can be issued.

5.30 SYSTEM 5. ACSL Runtime Commands


As an example, a command file could be edited on a VAX system as follows:

SYSTEM edit model.cmd

On PCs, the SYSTEM command opens a DOS window.

SYSTEM commands can be included in PROCEDUREs, which allows, among otherbenefits, system tasks to be given short names; for example, the above command couldbe stored in a PROCEDURE and executed:

PROCEDURE ed(name)SYSTEM edit &nameEND...ed 'model.cmd'

5.31 Wild cards (* and ?)

An asterisk (* ) or a question mark (?) in a name is a wild card. The asterisk stands fora character string of zero or more characters, and the question mark stands for any onecharacter. For example, to display all symbols starting with aK includingK itself ifpresent (K followed by zero characters), use:

DISPLAY k*

Wild card matches search both user and system dictionaries, which is useful foraccessing groups of system symbols. To find all six-character symbols ending in PLT:

DISPLAY ???plt

Other runtime commands that accept wild cards are:

OUTPUT PREPARE PRINT RANGE RESTORE

For the PREPARE command, constants and dumy variables (Zaaaaa) are excluded inthe wild card match.

5.32 XERROR

See MERROR.

5. ACSL Runtime Commands 5.31 Wild cards (* and ?)


6. Macro Language

6.1 Introduction

ACSL's macro capability allows you to expand the language by defining newoperators. These operators are called from the program, usually with arguments. Fromthe macro directives, the translator generates the code for compilation. Code isgenerated each time the macro is called. Usually the code is slightly different witheach call (because of arguments resulting in different variable names, for example).The generated code is often referred to as a macro expansion.

Macros are useful for standardizing certain functions for an industry or discipline.Macros can also be used to capture special expertise for other users to incorporate intotheir programs.

Macro versussubroutine

A macro is similar to a subroutine or function in that it is defined once and theninvoked as many times and as from as many places in the model code as needed. Thetranslator produces a set of statements in the Fortran compile file for each macroinvocation, but the extra storage used for such statements is usually small. Macros areslightly more efficient than subroutines or functions and have the advantage of beingable to define operators involving integrators and memory functions.

Macros are used rather than Fortran subroutines if any ACSL operators are involved,or to gain visibility of internal variables. Concatenation is another reason to usemacros. It allows the generation of unique variables for each application of a macro,and the values of these variables are available for printing and plotting.

Placement ofdefinitions

Macros can be defined two ways. They can be defined in the program in which theyare called, before the first invocation (notat the end of the program like subroutines).

Alternatively, definitions can be in a separate program containing only the macros; theprogram concludes with a SAVE statement (see Chapter 4) that saves the macros tothe current macro file. Since the procedure for writing a user macro file variesdepending on the computer system, it is described in the documentACSL Sim User'sGuide. In general, make a local copy of the system macro file and specify this localcopy as the macro file for the program to save macro definitions. On some systems,this file must be given WRITE permission. The macro definitions areaddedto the file(i.e., they are cumulative), so generally you will want to start with a fresh copy of thesystem macro file. Only translation is required, so stop the ACSL build procedurebefore compilation.

Examples For two examples of macros using integrators, see the Physiological Benchmarkprogram in Appendix A. Other examples are found at the end of this chapter.

Features Some of the more important features of the macro language are:

1) Variables and statement labels may be locally generated. In the event the macro iscalled more than once, this prevents multiply defined variables or labels.

2) An unlimited number of macro input arguments may be used. These argumentsmust be valid expressions (of arbitrary complexity) with balanced parenthesesand any character string enclosed in quotation marks.


3) Macro definitions mayinvokeother macros to an unlimited level of complexity.Note, however, that macrodefinitionsmay not be nested. Nesting macrodefinitions would require a count of nesting level within the definition to matchup with the correct MACRO END; such a count is not performed and the firstMACRO END terminates the definition.

4) Macros may be placed anywhere within an ACSL program, but they must bedefined before they are used. A macro may be redefined; the most recent versionis used in the expansion.

5) The concatenation operator (&) allows arguments to be placed together withoutintervening spaces, a useful way of making up variable names.

6) Macro definitions can include INITIAL and/or TERMINAL sections.

Forms of call Macros can be called in three ways. The second form, called standalone, is generallypreferred. The third form is must be used with more than one output.

y = MAC(x)MAC(y = x)MAC(y,z = x)

Concatenation The ampersand (&) is the concatenation operator that allows a substitutable argumentto appear next to a character string. Its use is discussed in more detail under MacroDefinition Header. In general, it enables generation of unique names with multiplecalls to a macro. For example, variable V1 is accessed in the following expansion:

MACRO abc(x)y = v&x

MACRO ENDabc(1)...y = v1

The substituted name must be separated from any other characters by either a space oran ampersand. No substitution would take place in the following situation:

MACRO abc(x)y = v&xgh

MACRO END

An additional ampersand after the X, however, sets it off so it can be substituted:

MACRO abc(x)y = v&x&gh

MACRO ENDabc(2)...y = v2gh

INITIALDYNAMIC

DISCRETETERMINAL

INITIAL, DYNAMIC, DISCRETE, and TERMINAL sections can be used in macrodefinitions. The translator collects all the code in the order presented (or expanded inthe case of macros). These sections are not sorted unless the SORT keyword isspecified.

Arguments Argument strings are substituted for each appearance of the macro argument name. Ifthe argument is an expression, care must be taken that the resulting code is correctafter the substitution (see the section on macro calls). Other names that may besubstituted during macro expansion are the ASSIGNed variable (see MACROASSIGN), local variable names identified by a REDEFINE (see MACROREDEFINE), and local labels identified by a RELABEL (see MACRO RELABEL).

6. Macro Language 6.1 Introduction


Warning –use of DO

Substitutable symbols on the left side of an equal sign in a macro definition should notbegin withDO. The problem with usingDO is that the ACSL translator, when it is in amacro definition, looks for substitutable strings, but in order to prevent substitution ofDO, it checks for leading characters in this form. Unfortunately, Fortran syntax doesnot require spaces, so:

DO100 = 1, 5

is an acceptable form, and ACSL also cannot assume that a space will be used to setoff the DO construct. ACSL thus does not make the expected substitution when thename begins withDO.

Warning –substitution errors

Another potential area for error in substitution is the use of the same name in differentcircumstances. In the following macro, for example:

MACRO test(L, x)MACRO RELABEL L1, form

IF(x .GT. 0.0) TO TO L1WRITE(6, form) LL1: CONTINUEform: FORMAT(1X, L1)

MACRO END

The FORMAT statement becomes:

99998 FORMAT(1X, Z09996)

which is invalid.L1 in the FORMAT should not have been substituted. Fix this bychanging the label name to a unique character string.

Two types of macrodefinitions

The section on the macro definition header describes the two types of macros that canbe defined. The first type is preferred for most applications and accepts variable namesas arguments. The second type is useful for handling arrays and can be identified byheaders starting MACRO MACRO.

6.1 Introduction 6. Macro Language


6.2 Macrodefinitions

The macro definition is a block of code that consists of the following:

1) Macro definition header2) Macro directive or ACSL statements3) MACRO END

The macro definition header specifies the name of the current definition and a list ofdummy reference parameters, analogous to dummy arguments in a Fortran subroutine.The translator scans the statements in the macro body for the appearance of thesenames, flagging them for substitution by the actual argument supplied on invocation.The definition terminator, MACRO END, must be present to flag the translator toreturn to direct translation. The translated macro body with arguments substituted isreferred to as the skeleton.

If a macro name is the same as one already defined, either in the system macro file orthe current model definition, the new macro definition replaces the old one. No errormessage is issued since this is considered to be a feature whereby you can alwaysoverride an old macro definition.

6.3 Macrodefinition header

FORM: MACRO identifier(x 1, x 2, ..., x n)MACRO MACRO identifier(p, q, r, s)

whereidentifier is the macro name,xi are variable names, constants, or expressions,pis the primary argument specifying an array of input expressions, andq, r, andsaresecondary arguments giving the names of array dimensions within the macrodefinition. The argumentsp, q, r, andsmay be any unsubscripted variable name. IfPis the name of the argument of a MACRO MACRO, then you must not use a variablenamedP in the macro.

First type For its relative simplicity, the first type of macro is preferred for most purposes.Anywhere the string of charactersxi is referred to in the macro definition, it will bereplaced by the ith argument (symbol or expression) when the macro is invoked;e.g.,

MACRO mult(x, y, z) ! definitionx = y*zMACRO ENDc = a*mult(5.0*b, d) ! invocation

In this example, the output of the function is the first argument (X); X does not appearexplicitly in the invocation.Y is replaced by5.0*B andZ by D everywhere throughoutthe definition.

Second type The second type of definition is useful when handling arrays of indefinite size. Thisform has an extra MACRO in the header.

Arguments forsecond type

The argumentp is the dummy reference parameter and may be thought of as a vector,each element of which identifies the respective element in the argument list atinvocation time. You specify onlyp in the invocation. The secondary argumentsq, r,andsappear, if needed, in the definition header and may be used in the macrodefinition, but do not appear in the invocation argument list. Elements ofp that are

6. Macro Language 6.2 Macro definitions


arrays must be dimensioned prior to the macro invocation. Argumentsq, r, andsmayalso be thought of as arrays, but only those elements corresponding to arrays in theparray contain values. They refer to the first, second, and third dimensions, respectively.

MACRO MACRO head(p, q, r, s) ! definition... definition statements ...MACRO ENDDIMENSION b(9), g(2, 3), h(4, 4, 2)head(a , b = 5*d, e+f, g, h, low) ! invocation

Arguments at invocation time are delimited by either commas or an equal sign. Thus,in this example,P(1)appearing in the definition body is substituted by the symbolA,the first argument, at invocation time.P(4) is replaced by the expressionE+F, thefourth argument.

Any reference toQ for an array accesses the first dimension. In the example above,Q(2)has the value 9 from the dimension of B in the previous DIMENSION statement,butP(1), P(3), P(4), andP(7)are not dimensioned arrays, soQ(1), Q(3), Q(4), andQ(7)are scalar have a dimension of one.

Symbols substituted for the secondary argumentsRandSact similarly toQ exceptthey provide the second and third dimensions respectively; for example,R(5) is 3 andS(6)is 2.

Note that macros written in this second form are extremely hard to read since nomnemonic symbols can be used for the arguments. The array expressions are restrictedto the following forms:

1) P(i) wherei is a literal integer constant2) P(n)wheren is the ASSIGNed variable3) P(n±i), combination of the above.

Substitutablesymbols

In general, the substitutable symbols must be separated from other character strings bynonalphanumeric characters (i.e., *, +, -, blank) or the concatenation symbol (&) inorder for the scan to operate. If the above macro MULT contained the statement:

ASSIGNz TO k

the symbolZ would not be identified for substitution. Here the space is all important,so the correct form is the following:

ASSIGN z TO k

Concatenation The concatenation operator is defined to allow the substitutable argument to appearnext to a character string. This operator is the ampersand (&). It serves as a separatorfor symbol identification, but is removed entirely when the macro is translated into theskeleton. As an example, consider generating unique symbols by adding anF to thethird argument of the MULT macro and including it in an expression. The new namewould be writtenF&Z (F concatenated withZ); i.e.,

X = Y*F&Z

Invoking the MULT macro with:

a = mult(sam, joe)

results in the statement:

A = SAM*FJOE

6.3 Macro definition header 6. Macro Language


where the new symbolFJOEhas been defined. The above call MULT enters a symbolJOEon the symbol table. If only the made up symbols are important, the argumentmay be quoted using double quotes as:

a = mult(sam, "joe")

In this case, the same expression is generated but now the symbolJOE is not beentered in the symbol table. The argument in double quotes has the quotes removedand the literal string of characters (including any blanks) is substituted for theappropriate argument symbol.

6.4 Macrodirectivestatements

The following section lists in alphabetical order the macro directive statements thatmay be included within a macro definition. No code results from these statements, butextremely flexible control of the macro processing at invocation time is possible. TheACSL statements themselves produce code, and symbols in the statements aresubstituted for the appropriate argument at invocation time. All these directivestatements begin with the word MACRO to indicate that they are instructions to themacro processor.

Labels All macro directive statements can have labels attached to them; the labels can be usedby MACRO GO TO and MACRO IF directives. These labels must be distinct fromany labels attached to nondirective statements. The label is inserted after the leadingMACRO of the directive;e.g.,

MACRO s1: RELABEL iMACRO s2: CONTINUEMACRO s3: END

Note that these labels control the sequence of the macro processor at macro invocationtime. The labels on nondirective statements control the sequence at runtime execution.

6.4.1 MACRO ASSIGN

FORM: MACRO ASSIGN n

wheren is a symbol (usuallyN is used). The ASSIGN directive assigns the number ofarguments in the macro call to the variableN; N is always an integer. If the dummyreference parameter contains a variable subscript, the variable must be the same as thevariable used in the ASSIGN statement. WheneverN is used as part of the dummyreference parameter subscript, the current value ofN refers to the Nth argument in themacro call list at invocation time. For example, using the second header type:

MACRO MACRO sam(P) ! definition

MACRO ASSIGN n...MACRO ENDsam(x, y, z) ! invocation

Within the macro definition,N is 3 since the invocation to SAM contains threearguments, and therefore:

6. Macro Language 6.4 Macro directive statements


p(n) = Nth argument, which iszp(1)(N) = x(3)

p(n-1)(N) = Nth element of the (n-1) argument;i.e., y(3)

6.4.2 Arithmetic macrodirectives

FORM: MACRO INCREMENT iMACRO DECREMENT iMACRO MULTIPLY iMACRO DIVIDE i

wherei is an unsigned integer constant, the secondary arguments (p, q, r, s) of thesecond type of macro, or a macro argument name that has a literal numeric integervalue.

These directives provide arithmetic operations on the ASSIGNed variableN. Thevalue ofN may be added to, subtracted from, multiplied, or divided. All arithmeticoperations are performed in fixed point integer. For example,

MULTIPLY 0

makes the ASSIGNed variable zero. To make the ASSIGNed variable equal to thedimension of the second argument, the following code can be used:

MACRO MACRO bil(p, q)MACRO ASSIGN nMACRO MULTIPLY 0MACRO s1: IF(n = q(2)) s2MACRO INCREMENT 1MACRO GO TO s1MACRO s2: CONTINUE

On exit from this section,N (the assigned variable) has the integer valueQ(2), thedimension of the second argument. In this wayN can be used as a counter or controlvariable in addition to its basic purpose of transmitting the number of arguments fromthe invocation.

6.4.3 MACROCONTINUE

FORM: MACRO CONTINUE

This macro directive is included so that it can be labeled, as, for example,

MACRO L1: CONTINUE

The MACRO IF or MACRO GO TO can then branch to this section within thedefinition.

6.4.4 MACRODECREMENT

SeeArithmetic macro directives.

6.4 Macro directive statements 6. Macro Language


6.4.5 MACRO DIVIDE


6.4.6 MACRO EXIT

FORM: MACRO EXIT

The EXIT directive statement stops the generation of code at invocation time. Theaction is the same as using a MACRO GO TO that transfers control to the macrodefinition terminator (MACRO END).

MACRO EXIT in a PROCEDURAL block can result in translator errors because theEND statement will be missing from the PROCEDURAL block.

6.4.7 MACRO GO TO

FORM: MACRO GO TO s

wheres is a statement label attached to another MACRO directive. The GO TOprovides an unconditional branch to a labeled macro directive within the definition.

6.4.8 MACRO IF

FORM: MACRO IF(e1 = e2) s

wheres is a macro directive statement label ande1 ande2 can be the dummy referenceparameters corresponding to the call list, integer constants, character strings, or theidentifier used in the ASSIGN directive. They must not be expressions. The IFdirective provides for a conditional branch to the macro directive labels inside thecurrent definition if the relatione1 = e2 holds. The stringse1 ande2 are testedcharacter by character (excluding blanks) for equality.

In order to compare a character string with a string passed as a macro argument, thestring must be enclosed in quotes when the macro is invoked and then the MACRO IFcompares the argument with an unquoted string;i.e., if the definition is as follows:

MACRO test(arg)MACRO IF(arg = top) LAB1...MACRO LAB1: CONTINUEMACRO END

and the invocation is:

test("top")

then the macro will expand via LAB1.

6.4.9 MACROINCREMENT




6.4.10 MACROMULTIPLY


6.4.11 MACRO PRINT

FORM: MACRO PRINT any character string except $ or ;

Error messages may be handled within the macro at invocation time by this PRINTdirective statement using any a string of any characters except the dollar sign ($) orsemicolon-colon (; ). This directive lists the character string on the output device. Itwill override any global list control. The primary use is for you to diagnose your ownerrors at invocation time and print out informative messages.

The messages appear with the word "WARNING" at the beginning for easier locating.they can be suppressed by invoking ACSL with the /NOWARNINGS switch (-w onUnix systems).

6.4.12 MACROREDEFINE

FORM: MACRO REDEFINE v1, v 2, ..., v n

wherevi are variable names appearing in the body of the macro. REDEFINE identifiesthe variables as being locally defined and specifies that they are to be replaced byunique symbols at each invocation. The generated variables consist of the letter Zfollowed by five digits.

The MACRO REDEFINE statement should appear before any statements whichreference the redefined variables, including type declarations.

6.4.13 MACRORELABEL

FORM: MACRO RELABEL 11, 1 2, ..., 1 n

whereli is an alphanumeric label (i.e., starts with a letter although it may containnumbers after the first character). RELABEL specifies that all symbols in the list arelocally defined statement labels which are to be substituted by unique generated labelsat invocation time. These labels must be attached only to ACSL statements, not macrodirective statements (statements beginning with the word MACRO).

The following RELABEL statement is illegal because the label name begins with anumber:

MACRO RELABEL 110

It could be replaced by the following statement:

MACRO RELABEL L110

6.4 Macro directive statements 6. Macro Language


To relabel within a macro loop, call another macro from within the loop; for example:

MACRO MACRO test(p)MACRO ASSIGN n...MACRO L1: CONTINUEMACRO IF(n=5) L99

mac2(p(n))MACRO DECREMENT 1MACRO GO TO L1MACRO L99: CONTINUE...MACRO mac2(arg)MACRO RELABEL xyzMACRO REDEFINE k

DO xyz k=1,25... statements that use argxyz: CONTINUE

MACRO END

6.4.14 MACROSTANDVAL

FORM: MACRO STANDVAL arg1 = c1, arg 2 = c2 ...MACRO STANDVAL P(i) = c1, P(j) = c 2, ...

whereargi are dummy argument names andci are literal constants that can be real(single or double precision), integer, or logical. In the second form,i andj areunsigned integer constants.

The STANDVAL statement is used to provide standard values for arguments of amacro. If the specified argument is not given in the macro call, then the constant isused in its place.

Omitted arguments For arguments to be omitted from an argument list, they must be at the end of the list.

Placement The STANDVAL directive must immediately follow the macro header in thedefinition if it is used at all.

Example Several of the ACSL operators use this statement. The operator for the second ordertransfer function (complex pole), for example, begins as follows:

MACRO cmpxpl(y, p, q, x, ic1, ic2)MACRO STANDVAL ic1=0.0, ic2=0.0...

A call to this operator in the model source code then need not specify the two initialconditions if they are to be zero:

CMPXPL(y = t1, t2, yp)



6.5 Macroexamples

The following examples of macro calls demonstrate some of the uses of the directivestatements and of direct parameter substitution.

6.5.1 Sampler

A sampler can be built up of a switch and two zero order holds; for convenience, theentire sequence can be embedded in a macro and invoked as a function. Theinvocation could be:

sample(y = dl, x, yic)

where the sample is repeated everyDL of the independent variable,X is the variable tobe sampled, andYIC is the initial value ofY. A macro to handle this could be definedas follows:

MACRO sample(samp, dl, x, ic)MACRO REDEFINE d, dtINITIAL

samp = icENDDISCRETE d

INTERVAL dt=0.0dt = dlsamp = x

ENDMACRO END

Note that the output name must always be included in the argument list. (Thisrequirement for macros is distinguished from Fortran functions, where the single resultis returned into the name of the function.) At the sample time, the DISCRETE sectionis executed. This action saves the input valueX as output valueSAMP, which issubstituted with the appropriate name from the macro invocation.

6.5.2 Dot product

The following call could be used to take the vector dot product of two arraysA andB:

x = DOT(a, b)

whereX is a scalar andA andB are vectors previously dimensioned in a DIMENSIONstatement. Since it is a function and thus has one output, the operator can be embeddedin an arithmetic expression of arbitrary complexity. The dimension of the vectors maychange, so it should not be specified in the call.

Second type The second form of the macro header is required in order to handle the arraydimension. See Figure 6-1 for a listing of a DOT macro. The header designatesP asthe primary variable andQ as the secondary variable;Q accesses the dimension of thecorresponding primary argument.

REDEFINE The REDEFINE statement ensures the variable I will not conflict with any other use.If this were omitted, a program variableI could have its value changed when themacro is executed, a potentially disastrous effect.

6.5 Macro examples 6. Macro Language


Dimensions The test ofQ(2)andQ(3) is needed to see if the second and third arguments have thesame dimension; if not, the DOT product is undefined and a macro error message isprinted. If the dimensions are correct, the DO loop summation is formed. Note thatQ(2)andQ(3)are replaced at invocation time (as distinct from execution time) byintegers corresponding to the array size of the respective arguments.

MACRO IF The MACRO IF must branch to another macro directive statement, hence the label isattached to a MACRO CONTINUE. This label can not be attached to the followingstatement since it is not a macro directive statement but an assignment statement.

Expansion At invocation time, the variableI is changed into a unique translator-generatedvariable (Z99999). The call shown in Figure 6-1 results in the macro being translatedinto the following code:

INTEGER Z99999X = 0.0DO 99999 Z99999 = 1, 1099999 : X = X + Y(Z99999)*Z(Z99999)

If the call to DOT is embedded functionally in an expression, this code precedes theexpression evaluation and a translator-generated variable in the form Znnnnn is usedin the expression for the output variable name.

6.5.3 Pressure tank

This pressure tank example illustrates the use of concatenation in macros. A similarexample (physiological benchmark PHYSBE) appears in Appendix A.

Concatenation One of the problems with using macros is the tendency to generate large numbers ofdummy variables (Znnnnn) which have no mnemonic meaning. All REDEFINEdvariables have this form. An alternate approach is to use the concatenation feature tobuild unique symbols that are available for plotting or printing. This technique canalso reduce considerably the length of the argument list; using a long argument list isthe other alternative when unique symbolic names are required.

MACRO MACRO dot(p, q)MACRO RELABEL loopMACRO REDEFINE iMACRO IF(q(2)=q(3)) ml1MACRO PRINT Conflicting dimensions in dot productMACRO EXITMACRO ml1: CONTINUE

PROCEDURAL(p(1) = p(2), p(3))p(1) = 0.0DO loop i = 1, q(2)p(1) = p(1) + p(2)(i)*p(3)(i)

loop: continueEND ! of procedural

MACRO END

! Invocation of dot macroDIMENSION y(10), z(10)dot(x = y, z)

Figure 6-1. DOT product macro and invocation

6. Macro Language 6.5 Macro examples


Definition In this example, a macro is defined for a gas holding tank. The flow into the tank iscalculated as the difference in pressure divided by a resistance. Total pressure is theintegrated net flow divided by a volume. The macro definition is thus:

MACRO tank(n)f&n&i = (p&n&i - p&n)/r&n&ip&n = (INTEG((f&n&i - f&n&o)/v&n, p&n&ic)MACRO END

Invocation The basic equations for different vessels (tank 1 and tank 3, for example) can now beestablished in the model by the statements:

tank(1)tank(3)

Expansion The invocation TANK(3), for example, generates the following translated code:

F3I = (P3I - P3)/R3IP3 = INTEG((F3I - F30)/V3, P3IC)

Constants andvariables

Constants must be defined elsewhere for the resistanceR3I, the volumeV3, and initialpressureP3IC. Variables which must be defined elsewhere are the input pressure nodeP3I and the output flowF3O. This macro then makes available to other sections of thesimulation the input flowF3I and tank pressureP3.

Alternative form An alternative form of the macro invocation without the concatenation feature wouldhave to be a separate statement such as the following for each tank in the system:

tank(f3i, p3 = p3i, r3i, f3o, v3, p3ic)

Advantages ofconcatenation

The trade-off in deciding how to define the macro can be stated generally as follows:Without the concatenation feature, argument lists become long and complicated, butargument lists have the advantage of flexibility in naming; in addition, arguments canbe expressions. Using the concatenation feature, the argument list is simple: oneargument (usually a literal constant, but can an alphanumeric variable name). Analternative TANK macro could have the output flow and downstream pressurespecified in the argument list since these are likely to be expressions;e.g.,

MACRO tank(n, pi, fo)f&n&i = (pi - p&n)/r&n&ip&n = INTEG((f&n&i - (fo))/v&n, p&n&ic)MACRO END

The invocation of this macro could, for example, substitute a variable name for inletpressure PI and an expression for the outlet flow FO, as follows:

tank(1, psource, (p1 - p5)/r51)

The disadvantage of the concatenation approach is the inflexibility in namingconvention, but if you have control of the model design, you can use this to advantage.

6.5.4 Matrix operations

Matrix operations such as addition, multiplication, negation, and transposition can bedefined by macros. Macros for these four operations are listed in Figures 6-2 through6-5 and the macro for matrix multiply (MMUL) is discussed in detail.

Note that matrix operations are usually characterized by an n-cubed operation countand can be expensive for large matrices.



Matrix multiplymacro

The MMUL operator (listed in Figure 6-2) uses the second type of macro definitionheader, in which array dimensionsQ andRare used in the definition and are picked upautomatically by the operator provided they have been defined prior to the macro call.The reason the arrays must be dimensioned before the macro call is that the ACSLtranslator makes only one pass over the input source code to generate text; the secondpass is a sorting operation.

Dimensions All matrices must be doubly dimensioned; single dimension vectors may bedimensioned either (1, n) for row vectors or (n, 1) for column vectors. Only matricesinput to the macro must be dimensioned; output matrices have their dimensionscalculated and defined appropriately. In the following example, input matricesA andBare dimensioned in a DIMENSION statement;X, which is input in the third line, hasbeen dimensioned by virtue of being output from the macro in the previous line.Reversing the order of the calls forX andYwould not work.

DIMENSION a(3, 2), b(2, 3)MMUL(x = a, b)MMUL(y = x, a)

Invocation The calling sequence for MMUL is defined as follows:

MMUL(C = A, B)

which performs the matrix multiplication expressed mathematically as:

[C] = [A][B]

The macro definition includes a test that the row dimension of [A] is equal to thecolumn dimension of [C]; if not, a message is written out to you.

!-----------------------------Matrix Multiply. Calling sequence is:!! mmul(c = a, b)!! This defines a new matrix C of dimension col(A) by row(B) and! performs the matrix multiplication

MACRO MACRO mmul(p, q, r)MACRO RELABEL L110MACRO REDEFINE j, k, lMACRO IF (r(2)=q(3)) okMACRO PRINT Row dimension 1st arg unequal to col dimnsn 2nd argMACRO EXIT

MACRO ok..CONTINUEDIMENSION p(1)(q(2), r(3))PROCEDURAL(p(1) = p(2), p(3))DO L110 k = 1, r(3)DO L110 j = 1, q(2)p(1)(j,k) = 0.0DO L110 l = 1, r(2)p(1)(j,k) = p(1)(j,k) + p(2)(j,l)*p(3)(l,k)L110: CONTINUEEND ! of proceduralMACROEND

Figure 6-2. Matrix multiply macro



!-----------------------------matrix add. Up to 4 matrices can be! added into an output matrix which is created automatically.! Calling sequence:!! madd(y = a, b, ..., d, e)!! where the input matrices must have exactly the same dimen-! sions (both rows and columns) and this will be the size of! the output matrix Y.

MACRO MACRO madd(p, q, r)MACRO RELABEL L110MACRO REDEFINE j, kMACRO ASSIGN nDIMENSION p(1)(q(2), r(2))MACRO IF (n=3) 3MACRO IF (n=4) 4MACRO IF (n=5) 5MACRO IF (n=6) 6

MACRO PRINT Too many or too few arguments to matrix addMACRO EXIT

MACRO 3: CONTINUEPROCEDURAL(p(1)=p(2), p(3))DO L110 k=1,r(2)DO L110 j=1,q(2)p(1)(j,k) = p(2)(j,k) + p(3)(j,k)L110: CONTINUEEND ! of proceduralMACRO EXIT

MACRO 4: CONTINUEPROCEDURAL(p(1)=p(2), p(3), p(4))DO L110 k=1,r(2)DO L110 j=1,q(2)p(1)(j,k) = p(2)(j,k) + p(3)(j,k) + p(4)(j,k)L110: CONTINUEEND ! of proceduralMACRO EXIT

MACRO 5: CONTINUEPROCEDURAL(p(1)=p(2), p(3), p(4), p(5))DO L110 k=1,r(2)DO L110 j=1,q(2)p(1)(j,k) = p(2)(j,k) + p(3)(j,k) + p(4)(j,k) + p(5)(j,k)L110: CONTINUEEND ! of proceduralMACRO EXIT

MACRO 6: CONTINUEPROCEDURAL(p(1)=p(2), p(3), p(4), p(5), p(6))DO L110 k=1,r(2)DO L110 j=1,q(2)p(1)(j,k) = p(2)(j,k) + p(3)(j,k) + p(4)(j,k) + p(5)(j,k) + p(6)(j,k)L110: CONTINUEEND ! of proceduralMACRO EXITMACRO END

Figure 6-3. Matrix add macro



Three matrices can be multiplied together with a call such as:

MMUL(y = a, MMUL(b, c))

which can be expressed mathematically, in the given order:

Y = [A][B][C]

!-----------------------------Matrix Negate. The output matrix is! created and the input matrix is moved into it, changing the! sign of each element on the way

MACRO MACRO mnegat(p, q, r)MACRO RELABEL L110MACRO REDEFINE j, kDIMENSION p(1)(q(2), r(2))PROCEDURAL(p(1) = p(2))DO L110 k = 1, r(2)DO L110 j = 1, q(2)p(1)(j,k) = -p(2)(j,k)L110: CONTINUEEND ! of procedural

MACROEND

Figure 6-4. Matrix negate macro

!-----------------------------Matrix Transpose. The output matrix is! created and the input matrix is moved into it, swapping rows! and columns on the way

MACRO MACRO mtrans(p, q, r)MACRO RELABEL L110MACRO REDEFINE j, kDIMENSION p(1)(r(2), q(2))PROCEDURAL(p(1) = p(2))DO L110 k = 1, r(2)DO L110 j = 1, q(2)p(1)(k,j) = p(2)(j,k)L110: CONTINUEEND ! of procedural

MACROEND

Figure 6-5. Matrix transpose macro



6.6 Macroinvocation

Once a macro has been defined, it must be invoked with specific arguments listed forsubstitution.

Single output One form of call is to embed the macro name in an arithmetic expression. For thisform, only one output (a single number) should be produced by the macro. Anexample of this form is:

x = 5.0*SIN(DOT(a, b)/4.0)

where the DOT product macro is embedded in the argument of the SIN function.AandB in this case correspond to the second and third argument of the macro,respectively; the output is the (understood) first argument.

Standalone forms An alternative form of the call is as a standalone statement, which has two forms asfollows:

DOT(x = a, b)DOT(x, a, b)

The equal sign in the first form is to indicate to the reader thatX is an output. Theprogram determines the actual inputs and outputs as it processes the statementsproduced by the macro;i.e., no error would result if the operator were invoked asfollows:

DOT(x, a = b)

but it would be misleading to the user. Note especially that

x = DOT(a, b)

is an assignment statement and the nameX is not substituted for the first argument.Only a single numerical value can be passed across the equal sign of an assignmentstatement.

On the other hand, consider a matrix integration operator which might be invoked asfollows:

matint(x, xd = a, xic)

In this call, two entire vectors are the output of the operator and have their valueseffectively passed across the equal sign. Passing more than one value across an equalsign is possible only in macro and subroutine calls.

Argumentsubstitution

The substitution of macro arguments is by replacement of the character string formingthe argument with the substitutable name. Where expressions are used, the wronganswer can be obtained if parentheses are not placed around the argument. Forexample, consider a macro to integrate a difference in flow rate as follows:

MACRO accum(tot, w1, w2, ic)tot = INTEG(w1 - w2, ic)MACRO END

At invocation, an expression for net flow out becomes:

accum(mass = win, wp1 + wp2, massic)

which produces the line of code:

MASS = INTEG(WIN - WP1 + WP2, MASSIC)

6.6 Macro invocation 6. Macro Language


Use of parentheses This result is not exactly right, since the second flowWP2has been made positive.The solution, when the operator precedence can cause a problem, is to surround thesubstitutable name with parentheses. The macro above should have been defined asfollows:

MACRO accum(tot, w1, w2, ic)tot = INTEG(w1 - (w2), ic)MACRO END

Now at substitution the executed statement is:

MASS = INTEG(WIN - (WP1 + WP2), MASSIC)

It is not necessary to enclose the first parameter,W1, in parentheses since anyexpression substitution gives the correct answer. Trouble usually arises whenarguments are negated, multiplied, divided by other variables, or used as a divisor inthe macro division.

6. Macro Language 6.6 Macro invocation


7. Debugging

7.1 Debuggingprocedure

One of the important features of the ACSL language is the availability of tools toassist in pinpointing errors. These tools include informational messages, errormessages, and debug dumps. This chapter outlines the debugging procedure andexplains the debug dump, the messages produced by the variable step integrationalgorithms, and the messages produced by the Jacobian evaluation. ACSL errormessages (from both the translator and the runtime executive) are listed alphabeticallyin Appendix F along with an explanation for each and often a suggested remedy.

Start translation When you start the ACSL system (see theACSL Sim User's Guidedocument), ittranslatesthe model source code onto a Fortran compile file,compilesthe Fortran intoan object file,linksor loads the object files with libraries needed for runtimeexecution, and finallyexecutesthe program, arriving at the ACSL prompt, which onmost systems is:

ACSL>

At this point, ACSL is waiting for runtime commands.

Translation errors The first run through the translator often produces messages indicating syntax errors(probably the most common error) and/or semantic errors. Semantic error messagesare listed in Appendix F. The translator analyzes each model code statement in turn. Ifit encounters a syntax error, it writes out the statement in error, including anycontinuations, with a line of asterisks underneath the acceptable part of the statement.The asterisks thus stop justbeforethe error. For example:

X = Y + (SIN(Y.Y))...Syntax error....the line is listed with a pointer to the errorX = Y + (SIN(Y.Y))**************

Here the asterisks appear under everything through the firstY in the argument to theSIN function, but not under the period, indicating that the period separating the twoY'sis not allowed; it undoubtedly should be an asterisk, for multiplication.

Finds only firsterror in line

Two points should be noted about the error messages. The first point is that only thefirst error in the statement will be indicated. If this error is corrected, a second (orthird) run may be needed to uncover other problems further into the statement. Whenmaking a correction, you should take a long hard look at the rest of the statement.

Continuationstatements

The second point is that if continuation statements are used, the line listed may notlook exactly like the input text. The error listing gives the complete string to beanalyzed after the blanks have been squeezed from any continued statements.

Search for .... Translation errors can be found in the translator output file by searching for ".... ".Avoiding these in the program code makes it easier to search for errors with an editor.

Spelling errors After correcting translation errors, check for misspellings. Names may be typedincorrectly and intended changes may be overlooked. Any variables listed under


Symbol used but not definedare probably misspellings, constants left unspecified, orcorrect variables that had their names misspelled at the statements defining them.

FORTRANcompilation errors

The ACSL translator catches most errors that would also fail at the compiler stage;however, occasionally a compiler error is produced. The name of the compile filedepends on your computer system. For example, on Unix systems, the default filename is model.f; on PC systems, model.FOR. If you find any compiler errors, refer toyour FORTRAN manual for details. Correct the ACSL program code, then begin thetranslation process again.

Unsatisfiedexternal

references

Next, take note of any unsatisfied external references listed in the load map. Thesemay correspond to arrays not declared in a DIMENSION statement; without thedeclaration, they look just like functions. Another possibility is a referenced librarythat has not been specified in the link or load statement.

First run For the first run, set the stop condition (the condition in the TERMT statement) to asmall value (typically one communication interval) so that no time is wastedcalculating incorrect values. Also set up a debug action as follows:

SET NDBUG=10,HVDPRN=.T.,tstop=0.1START

NDBUG specifies the number of DEBUG dumps to be printed. A debug dump isproduced each time a DERIVATIVE or DISCRETE section has been evaluated, andfor each perturbation during a Jacobian evaluation. HVDPRN is set true so that thedebug dumps appear on the screen; this is the system default. The stopping conditionis assumed in this example to depend on a CONSTANT in the program namedTSTOP.

Evaluating debugdumps

The debug output is probably the most important data to help in debugging; theprevious steps were merely to ensure that the mechanics were correct (commas in theright place, spelling consistent, etc.). This debug output gives the actual numberscalculated for every one of the state derivatives and intermediate variables. Look at thenumbers carefully and check for reasonableness using your knowledge of the systemyou are trying to model. For example, check that the derivatives are of the sign andmagnitude you expect. The next section in this chapter explains the order of the debugdump and meaning of the system symbols printed out.

Initial conditions It is a good idea to start with initial conditions nonzero. If there are too many zerovalues, the arithmetic calculations can conceal errors. For preference, pick conditionsso the derivatives all have a nonzero value which can be checked. Check the valuesthat are listed for the constants.

Preset variables The translator presets all user variables to 5.5555E33 (double precision to 5.5555D33and integers to 55555333). This procedure helps catch variables that are not yetcalculated before being used. If a run stops on an error, large numbers in the debugdump point out variables which have not been calculated; often these can be traced inthe ACSL or FORTRAN listing to some error in initialization, spelling, or ordering.

Preset derivatives The initialization subroutine presets all derivatives to 3.33333E-33. During the initialevaluation of the DERIVATIVE section, ACSL checks that all derivatives havechanged from this preset value; if not, an error message is produced to indicate that aderivative calculation has been skipped:

...Derivative no. N not calculated

Arrays All elements of an array are listed in debug dump if the size of the array is less thanthe value of the integer system variable MALPRN (maximum array limit for printout,default 10). If the array size exceeds MALPRN, the name of the array, its size, and thevalue of the last element of the array are printed out; for example:

7. Debugging 7.1 Debugging procedure


A(16) 4.590000000 B(12) 2.000000000

See Appendix C for descriptions of MALPRN and other system symbols.

Initialization test One of the best tests of initialization is to START the same run twice;i.e.,

SET NDBUG=2 ; STARTSET NDBUG=2 ; START

The corresponding debug dumps from each run should be the same down to the lastsignificant digit; if they are not, the second run must be using a value left over fromthe first run, indicating that some variable has not been correctly initialized. Be surethat any random number generators are initialized with the same seed.

First full run Now the time comes to try the first full run. Plan what significant output variables willenable you to deduce correct model operation. Specify these in an OUTPUTstatement, increase the termination time, and give the START command.

It is at this point that the modeller's skill comes in, to rationalize the behavior of thesimulation in terms of the way the real world system is expected to behave. Oncequestionable areas have been uncovered, schedule debug printouts to cover the area ofinterest so that as much information is recorded as possible.

ACTION fordebug during run

To obtain debug dumps at a particular time in the run, use the ACTION command. Anumber of dumps can be scheduled either at the beginning of the run or at a point ofinterest, such as where the behavior of the system becomes questionable. ACTIONgives a debug printout after each START until an ACTION /CLEAR subcommand isissued. (See the section on ACTION in Chapter 5 for details.) Typical calls toACTION are:

ACTION /VARIABLE=0.0 /VALUE=10 /LOCATION=NDBUGACTION /VARIABLE=4.98 /VALUE=50 /LOCATION=NDBUG

Systemdebuggers

On some computer systems, a run might crash without giving very much diagnosticinformation. In this situation, we suggest using your computer system debugger; forexample, on Unix systems, the-g flag starts up the debugger, and on VAX systemsthe/DEBUGswitch starts the symbolic debugger. In the debugger, when an abortoccurs, a'where' or TRACEBACK pinpoints the offending line.

Debuggingwithout a system

debugger

If there is no Fortran or system debugger to help isolate the problem, try inserting callsto LOGD (see Chapter 4) or calls to DEBUG along with a diagnostic variable asfollows:

PROCEDURALaaaaaa = 1CALL LOGD(.TRUE.)END

Place these calls at strategic points in the ACSL program, such as at the beginning andend of DERIVATIVE and DISCRETE sections, using a different value ofAAAAAAfor each call for identification purposes. LOGD forces data logging both to the RRRfile and to the OUTPUT listing. At runtime, putAAAAAAand any other variables ofinterest on the OUTPUT list and START a run.

OUTPUT t,aaaaaa, ...START

Note the last value ofAAAAAAbefore the run crashes. Check the program listingand/or the Fortran compile file for clues as to which statement after this last call toLOGD and before the next one (not executed) caused the problem. You may need toadd more calls to further narrow the area of interest and isolate the problem.

7.1 Debugging procedure 7. Debugging


Choosing stepsize

A possible cause of a model stopping without apparent reason or with a crypticmessage can be an integration step size that is too large. The step size should never belarger than the smallest time constant in the model (except in cases where the energydies out of the high frequency motion, where the Gear's stiff algorithm can be used totake larger steps).

Finding timeconstants with

ANALYZE

If you don't know the system time constants, there are two methods of determining anappropriate step size. The frequency analysis command ANALYZE /EIGEN lists theeigenvalues in ascending order (see the section on ANALYZE in Chapter 5); these arethe reciprocal time constants of the system.

ANALYZE /EIGEN

ACSL's choice ofstep size

Another approach is to find out what ACSL chooses for a step size with the variablestep, variable order algorithm, Adams-Moulton (IALG=1). The system symbolsCSSITG (current step size) and CIOITG (current integration order) can be put on thePREPARE list for printing and/or plotting.

SET IALG=1PREPARE T,CSSITG,CIOITG, ...STARTPLOT CSSITG,CIOITG

Look at the shape of CSSITG. If it is steady, use a fixed step size just slightlylargerthan the values chosen by the variable algorithm (the system choice of step size ismore conservative than necessary, so a slightly larger step is adequate). If the currentstep size varies widely, however, consider using one of the variable step algorithms.

Check that the step size is not being constrained by CINT. If it is, increase CINT andrun the simulation again.

The system choice of integration order CIOITG can be factored into the decision onwhat order and step size of a fixed step algorithm to use.

7.2 DEBUGprintout

The debug output is generated whenever NDBUG is greater than zero or when a callto DEBUG appears in the model code. The call to DEBUG is often put on a logicalswitch; for example:

LOGICAL dump ; CONSTANT dump=.TRUE.IF(dump) CALL DEBUG

At runtime, NDBUG can be set before starting the run:

SET NDBUG=10START

ACTION statements can set NDBUG at any value of the independent variable:

ACTION /VARIABLE=2.0 /VALUE=20 /LOCATION=NDBUGSTART

Figure 7-1 shows a debug dump. The listing is divided into three major sections:system variables, state variables (with derivatives and initial conditions), and algebraicvariables (further divided into common blocks). Each of these sections is described inmore detail below.

7. Debugging 7.2 DEBUG printout


NDBUG andblock number

The header gives the value of NDBUG (which is decremented at each dump) and theblock number. The block number tells you which DERIVATIVE or DISCRETEsection has just been evaluated. The number is assigned by counting allDERIVATIVE and DISCRETE sections in the order they appear in the program code,counting the first block as one.

When debugdumps areproduced

A debug dump is produced at every derivative evaluation as long as NDBUG isgreater than zero. For example, Runge-Kutta fourth order integration takes fourderivative evaluations – one at the beginning, two in the middle, and one at the end.The independent variable thus appears to advance in half-steps, with two derivativeevaluations each step. There is an additional evaluation prior to each communicationinterval (i.e., pass through the DYNAMIC section). Debug dumps are also producedeach time a DISCRETE section is evaluated and for each perturbation during aJacobian evaluation.

ACSL systemsymbols

The first seventeen variables in the dump are ACSL system variables. The namesand/or values of certain system variables can be changed from their defaults bystatements in the program (CINTERVAL, VARIABLE, for example). The default setof system variables is defined as follows:

T Floating point. Independent variable; may have been renamed in a VARIABLEstatement.

ZZTICG Floating point. Initial condition of the independent variable; may have been renamedin a VARIABLE statement.

CINT Floating point. Current communication interval; may have been renamed in aCINTERVAL statement.

ZZIERR LOGICAL. Variable step error flag; may have been renamed in an ERRTAGstatement. It becomes TRUE if the variable integration algorithm attempts to take astep size smaller than MINT.

ZZNBLK INTEGER. Number of DERIVATIVE plus DISCRETE blocks in use. Several of theother system variables are arrays of length ZZNBLK;i.e., ZZNIST, ZZNAST, IALG,NSTP, MAXT, MINT.

....Debug dump - System Variables. NDBUG is 1, block number 1T 0. ZZTICG 0. CINT 0.02500000

ZZIERR F ZZNBLK 1 ZZICON 1ZZSTFL F ZZFRFL T ZZICFL FZZRNFL F ZZJEFL F ZZNIST 2ZZNAST 0 IALG 4 NSTP 1

MAXT 0.01250000 MINT 1.0000E-09

State Variables Derivatives Initial ConditionsTH 1.00000000 Z09997 0. THIC 1.00000000

THD 0. Z09998-16.5097000 THDIC 0.

Algebraic Variables

Common Block /ZZCOMU/DICT F DPR 57.2958000 DUMP FFILE 11 G 9.81000000 KDAMP 0.30000000

LENGTH 0.50000000 MASS 1.00000000 THDD-16.5097000TSTOP 4.99000000 XTH 57.2958000 ZZSEED 55555555

Figure 7-1. ACSL debug dump

7.2 DEBUG printout 7. Debugging


ZZICON INTEGER. Distinguishes pre-initial (0), START (1), and CONTINUE (2).

ZZSTFL LOGICAL. Stop flag; starts FALSE, eventually set TRUE by TERMT or by anoperator interrupt.

ZZFRFL LOGICAL. First flag; set TRUE at first derivative evaluation of every integration step.

ZZICFL LOGICAL. Initial condition flag; set TRUE for the first derivative evaluation of everyrun, immediately after initial conditions have been transferred to states.

ZZRNFL LOGICAL. Reinitialize flag; set TRUE by REINIT, used during initialization(ZZICFL=.TRUE.), and then turned FALSE.

ZZJEFL LOGICAL. Jacobian evaluation taking place when TRUE. The Jacobian is evaluatedfor some ANALYZE operations and during integration with the Gear's stiff algorithm.

ZZNIST INTEGER. Array of length ZZNBLK; number of integration state variables in each ofthe DERIVATIVE and DISCRETE blocks.

ZZNAST INTEGER. Array of length ZZNBLK; number of algebraic state variables in each ofthe DERIVATIVE and DISCRETE blocks.

IALG INTEGER. Array of length ZZNBLK; integration algorithm number to be used foreach block, zero for DISCRETE sections; may have been renamed in anALGORITHM statement.

NSTP INTEGER. Array of length ZZNBLK; communication interval divisor for each block;may have been renamed in a global NSTEPS statement.

MAXT Floating point. Array of length ZZNBLK; maximum integration step size for eachblock; may have been renamed in a global MAXTERVAL statement.

MINT Floating point. Array of length ZZNBLK; minimum integration step size for eachblock, value of INTERVAL for DISCRETE sections, -1 for DISCRETE sectionswithout an INTERVAL statement; may have been renamed in a global MINTERVALstatement.

Arrays Several system variables (ZZNIST, ZZNAST, IALG, NSTP, MAXT, and MINT)become arrays when there is more than one DERIVATIVE and/or DISCRETE blockin the program. See the section on DERIVATIVE in Chapter 4 for more details.

State variables,derivatives, andinitial conditions

Next in the debug print out is the list of state variables in DERIVATIVE block orderand in alphabetical order within each block. Each state is listed with it correspondingderivative and initial condition on the same line. If the line width (see PCWPRN,TCWPRN, and HVDPRN) is sufficient (126), the corresponding value of absoluteerror (XERR) and relative error (MERR) are also listed on the same line. In general,the derivatives will have dummy names (i.e., in the form Znnnnn), except for thosedefined by the INTVC integration operator.

Algebraicvariables

After the states, the algebraic variables are listed in order of common blocks.

Common blocks First is the single precision common block /ZZCOMU/. Second, if any doubleprecision variables are used, a double precision common block called /ZZCOMP/appears. Third, if any character variables are specified, there is a common block called/ZZCOMC/. The variables in these three blocks are listed in alphabetical order,reading left to right in rows. Then come any common blocks you have specified, withthe variables given in the order you specified when defining the blocks. In Figure 7-1,there are no user-specified common blocks.

Equivalence Any EQUIVALENCEd variables are listed at the end of each block.

7. Debugging 7.2 DEBUG printout


ZZSEED System variable ZZSEED is the random number seed variable, which changes withevery call for a new random number (i.e., using GAUSS, UNIF, or OU).

Value ofI or R

A value of I in the output stands for infinity. A value of R stands for NaN (not anumber). This indicates that the bit pattern does not correspond to a floating pointformat, which often occurs when a floating point variable contains integer data, orwhen dividing zero by zero.

7.3 Variable StepAlgorithmMessages

A summary message is produced at the end of a simulation run when using one of thevariable step integration algorithms;i.e., IALG = 1 (Adams-Moulton), IALG = 2(Gear's Stiff), IALG = 8 or 9 (Runge-Kutta-Fehlberg second or fifth order) orIALG=10 (DASSL). Unless the summary is suppressed by setting the ACSL systemsymbol WESITG (write error summary) to FALSE, the message is produced andappears in the following form:

COUNT OF TIMES STATE CONTROLLED STEP SIZEMINUS (-) REL ERR ALWAYS BELOW ABS ERR

ST1 PC FAIL 0 ERR CONTROL 15-ST2 PC FAIL 0 ERR CONTROL 1ST3 PC FAIL 0 ERR CONTROL 127

...

PC FAIL At each time step of a variable step algorithm, a predictor/corrector (PC) iterationoccurs until the estimated integration error is less than the allowable error specified (orimplied) by the model (see MERROR, XERROR). If all state derivatives fail toconverge to within a given error tolerance within three attempts, the predictor/corrector iteration is considered to have failed and the state responsible (or the statewith the largest relative error) is marked with the PC FAIL count incremented and thestep size is arbitrarily reduced by a factor of 0.25. Relative error is the ratio ofestimated error to allowable error and can be different for each state variable. The stepsize is reduced arbitrarily because convergence failure implies that a discontinuity.

ERR CONTROL If the predictor corrector iteration converges, then an estimate of the actual error madein the step is calculated. This error estimate is compared with the allowable error. Onestate always has the largest relative error, even though in general this will be less thanunity; this state has a corresponding ERR CONTROL counter incremented. Thecounter is reported as an ERR CONTROL count in the summary message at the end ofthe run. The sum of all the ERR CONTROL counts is approximately the total numberof integration steps taken.

Reducing thestep size

If any comparison of estimated error with allowable error exceeds unity (i.e., theestimated error is greater than the allowable error), a reduced step size is calculatedand the predictor-corrector iteration is performed again. This sequence is continueduntil the step size is such that all the estimated errors are below the allowable errors.Note however that only one count is added to the ERR CONTROL vector at eachintegration step, and that count is for the state with the largest relative error on the firstcalculation of estimated error.

Minus sign (-) The minus sign (-) that follows the ERR CONTROL count is a flag to warn that theabsolute error (XERROR) may be swamping the relative error for this state. Sinceabsolute error must have the same units as the state, it is possible for this to beaccidentally much larger than that allowed by the relative error specification. Using

7.3 Variable Step Algorithm Messages 7. Debugging


the standard defaults of 1.0E-4 for both MERROR and XERROR, if the state valuenever exceeds one, then control is always by the absolute error and the minus signflags the state. Problems are possible if a state varies over microradians, for example,where a 0.01% fractional error would be 1.0E-10 and the absolute value is still thedefault of 1.0E-4. This is not necessarily a problem, though, since other states may bemore important or may be the controlling states. The minus sign simply indicates thatit is worthwhile examining the conditions.

7.4 Output fordebugging ofintegrationprocess

One of the standard difficulties of producing a working simulation is validating thedata produced by the model. The problem with the OUTPUT and PREPAREstatements is that they record data only every communication interval. There may bemany derivative evaluations between these points of visibility. One of the problemswe've encountered is seeing a derivative with a positive value but the state moves in anegative direction. The explanation for this can be seen by turning on the ACSL debugoutput (NDBUG = positive integer) so that each derivative evaluation can beexamined. This usually exposes the problem since the state moves due to some linearcombination of derivative values and if they are all visible, then the problem can beexplained.

For the above, the derivative seen in an OUTPUT or PRINT line is the derivativeevaluated last before the data recording action. In order for the state to move negative,there must have been enough negative derivatives prior to the positive one shown byOUTPUT or PRINT to produce a net negative change. Unfortunately, with largesimulation models of thousands of variables, a single debug listing can go for tens ofpages (with width not constrained to a terminal, it is five variables/line, 55 lines perpage, roughly four pages/1000 variables).

7.4.1 Write NormalData (WNDITG)

The important information that determines the evolution of the simulation is the statevalues and the derivatives that are making the state move. In order to get just thisinformation, we introduced an extra system variable WNDITG (write normal dataduring the integration). This flag has somewhat differing effects depending on theintegration algorithm but the basic idea is to generate enough information so that theintegration process can be followed.

We ran the single precision version of the missile model (MISSGL.CSL) to generatesample output using this switch. We chose the missile model because it has twelvestate variables that make it more interesting than just the two in the spring model.

The output is shown in Figures 7-2 through 7-10 for each of the different algorithms.

Euler The simplest one is shown in Figure 7-2 for algorithm three (IALG=3), Eulerintegration. With one derivative evaluation per step, the listing shows the current valueof the independent variable asx and the current step size ash. These are the namesthat are actually used in the integration routines rather than the user changeable defaultnames such as T (independent variable) or MAXT (maximum step size). After the step

7. Debugging 7.4 Output for debugging of integration process


size information is listed, the state vector (really the transpose since it is laid out acrossthe page) and derivative vector are shown.

Runge-Kutta Next in complexity is the Runge-Kutta second order (IALG=4), shown in Figure 7-3.Now we see the state and derivative after the first derivative evaluation and also forthe second one two-thirds across the step (h). The next state vector is calculated byadding a weighted sum of these two derivatives (0.25, 0.75) to the original statevector. Very similar is the fourth order Runge-Kutta shown in Figure 7-4. In this case,there are four derivative evaluations per step, each one being shown in turn.

Runge-Kutta-Fehlberg

The variable step Runge-Kutta-Fehlberg algorithms (IALG=8, 9) are shown in Figures7-5 and 7-6. Here we have a number of state extrapolations with derivativeevaluations, and then an estimate of the errors made for each element of the statevector. This error vector is normalized by dividing the actual estimated error term bythe allowable error (for XERROR and MERROR), so that for a successful step allentries in the estimated error vector should be less than or equal to one.

In several of these figures, intermediate evaluations have been edited out to save space.

Start of step: Order is 1State/derivative vectors : x = 0.0100000 0 , h = 0.01000000

1 0. 21.5480003 10000.0000 0. 0.6 0. 2154.80005 -0.50673878 0. 0.

11 0. 0.02019195

1 0. 2154.80005 -0.50673878 0. 0.6 0.02019195 0. -47.6358032 0. 0.

11 0. 1.90546012

Figure 7-2. Euler integration (IALG = 3)

Start of step: Order is 2State/derivative vectors : x = 0.0100000 0 , h = 0.01000000

1 0. 21.5480003 9999.99707 0. 0.6 1.0096D-04 2154.80005 -0.49154842 0. 0.

11 0. 0.01962327

1 0. 2154.80005 -0.49154842 0. 0.6 0.01962327 0.00143591 -46.4225960 0. 0.

11 0. 1.88084292

Second eval. State/derivative vectors : x = 0.016666671 0. 35.9133339 9999.99414 0. 0.6 2.3178D-04 2154.80005 -0.80103236 0. 0.

11 0. 0.03216222

1 0. 2154.80005 -0.80103236 0. 0.6 0.03216222 0.00247475 -42.8770714 0. 0.

11 0. 1.7746803

Figure 7-3. Runge-Kutta 2nd order integration (IALG = 4)

7.4 Output for debugging of integration process 7. Debugging


Start of step: Order is 4State/derivative vectors : x = 0. , h = 0.01000000

1 0. 0. 10000.0000 0. 0.6 0. 2154.80005 0. 0. 0.

11 0. 0.

1 0. 2154.80005 0. 0. 0.6 0. 0. -50.6738815 0. 0.

11 0. 2.01919460...Fourth eval. State/derivative vectors : x = 0.01000000

1 0. 21.5480003 9999.99707 0. 0.6 9.8116D-05 2154.80005 -0.48548239 0. 0.

11 0. 0.01950018

1 0. 2154.80005 -0.48548239 0. 0.6 0.01950018 0.00140264 -46.4956970 0. 0.

11 0. 1.88270521

Figure 7-4. Runge-Kutta 4th order integration (IALG = 5)


1 0. 0. 10000.0000 0. 0.6 0. 2154.80005 0. 0. 0.

11 0. 0.

1 0. 2154.80005 0. 0. 0.6 0. 0. -50.6738815 0. 0.

11 0. 2.01919460

Second eval. State/derivative vectors : x = 0.005000001 0. 10.7740002 10000.0000 0. 0.

...Third eval. State/derivative vectors : x = 0.01000000

1 0. 21.5480003 9999.99707 0. 0....Estimated error: fflg = 0

1 0. 0. 9.6017D-06 0. 0.6 0.00383310 1.2969D-07 0.82940382 0. 0.

11 0. 0.02700307

State number 8 has largest relative error of 0.82940400

Figure 7-5. Runge-Kutta-Fehlberg 2nd order integration (IALG = 8)



Adams-Moulton,Gear

Moving to the Adams-Moulton and Gear algorithms, outputs from these routines arelisted in Figures 7-7 and 7-8. The current situation is saved in a Nordsieck vectorwhich maintains the components of a Taylor series expansion to predict the value onestep size (h) away,i.e.;

y(x + h) = y(x) + hy′(x) + h2

2!y′′(x) + h3

3!y′′′(x) + ⟨

The components of the Nordsieck vector are just the values of the separate terms in theabove equation. It is really the state vector at the current time at the beginning of thestep (Y(X)) and successive derivatives scaled by increasing powers ofh. One bigadvantage of the Nordsieck vector is the prediction step, which just adds thecomponents. Changing step size just means multiplying each term by a step size ratio(r) to a power;i.e., r, r2, r3, ....

References For the details of what is calculated, reference should be made to Gear[2]. The last ofthese sequences of outputs is shown in Figure 7-9. This is the output from the DASSLintegrator, and for the details of this, reference is made to Brenan, Campbell, andPetzold[1].


1 0. 0. 10000.0000 0. 0.6 0. 2154.80005 0. 0. 0.

11 0. 0.

1 0. 2154.80005 0. 0. 0.6 0. 0. -50.6738815 0. 0.

11 0. 2.01919460

Second eval. State/derivative vectors : x = 0.002500001 0. 5.38700008 10000.0000 0. 0.6 0. 2154.80005 -0.12668470 0. 0.

11 0. 0.00504799

1 0. 2154.80005 -0.12668470 0. 0.6 0.00504799 0. -49.9143639 0. 0.

11 0. 1.99076092...Sixth eval. State/derivative vectors : x = 0.00500000

1 0. 10.7739992 9999.99902 0. 0....

Estimated error: fflg = 01 0. 0. 3.5304D-08 0. 0.6 9.1747D-06 7.7587D-09 0.00649173 0. 0.

11 0. 1.1720D-04

State number 8 has largest relative error of 0.00649173

Figure 7-6. Runge-Kutta-Fehlberg 5th order integration (IALG=9)



Start of step: Order is 2Saved Nordsieck vector: xsv = 8.8520D-04 , hsv = 2.9407D-04

1 2 3 4 51 0. 1.90743566 10000.0000 0. 0.2 0. 0.63367027 -1.3151D-05 0. 0.3 0. 0. -2.1791D-06 0. 0.

6 7 8 9 101 1.0528D-06 2154.80005 -0.04469361 0. 0.2 5.2415D-07 4.7032D-09 -0.01481967 0. 0.3 8.6867D-08 1.3981D-09 1.4061D-05 0. 0.

11 121 0. 0.001781372 0. 5.9077D-043 0. -5.1048D-07

Corrector iteration: fail flag 0, count 1Current Nordsieck vector : x = 0.0013099 8 , h = 4.2477D-04

1 2 3 4 51 0. 2.82273698 10000.0000 0. 0.2 0. 0.91530144 -2.8065D-05 0. 0.3 0. 0. -4.5466D-06 0. 0.

6 7 8 9 101 1.9907D-06 2154.80005 -0.06606957 0. 0.2 1.1187D-06 1.5268D-08 -0.02134572 0. 0.3 1.8124D-07 2.9169D-09 2.9337D-05 0. 0.

11 121 0. 0.002633622 0. 8.5117D-043 0. -1.0651D-06

Current error relative to maximum1 0. 3.1249D-04 -2.4776D-08 0. 0.6 8.9358D-06 -1.2254D-08 -0.01797453 0. 0.

11 0. 3.6729D-04

Corrector converged.Sum of all derivative differences

1 0. 5.9605D-08 -2.4776D-08 0. 0.6 8.9358D-10 -2.6405D-09 -1.7975D-06 0. 0.

11 0. 3.6729D-08

State 8 has largest relative error of 0.01797450Scaled error that must be less than unity is 0.00149788

Figure 7-7. Adams-Moulton integration (IALG = 1)



Start of step: Order is 1Saved Nordsieck vector: xsv = 0. , hsv = 1.00000000

1 2 3 4 51 0. 0. 10000.0000 0. 0.2 0. 2154.80005 0. 0. 0.

6 7 8 9 101 0. 2154.80005 0. 0. 0.2 0. 0. -50.6738815 0. 0.

11 121 0. 0.2 0. 2.01919460

Corrector iteration: fail flag 0, count 1Current Nordsieck vector : x = 0.0100000 0 , h = 0.01000000

1 2 3 4 51 0. 21.5480003 9999.99512 0. 0.2 0. 21.5480003 -0.00455353 0. 0.

6 7 8 9 101 1.8642D-04 2154.80005 -0.45535287 0. 0.2 1.8642D-04 3.4438D-05 -0.45535287 0. 0.

11 121 0. 0.018641642 0. 0.01864164

Current error relative to maximum1 0. -0.00344383 0.00455353 0. 0.6 -1.86416483 -1.5982D-04 -513.859131 0. 0.

11 0. 15.5030489

State number 12 has largest errorCorrector iteration: fail flag 0, count 2Current Nordsieck vector : x = 0.0100000 0 , h = 0.01000000

1 2 3 4 51 0. 21.5480003 9999.99512 0. 0.2 0. 21.5480003 -0.00455355 0. 0.

6 7 8 9 101 1.8642D-04 2154.80005 -0.45535532 0. 0.2 1.8642D-04 2.4861D-05 -0.45535532 0. 0.

11 121 0. 0.018642062 0. 0.01864206

Current error relative to maximum1 0. 9.5778D-04 2.4492D-08 0. 0.6 -4.1162D-05 4.4449D-05 0.02449157 0. 0.

11 0. -0.00420351


1 0. -2.4861D-07 0.00455355 0. 0.6 -1.8642D-04 -2.4861D-05 -0.05138346 0. 0.

11 0. 0.00154988

Figure 7-8(a). Gear stiff Integration (IALG = 2)



Iteration beforederivativeevaluation

If models have algebraic constraints, then there must be an iteration before anyderivative evaluation to drive the residuals to zero. This is also made visible via theWNDITG flag. The new BOILER.CSL model described in the Appendix has twoalgebraic constraints and Figure 7-9 shows one iteration to drive the residuals to zeroprior to a derivative evaluation using Euler (IALG=3). The information here isessentially the same as that generated by the ANALYZE/TRIM command anddescribed under the ANALYZE command. The convergence however is when theactual step is less than all the allowable errors in these states.

State 8 has largest relative error of 513.835000Scaled error that must be less than unity is 256.917000Step change factors at different ordersBest factor 0.02495530 : factor current order 0.02495530Factor one lower 0. , factor one higher 0.Corrector iteration: fail flag 1, count 1Current Nordsieck vector : x = 2.4955D-0 4 , h = 2.4955D-04

1 2 3 4 51 0. 0.53773743 10000.0000 0. 0.2 0. 0.53773743 -3.1510D-06 0. 0.

6 7 8 9 101 1.2557D-07 2154.80005 -0.01262654 0. 0.2 1.2557D-07 5.7891D-10 -0.01262654 0. 0.

11 121 0. 5.0318D-042 0. 5.0318D-04

Current error relative to maximum1 0. -1.4447D-09 3.1510D-06 0. 0.6 -0.00125570 -2.6866D-09 -0.19296737 0. 0.

11 0. 0.00715956


1 0. -1.4447D-13 3.1510D-06 0. 0.6 -1.2557D-07 -5.7891D-10 -1.9297D-05 0. 0.

11 0. 7.1596D-07

State 8 has largest relative error of 0.19296700Scaled error that must be less than unity is 0.09648370

Figure 7-8(b). Gear's stiff integration (IALG=2)



7.4.2 Write ExtraData (WXDITG)

Jacobians can be very high volume in some cases since the size goes up by the squareof the number of state variables. The printing of these matrices is controlled separatelyby another system variable, WXDITG, or write extra data during the integration.Figure 7-10 shows the output taken from the BOILER.CSL model when using theGear's stiff integrator (IALG=2). The number of dynamic states leads to a 3x3 matrix.

State vector - iteration number 1MV 0.53387800 TL 139.802000

Residual vector - current rms 12.9154000 previous 1.0000E+37Scaled residual is 902.827000 previous 1.0000E+37

Z99992 5.0259E-04 Z99990-1805.65000

Newton step 0.32581800 steep desc step 0.20191800Relative step 40.0125000 mu 0


Residual vector - current rms 0.00700697 previous 12.9154000Scaled residual is 0.48896600 previous 902.827000

Z99992 6.1512E-05 Z99990 0.97729500

Newton step 1.7195E-04 steep desc step 1.1142E-04Relative step 0.08816350 mu 0

T 0.50000000 RESIDMV 9.5367E-07 RESIDTL 0.00439453


Residual vector - current rms 3.1521E-05 previous 1.0000E+37Scaled residual is 0.00221420 previous 1.0000E+37

Z99992 9.5367E-07 Z99990 0.00439453

Newton step 7.3193E-07 steep desc step 5.2732E-07Relative step 0.00115801 mu 0

Figure 7-9. Iteration to solve algebraic constraints

First Jacobian evaluated - Jacobian matrix:1 0. 3.4318D-11 -1.0008D-052 95.0857162 -0.37937951 66.19897463 1.00000000 -9.2765D-05 0.01130192

Figure 7-10. Jacobian value from Gear's stiff integrator (WXDITG = .TRUE.)



7.5 JacobianMessages

Jacobian messages are generated during simulation runs that use the Gear's Stiffintegration algorithm (IALG = 2) or with the runtime command ANALYZE explicitlyfor the Jacobian (subcommand /JACOBIAN) or implicitly for eigenvalues (/EIGEN)or steady state (/TRIM). The messages are produced when the ACSL system symbolCJVITG (check Jacobian validity) is TRUE (which is the default). The two messagesrelating to the Jacobian evaluation are:

Jacobian nonlinear measure for now M and column N is XFunction evaluation not repeatable, row N

Row and columnnumbers

To see how the Jacobian rows and columns are numbered, use the following runtimecommand (see the section on ANALYZE in Chapter 5):

ANALYZE /JACOBIAN

The Jacobianmatrix

The Jacobian is the partial derivative of the derivative vector with respect to the statevariables. It is a square matrix of dimension equal to the number of state variables.With ANALYZE, the addition of control (/CONTROL) and observable (/OBSERVE)variables extends the state and derivative vectors, respectively, making the Jacobiannon-square, although it is actually listed out as a square A matrix and possiblynon-square B, C, and D matrices. Freezing some state variables (/FREEZE) reducesthe dimension of the state and derivative vectors together.

Perturbation The Jacobian is calculated numerically by perturbing each of the states first positively,then negatively, computing the derivative vector for each value. The differencedivided by twice the perturbation produces one column of the matrix for each state asit is evaluated in turn.

Nonrepeatable TheFunction evaluation not repeatablemessage refers to a nonrepeatable derivativevalue which is checked by perturbing the state again in the positive direction (only ifCJVITG is TRUE), then checking to see if all derivatives are identical to thoseobtained during the first perturbation (i.e., identical to the bit precision of the machineby a REAL equal or .EQ. test). This test is fairly stringent, and it fails if any iterationsare present in the derivative evaluation code, a relatively rare occurrence. Thisguarantees that the state equation:

x.

= F(x, t)

is a true function with no side effects. It returns the same derivative value no matterhow often the function (the model) is evaluated, provided the arguments are identical.

Turn offmessages

Turn off the warning messages by setting system symbol CJVITG (Check JacobianValidity) to FALSE. Setting system symbol TJNITG (Threshold for flagging JacobianNonlinearities) to 1.0 also effectively turns off the messages.

Number ofevaluations

The number of extra derivative evaluations during the Jacobian is determined by bothCJVITG (check Jacobian validity) and TSMITG (two-sided matrix calculation). Thenumber of evaluations per state for the various settings of the flags is as follows:

CJVITG TSMITG evaluationsFALSE FALSE 1FALSE TRUE 2TRUE FALSE 3TRUE TRUE 3

7. Debugging 7.5 Jacobian Messages


Controls andobservables

extend matrix

When calculating the extended state matrices with control and observable variables,the state vector is extended by the controls and the derivative vector by theobservables. In the actual calculation, messages giving row and column number referto this expanded matrix. For example, if there are ten states, three controls, and fourobservables, a messageFunction evaluation not repeatable, row 3refers to the thirdderivative.Function evaluation not repeatable, row 12refers to the second observable,the output of the C matrix, since the first ten rows are states and the last four areobservables.

Seriousness ofnonrepeatable

message

The message that the function is not repeatable is not necessarily bad since the Stiffintegration is fairly forgiving of the accuracy of the Jacobian. However, it is a moreimportant indication than the message regarding nonlinearity (described next), and itdeserves investigation into the source of the problem. Nonrepeatability normallyinvalidates any results from the ANALYZE command (i.e., eigenvalues, zeros, rootloci, or frequency response plots) and for these applications the message is to be takenseriously.

Nonlinearmessage

TheJacobian nonlinear measuremessage refers to Jacobian nonlinearity. An attempthas been made to identify a nonlinear measure which can be estimated from thedifference between the slopes of the derivative function when perturbed positive andwhen perturbed negative. Figure 7-12 shows the function of the stateF(x) with anominal value in the middle of the box where the perturbation results in a smallerslope in the positive direction toF(x+dx) than in the negative direction toF(x-dx). Ifthe system were linear, then the midpoint would lie on the average of the two outerpoints;i.e., at (F(x+dx) - F(x-dx))/2. Any deviation of F(x) from this midpoint impliesa nonlinearity.

Normalizeddifference

A simple difference has units and can not be fixed in value since a change of basis(from meters per second to feet per second, for example) would change the differenceand invalidate any threshold setting. To avoid this problem, the difference isnormalized by the total vertical dimension of the rectangle;i.e., F(x+dx) - F(x-dx). Thenonlinear measure tested can be expressed as follows:

| F(x) − 0.5 (F(x + dx) + F(x − dx)) |

| F(x + dx) − F(x − dx) |

Effect of bowl This expression does not work well if the function lies in the bottom of a bowl; in thiscase, the difference betweenF(x+dx) andF(x-dx) can be a very small number (evenzero), exaggerating any difference ofF(x) from the midpoint. If there is only a verysmall slope between end points, no message is generated;i.e., for EPMX of 1.0E-6 on32-bit systems and 1.0E-9 on 60 and 64-bit systems:

| F(x + dx) − F(x − dx) | < EPMX∗ F(x)

Threshold formessage

The nonlinear measure is tested against a threshold TJNITG (threshold for Jacobiannonlinearity, an ACSL system symbol with a default of 0.1). If the threshold isexceeded, the error message is reported, with the nonlinear measure expressed in a realnumber. The message can be suppressed by setting TJNITG to a large number;1.0E33, for instance.

State at a limit A nonlinear measure of 0.5 may be due to the state sitting at a limit. This is the worstpossible value if the function is monotonic. Assuming a positive limit, a change fromF(x) to F(x+dx) does not change the function value at the limit and theF(x) point liesat the top bar of the rectangle in Figure 7-11. The difference from the midpoint isexactly half of the vertical dimension, thus giving a nonlinear measure of 0.5. If the

7.5 Jacobian Messages 7. Debugging


center point is outside the box of the two end points (a bowl or a roof), then there is nolimit to the size of the nonlinear measure.

Negativemeasure

It is possible for negative values of the Jacobian nonlinear measure to be reportedsince the absolute value is not applied. The actual test is on the absolute value of thedifference between the center point and the average of the two outside points, but thereport prints just the difference, as follows:

(0.5*(CPLUS + CMNUS) - CZERO)/(CPLU - CMNUS + 1.0E-30)

where CZERO is the center function value and CPLUS and CMNUS are the values ofthe positive and negative perturbations. Thus, center function values above the averageof the two ends, or a decreasing slope from left to right, produces a negative value.

It is again to be emphasized that the messages are not necessarily bad, but they serveas a warning that the perturbations are showing up real nonlinearities in the system.

Figure 7-11. Perturbation of state F(x)

7. Debugging 7.5 Jacobian Messages


7.6 Loss ofaccuracy withlarge bias terms

There is a potential problem in evaluating the Jacobian when small terms coexist withlarge ones that nominally cancel. As an example, consider torque applied to an inertiawhere the torque is resisted by a small damping term and a spring. The equations are:

nettorque = appliedtorque - damping - springdamping = k1*thetadot ! k1 is 0.0229spring = k2*theta ! k2 is 0.1500thetadotdot = nettorque/inertia

TheK1 andK2 values give a damping factor of 0.5 and the inertia just time scales theproblem so its value is immaterial.

The problem is with theNETTORQUEequation in equilibrium with say a 100 Nmapplied torque. In equilibrium, the spring action equals the applied torque and thedamping is zero since the velocity is zero (steady state). In calculating the derivative ofthe torque term with respect to velocity (THETADOT) for the Jacobian, a nominalperturbation of 1.0E-4 is applied (which may be much smaller if specified via theXERROR and MERROR statements), resulting in:

deltatorque = 100 + 0.0229*1.0E-4 - 100.0

The middle term is very small compared with the hundred, and so the difference(100.00000229 - 100) is completely lost at single precision; even double precisionloses eight decades of precision (or more if the perturbation has been reduced from thedefault).

The solution to the problem is to group terms with parentheses so that large terms aresubtracted before small ones are included. In the example above, we would write:

nettorque = (appliedtorque - spring) - damping

which results in:

nettorque = (100 - 100) - 0.0229*1.0E-4

and the damping term is evaluated with full precision. On some computer systems,reordering the calculation as follows:

nettorque = appliedtorque - spring - damping

happens to work, but the order of calculation is not guaranteed to be from left to right.Parentheses force the order.

This is a standard problem with numeric differentiation where relatively large constantterms are present in the equations.

7.6 Loss of accuracy with large bias terms 7. Debugging


7. Debugging 7.6 Loss of accuracy with large bias terms


8. Application Notes

This chapter describes a number of advanced application techniques.

8.1 Parametersweep

This example outlines a procedure to set up parametric studies within a program.Parameter sweeps differ from Monte Carlo runs in that Monte Carlo models arepseudo-random (using GAUSS or OU, for example) while parameter sweeps areorderly. This model uses a sequence of runs in which a parameter (P) is varied from alow limit (PMN) to a high limit (PMX) by a certain increment (PDL) between runs.

Program structure The model is programmed in explicit structure. Plots are generated with a set of curvesshowing the parametric variation. The program structure is:

PROGRAM sweepINITIAL

p = pmnloop: CONTINUE

CALL INITDEND ! of initialDYNAMICDERIVATIVE

... model definition (depends on P)...END ! of derivative

TERMT(T .GE. tstop)END ! of dynamicTERMINAL

CALL LOGD(.TRUE.)p = p + pdlIF(p .LE. pmx) GO TO loop

END ! of terminalEND ! of program

INITD utility INITD is a utility routine which clears the event list. The event list notes the times atwhich events (such as DISCRETE sections, communication intervals, SCHEDULEtime events) are scheduled to occur. The list is cleared automatically by a STARTcommand, but not in a loop as described above. See Appendix B for more on INITD.

Runtime The runtime commands are then as follows:

PREPARE t,y1,y2, ...SET FTSPLT=.TRUE.STARTPLOT y1,y2, ...

The independent variable (T) is named as the first variable on the PREPARE list sincethe PLOT command assumes the first PREPARE variable is plotted as the X axis.

Flyback tracesuppression

FTSPLT (flyback trace suppression on plots) is set TRUE to signal the plot commandto lift the pen when the first variable on the PREPARE list is less than its previous


value. At the same time, the symbol character is incremented. Each transition from theINITIAL section into the DYNAMIC section resets the independent variable to itsinitial value. This is the characteristic which allows this structure to work forparametric runs and allows the plots to differentiate the curves.

Single runs Single runs can be easily generated, either by setting the maximum value to theminimum value:

SET pmx=pmn

or by making the increment very large:

SET pdl=1.0E38

Warning –TERMT in

DERIVATIVE

It is possible with this type of loop that if a TERMT statement is in the DERIVATIVEsection and the event list is not cleared, eventually the table space is filled. Theproblem is that when the run stops in the DERIVATIVE section, an event has beenentered on the event list for the next communication interval. Stopping prematurelyleaves the event on the event list. The event list is not cleared because there may be afollowing CONTINUE. This problem does not arise if a call to INITD is included inthe INITIAL section to clear the event list after the loop back. It also does not occur ifthe TERMT statement is in the DYNAMIC section since the event is removed fromthe list at the communication interval and so does not accumulate.

8.2 Phase andgain plots

Phase and gain characteristics of a model forced by a sine wave are often useful. Withthe system described here, the excitation frequency can be varied logarithmically andthe phase and gain characteristics determined and plotted as a function of thisfrequency.

Frequency sweep First a nameW, for frequencyω, is established. This variable is swept from minimum(WMN) to maximum (WMX) by using a geometric progression with multiplierKW(generally set in the range 1.2 to 1.5). The model structure is as follows:

PROGRAM phase and gainINITIAL

w = wmnloop: CONTINUE


... model ...END ! of derivative

TERMT(...)END ! of dynamicTERMINAL

pw = LOG10(w)CALL LOGD(.TRUE.)w = w*kwIF(w .LE. wmx) GO TO loop


While the frequency is varied,PW is calculated for the X axis of the plot to be made;the actual scale will then be logarithmic.

8. Application Notes 8.2 Phase and gain plots


Phase and gain To find the phase and gain, assume that the signal is injected into an equation for thevariableF. The gain and phase betweenF and the output variableX can be expressed:

XF

= G ( j ω )

The in-phase (P) and quadrature (Q) components will be given by the followingequations where the integration is taken over any complete cycle:

P =ωπ ∫

ts

t

X sin (ω t ) dt

Q =ωπ ∫

ts

t

X cos(ω t ) dt

Cycle The key to obtaining correct results is to start the integration after sufficient time haselapsed so that the initial transients have decayed away, then integrate over onecomplete cycle. This can be done by logic within either the DYNAMIC orDERIVATIVE sections; it is usually easier to set the communication interval to forcethe full cycle integration. It is immaterial at what point in the drive sine wave thewindow begins; any whole cycle is sufficient.

Alternativetechnique

The technique described here requires a complete simulation run for each point;i.e.,the model code cycles from TERMINAL to INITIAL every time a new frequencypoint has been calculated. Another way of generating frequency response in a singlerun is described in Section 9 of Appendix A. While the implementation describedthere is fairly complicated, it reduces somewhat the time spent for settling (which iswasted computer time) and also allows more direct control of the phase accuracycalculated.

8.3 Summaryoutput

It is often useful to obtain a complete list of all simulation variable values in order todocument the state of the simulation. Setting NDBUG = 1 gives a picture at the veryfirst derivative evaluation, but this is not as useful as a picture obtained at the end ofthe run. In a final value debug dump, initial conditions are still available in the initialcondition arrays, but all other variables document the termination condition.

In order to easily obtain this final value listing, incorporate the following code in theTERMINAL section:

TERMINALLOGICAL dump ; CONSTANT dump = .TRUE.IF(dump) CALL DEBUG

END ! of terminal

The call to subroutine DEBUG produces the debug dump (explained in detail inChapter 7); having the call under the control of a logical variable that can be set atruntime in order to turn the output on or off is a convenience, especially for interactiveruns.

8.3 Summary output 8. Application Notes


8.4 Impulse andstep response

Determining the response of a system to impulses and steps in the control variables isa common method of checking a simulation model. In most cases it is not necessary touse special operators as these forcing functions can usually be handled by parameterchanges.

Impulse asintegrator output

An actual impulse is of infinite height and zero time width and so is impossible togenerate directly. The effects, however, are felt at all integrators the impulse is fed to,and result is a unity jump in the output of these integrators. The easiest way toimplement this jump in practice is to apply a value to the integrator initial conditionwhich models receiving the impulse immediately prior to time zero. When thesimulation program starts to execute, it then follows a solution trajectory in responseto this hypothetical impulse.

Impulse example As an example, consider a pendulum model described by the equations:

omega = INTEG(-g*SIN(theta)/l, omegaz)theta = INTEG(omega, thetaz)

An impulse in force transferred to the pendulum ball at time zero is modeled byspecifying a nonzero value for the angular rate initial conditionOMEGAZ.Determining this rate may need some calculation since it may involve equationsgoverning momentum transfer. These would apply if, for example, the pendulum bobwere struck with a mallet, and such equations would correctly be placed in theINITIAL section.

If the impulse is applied at times other than time zero, then the integral equation mustbe modified to add in the net integrated impulse;i.e.,

omega = INTEG(-g*SIN(theta)/l, 0.0) + dlomeg

Now the variableDLOMEG(delta OMEGA) is added in and becomes the initialcondition onOMEGA(since the INTEG has an initial condition of zero). In thisconfiguration,DLOMEGcan be changed; and since it is always added to the statevariable or output of the INTEG operator,OMEGAjumps discontinuously when thishappens. IfDLOMEGhas been changed, it must be reset in the INITIAL section priorto the start of each run. It itself becomes an effective state variable. Most cases can behandled by using the initial condition, but when true impulses are applied during a run,then the added variable becomes necessary (see the aspirin example in Appendix A).

Step response Step responses are a different excitation technique, usually handled by adding aconstant (initialized to zero) at a summing junction, but often loops must also bebroken. A typical requirement is to examine the response of a missile (pitch rate, pitchangle, and accelerometer reading) to a step in fin deflection. This would normally beapplied at time zero and the dynamic response recorded. Unfortunately, a simplechange of initial condition on the fin angle integrator is not sufficient since after therun starts, the fin deflection will change due to the dynamics built into the actuatormodel. The key now is to break the outer loop and prevent this fin motion; the easewith which this can be done depends somewhat on the actual fin dynamics modelitself. A simple fin model is a first order lag with a typical time constant of 5 to 50msec, so motion can easily be stopped by setting temporarily the time constant to1.0E30. This very large value ensures that the output will remain constant irrespectiveof what the input does. Alternatively, there may be a gain between torquer andvelocity integrator which can be made zero, thus ensuring zero derivatives and aconstant output.

8. Application Notes 8.4 Impulse and step response


Parameter names For these types of test cases, it is important that model parameter values be givensymbolic names, preset by CONSTANT statements. The symbolic name enters theseinto the ACSL dictionary and the CONSTANT statement is just a preset so valueschanged will not be changed back as they would if they were set via an assignmentstatement. It is not good practice to specify numbers within the code sequence since noname can be assigned to the value and the value itself is always fixed, requiring are-edit of the program in order to effect any changes.

Step example As an example, for a first order lag fin model with a time constant of 20 msec, twochoices are available:

a) REALPL(dl = 0.020, dlc, dlic)

b) CONSTANT tact = 0.020REALPL(dl = tact, dlc, dlic)

The second form is far better since now the variableTACTcan be changed at runtimeby SET commands. For step responses, the following commands could be used atruntime to generate the response for a fixed fin deflection of -10 milliradians:

SET tact=1.0E30, dlic=-0.010START

8.5 Externallydefined variables

It is sometimes necessary to suppress the messageSymbol used but not definedthat isgenerated if names are found that never appear on the left hand side of an equal sign.This happens with external Fortran subroutines that are communicating with theACSL program via the dollar sign in column one (as described in Chapter 1). In orderto tell the ACSL system that these variables are calculated and at the same time enterthe name in the ACSL model dictionary, they may be listed in a dummyPROCEDURAL block placed anywhere in the program.

Consider variablesXF, YF, andZF, which we know to be defined elsewhere. Add thefollowing two lines

PROCEDURAL(xf, yf, zf =)END

This indicates that it is known that the variablesXF, YF, andZF are definedsomewhere. In this method, it is assumed that sorting problems are handled separately.There is no check that the inside of a PROCEDURAL block agrees with theinput/output list stated on the header. While this can be a useful feature, you should becareful when using it.

8.5 Externally defined variables 8. Application Notes


8.6 Stoppingmissiles atintercept

Ensuring that a simulation stops at a defined event is a common problem. A solution isillustrated in the example of stopping a missile simulation at the distance of closestapproach to a target (known as the intercept point). A typical closing velocity for amodern missile is about 1500 meters/second. A typical integration step required for amissile simulation is about 10 msec. An integration step thus corresponds to 15 metersdistance, too coarse an interval to determine miss distance (distance of closestapproach), which should be in the range of 1 to 5 meters.

Warning – avoidsmall steps

A technique which is sometimes used, but which should be avoided, is to switch to amuch finer integration step when intercept is near. Typically, switching to anintegration step of 0.1 msec within a time-to-go of 50 msec allows stopping to within0.15 meters accuracy, adequate for the application. However, the code for this isclumsy and usually difficult to implement.

Forecast intercept The recommended solution is to continually forecast when the intercept will occur andadjust the last communication interval so that the integration routine arrives exactly(neglecting acceleration) at the intercept point. Implementing this method begins withthe relative position and velocity vectors (RMT andVMT), which measure the missilefrom the target motion as though the target has been stopped. The distance to the pointof closest approach is the range vector resolved onto the velocity vector:

RMT ⋅ VMT

VMT

Time-to-go This quantity divided by the magnitude of the relative velocity vector gives the time toclosest approach (i.e., time-to-go) as follows:

TGO =RMT⋅VMT

VMT2

RecomputingCINT

The communication interval (CINT) is continually recomputed in the DYNAMICsection, whereCINTZ is the nominal communication interval, by:

CINT = MIN(tgo, cintz)

CINT notnegative

In addition, however, a precaution to prevent CINT from becoming negative isnecessary. The extrapolation assumes no acceleration, which is a source of inaccuracy,but in practice time-to-go accuracy turns out to be better than 0.1 msec, so a protectionthat the communication interval never goes below a specified minimum and a TERMTstatement to stop the simulation when time-to-go reaches this minimum preventsCINT from becoming negative. The statements might read as follows:

CONSTANT cintmn = 0.0001, cintz = 0.05CINT = MAX(cintmn, MIN(tgo, cintz))TERMT(tgo .LE. cintmn, 'Stop on TGO')

There is still a problem with this formulation if the relative range is increasing atlaunch. Once the motor ignites, a missile accelerates rapidly and overtakes the target,but in the simulation all conditions must be taken into account. In a launch against areceding target, time-to-go will be negative, so both TERMT and CINT must beprotected. This protection can be implemented with aTFLTMN(time of flight

8. Application Notes 8.6 Stopping missiles at intercept


minimum) parameter on TERMT and by makingTGOa large number until theminimum flight time has been exceeded. Then statements for TERMT andTGOare:

TERMT(tgo .LE. cintmn .AND. T .GE. tfltmn, 'Stop on TGO')tgo = RSW(T .GE. tfltmn, tgo, 1.0E30)

This sequence shows the build up of complexity as real-life simulation models aredeveloped and problems with operation are found and resolved. Note that all theproblems have been solved without resorting to IF or GO TO statements.

SCHEDULEsolution

Still another approach to finding the missile intercept point is to introduce aSCHEDULE statement to force an iteration on the sign of the closing velocity. Whenthe dot product ofVMT onRMT changes sign from positive to negative, the interceptpoint is signalled. This implementation of the SCHEDULE statement ignores theinitial crossing of zero at the beginning of the flight when closing velocity changesfrom negative to positive:

SCHEDULE final .XP. DOT(vmt, rmt)

The final iteration is probably not needed for this particular application of a missileintercept, so we would use the forecasting method, but either technique is acceptable.The handler block FINAL that stops the model when a zero crossing has been foundcan be in the form:

DISCRETE finalTERMT(.TRUE., 'Stop at intercept')

END ! of final

Warning –incorrect TERMTwith SCHEDULE

Be careful of using the following with the SCHDULE statement since for theSCHEDULE operator to work, it must actually cross zero prior to iterating; this setsthe stop flag, thereby stopping the run and also the SCHEDULE iteration:

TERMT(tgo .LE. 0.0)

8.7 State spacelinear matrixmodel

The matrix multiply macro listed in Figure 6-2 can be used to solve the dynamics ofthe linear matrix equation:

X.

= [A ] X

The following code fragment handles up to tenth order systems; if fewer than ten statevariables are used, theA array is completed with zeros:

ARRAY x(10,1), xic(10,1), a(10,10)CONSTANT a = <... 100 numeric values...>CONSTANT xic = 1.0, 9*0.0MMUL(xd = a, x)x = INTVC(xd, xic)

The derivative vector (XD) is automatically dimensioned to matchX; i.e., (10,1). Thecode above produces an impulse on the first state in the vector by setting the firstelement in the initial condition vector (XIC) to 1.0; to produce impulses on any otherstates, change the corresponding elements inXIC to 1.0 using a SET command atruntime.

8.7 State space linear matrix model 8. Application Notes


8.8 Full setmatrix operations

The behavior of an error covariance matrix can be modeled based on the followingmatrix differential equation:

Σ.

= A Σ + Σ AT + Ξ − Σ CTC Σ

whereΣ, Σ., A, andΞ are three-by-three matrices andC is a one-by-three vector. The

following mnemonic names are used for programming:

Σ.

≡ SGDΣ ≡ SGΞ ≡ XI

Using the macros defined in Figures 6-2 through 6-6, the calculation can be written onone line as follows:

ARRAY a(3,3), sg(3,3), c(1,3), sgic(3,3)MADD(sgd = MMUL(a, sg), MMUL(sg, MTRANS(a)), xi, &

MNEGAT(MMUL(sg, MTRANS(c)), MMUL(c, sg))))

and the derivative is then integrated using the vector integration operator:

sg = INTVC(sgd, sgic)

Dimensions Only the input matricesA, SG, andC and the initial condition vector (SGIC) need tobe dimensioned. The matrix add (MADD) operator automatically dimensionsSGDtobe (3,3).SGICmust be dimensioned to matchSGfor the vector integration operator.

Intermediatevariable names

In practice, it is probably necessary to calculate some of the intermediate quantities sothat they can be printed, plotted, and checked. The above equations could also beimplemented as follows:

MMUL(ASG = a, sg)MMUL(sgat = sg, MTRANS(a))MMUL(sgct = sg, MTRANS(c))MMUL(csg = c, sg)MADD(sgd = asg, sgat, xi, MNEGAT(MMUL(sgct, csg)))sg = INTVC(sgd, sgic)

Providing values for the input arraysA, C, andSGICdefines the evolution of thesystem. The ANALYZE /TRIM and /EIGEN can be used to determine the eigenvaluesand the appropriate step size for a fixed step integration algorithm.

8.9 Moving timebackwards

Most dynamic simulations move forward in time, as nature does, but some in somesituations it is useful to simulate time (or some other variable) moving backwards.This can be accomplished by establishing an independent variable to integrate in thenegative direction as follows:

CONSTANT timeic = 5.0time = INTEG(-1.0, timeic)

8. Application Notes 8.8 Full set matrix operations


UseTIME (or some other name) rather than the ACSL default independent variableTthroughout the program in calculations, and at runtime in printouts and plots. Anyvariable name may be used. The nameT may also be used if the ACSL default ischanged using the VARIABLE command; for example,

VARIABLE dummy, dumic = 0.0CONSTANT TIC = 5.0T = INTEG(-1.0, TIC)

On a related subject, to start from a negative value of time and move forward, simplyspecify the initial condition ofT using the VARIABLE command;e.g.,

VARIABLE T, TIC =-200.0

8.10 Plottingaverages fromMonte Carloprograms

In running Monte Carlo or parametric programs (such as described in Section 8.1), it issometimes desirable to collect results over a number of runs and plot them. Oneapproach is to set up an array for the variable (an average, for example), an index intothe array, and a calculation for the average as follows:

INITIALDIMENSION avge(100)INTEGER index, runnumindex = 0runnum = 0IF(runnum .EQ. 0) CALL SETR(0.0, avge, 100)runnum = runnum + 1...

ENDDYNAMICDERIVATIVE

...END ! of derivative

index = index + 1aplot = avge(index)avge(index) = (avge(index)*(runnum - 1) + a)/runnum

END ! of dynamic

Note that the average is always the up-to-date average from the beginning of the run; itis calculated on the fly, so to speak, since the average is defined as the sum so fardivided by the total number of runs. The formula for the average multiplies the oldaverage by the previous run number, adds the new value of the variable (A), and thendivides by the current run number.

In the following runtime commands, first the parametric data is generated, then a finalSTART forces a single run. SinceAPLOTis extracted fromAVGEbeforeAVGEisupdated, this last START plays back the previous average.

8.10 Plotting averages from Monte Carlo programs 8. Application Notes


PREPARE t,aplotSTART...STARTSTARTPLOT aplot

With this procedure, each START accumulates a new average. An alternate methodwould be to loop back from the TERMINAL section to the INITIAL section, to justbeforeRUNNUMis incremented, incrementingRUNNUMto some specifiedmaximum as in a parametric run; then only two START commands are required.

The average can be reset by settingRUNNUMto zero prior to a START.

8.11 Plottingarrays

Data collected into arrays can be plotted even when it is not a function of theindependent variable. This is accomplished by cycling through the array elements inthe TERMINAL section, then logging the data to the RRR file with LOGD. Forexample, if an array is filled as a histogram in the DYNAMIC section as follows:

DIMENSION hx(imax)INTEGER i, imaxi = (x - xmin)/(xmax - xmin)*ima x + 1 ! x into imax binsi = MAX(1, MIN(imax, i)) ! limit overflowhx(i) = x(i) + 1 ! increment element

Then in the TERMINAL section:

DO 110 i=1, imaxh = hx(i)a = (xmax - xmin)*(i - 1)/imax - xminCALL LOGD(.FALSE.)110..CONTINUE

At runtime, add the variablesH andA (the abscissa) to the PREPARE list and plot:

ACSL> PREPARE a,h, ...ACSL> STARTACSL> PLOT /XAXIS=a h

Since data logging during the run saves values forH andA that don't correspond toany calculated value, the values ofH andA should be initialized in the INITIALsection; zero is probably a good number to choose:

h = 0a = 0

8. Application Notes 8.11 Plotting arrays


8.12 Callingsubroutines in C

Subroutines written in C can be called from ACSL. Just be sure arguments arereceived as pointers since FORTRAN passes variables by reference. For example, thefollowing in ACSL:

INTEGER aREAL bDOUBLEPRECISION cCALL foo(a, b, c)

should appear as follows in C:

voidfoo_(int*a, float*b, double*c){...}

Place all the routines in a library and link the library to the program object code at linktime (see the documentACSL Sim User's Guidefor details).

Underscore Most Unix Fortran systems append an underscore (_) to external C names, which iswhy the entry pointfoo in the example above on Unix systems is shown as:

foo_(...)

As function C routines can also be called as functions from ACSL; in the following calls, Xx isoutput.

x = foo(a)

Example Here is an ACSL program to demonstrate the interface between ACSL and C.VECTEST.CSL is an ACSL program that demonstrates a call to subroutineVECADD.C. There are two methods for calling the C subroutine: using an equal signin the argument list, or calling from within a PROCEDURAL.

program vecadd! demonstrate interface to C with a vector addition operator!array x(3), y(3)constan t x = 1.0, 2.0, 3.0constan t y = 10.0, 20.0, 30.0

!-----call the C routine using an equal sign in the arg listarray sumxy(3)call vecadd(sumxy = x, y)

!-----now do it with a proceduralarray sum(3)procedural(sum = x, y)

call vecadd(x, y, sum)end ! of procedural

termt(.true.)

end ! of program

8.12 Calling subroutines in C 8. Application Notes


The C subroutine contains ifdef statements to handle differences between varioussystems such as Cray, Microsoft PowerStation, Watcom, and VMS. VECADD.C is anexample that should work on any known system. IFDEF's are only needed for thosesystems that are not standard.

/* *********************************************************** PURPOSE: demonstrate C interface to ACSL programs** INPUTS: two single precision vectors ("a" amd "b")* OUTPUTS: the single precision sum of the input vectors*** ******************************************************/

#ifdef cray#define vecadd_ VECADD#endif

#ifdef usoft#define vecadd_ __stdcall VECADD#endif

#ifdef watcom#pragma aux VECADD "*"#define vecadd_ VECADD#endif

#ifdef vms#define vecadd_ vecadd#endif

voidvecadd_(a, b, c)float *a, *b, *c;{

*c++ = *a++ + *b++;*c++ = *a++ + *b++;*c = *a + *b ;

}

Run the model as follows, compiling the C routine first and adding its object file to theACSL command.

cc -c vecadd.cacsl vectest vecadd.oACSL> display/allACSL> startACSL> display/allACSL> quit

On the Cray, Microsoft PowerStation, Watcom, or VMS system, add the appropriate-D flags to the C compiler command line (i.e., cc -Dcray -c).

8. Application Notes 8.12 Calling subroutines in C


8.13SynchronizingDISCRETE events

Let's say your model has three DISCRETE sections that run at 1.0, 0.1, and 10.0second intervals. What happens at the 10 second interval? If you do not care about theorder of execution of the three DISCRETE sections when their events coincide, theneach section can be described with its own INTERVAL statement:

DISCRETE aINTERVAL dta = 1.0

...END ! of aDISCRETE b ! section with

INTERVAL dtb = 0.1 ! relatively... ! small interval

END ! of bDISCRETE c ! section with

INTERVAL dtc = 10.0 ! relativelyEND ! of c ! large interval

With this structure, the relative order of execution of the sections is indefinite at the1.0 second and 10 second intervals. If these sections control independent processesthat do not depend on each other and are in fact unsynchronized in the real world, thenthis model is a good representation.

When you are modeling major and minor cycles of the same process, it is oftennecessary to specify who goes first, what goes second, and I don't know goes third.You accomplish this by putting an INTERVAL statement only in the section to beexecuted first in the case of a tie. Then SCHEDULE statements activate the othersections in the order desired.

In the example above, assume the order desired to be:

ABC at 0.0 and at every 10 seconds thereafterAB at every 1.0 second interval

This order can be set up by the code outlined below. The code in section A determineshow many times (countb ) section B is to be executed for each cycle of section A.This demonstrates a technique for controlling a high frequency DISCRETE section.

The code in section B determines how many times (countc ) section B is to beexecuted before activating section C. This demonstrates a technique for controlling alow frequency DISCRETE section.

The time whenindexc equalscountc can also be checked with a modulus (orremainder) operator;e.g.,

indexc = MOD(indexc, countc) + 1IF(indexc .EQ. 1) THEN...ENDIF

In a model like this, you may want to record data every second, including the data thatchanges every ten seconds. Do this by including a CALL LOGD(.TRUE.) at the endof sections B and C. If you want to graphically show (plot) the discrete nature of whatis happening at every second, add another call to LOGD at the beginning of section B,which will square up the plots of variables calculated between two calls.

8.13 Synchronizing DISCRETE events 8. Application Notes


DISCRETE a ! first sectionINTERVAL dta = 1.0 ! in sequence...

INITIALINTEGER countb ! count for bcountb = dta/dtb + 0.5 ! rounded up

END ! of initialDO schedb j=1, countb ! loop toSCHEDULE b .AT. t+(j-1)*dtb ! schedule b

schedb..CONTINUEEND ! of a

DISCRETE bCONSTANT dtb = 0.1 ! section with... ! small interval

INITIALINTEGER countc, indexc ! count for ccountc = dtc/dtb + 0.5 ! rounded upindexc = countc ! c counter

END ! of initialIF(indexc .EQ. countc) THEN

indexc = 0 ! schedule cSCHEDULE c .AT. t ! when counted

ENDIF ! time reachedindexc = indexc + 1

END ! of b

DISCRETE c ! section withCONSTANT dtc = 10.0 ! relatively... ! large interval

END ! of c

8. Application Notes 8.13 Synchronizing DISCRETE events


A. ACSL Example Programs

Introduction

The following example programs illustrate the use of ACSL. Each problem isdescribed physically and mathematically, the ACSL code and features are explained,and the program and its printed and plotted output are shown.

The computer input for each example consists of two files: the model source and theruntime commands. The model source code describes the model under examination. Inmost cases the model can be considered to be parallel;i.e., variables need not becalculated prior to their use. The translator will rearrange the program until it is incorrect sequence for execution. On the other hand, runtime commands are sequential;they tell the model what to do next. A minimum of a START command is necessary toexercise a model. Listings of the model source code and runtime commands areincluded in each of the examples.

In the examples we have capitalized the ACSL keywords to differentiate them fromnames and text, which are model-dependent. However, ACSL is not case sensitive.You can use any case in your programs and at runtime. The exception is the TITLEarray, which is reproduced in printouts and plots in upper and lower case as given.

Outputs from the simulation runs include printouts and line plots. Although the fullthirteen inch width of the line printer is available in ACSL, the output shown here isdesigned to fit on standard A size paper (81⁄2 x 11 inches) where possible for ease ofreproduction. The width of output viewed at the terminal is controlled by the ACSLsystem variable TCWPRN (terminal character width), and the width of log file (orprint logical unit) is PCWPRN (printer character width). In these examples, TCWPRNis set to 72 and PCWPRN to 80 so the output fits on an 81⁄2 inch wide page.

1. Limit Cycle

This example illustrates a simple nonlinear model and the runtime commands requiredto run the program. A limit cycle in the XY plane is described by the equations:

x.

= y +Kx (1 − x2 − y2 )

√x2 + y2

y.

= − x +Ky (1 − x2 − y2 )

√x2 + y2

where:

x(0) = xzy(0) = yz

The limit cycle is a circle of radius 1.0; that is, no matter what initial conditions areimposed onx andy (exceptx = y = 0), (x2 + y2 ) → 1 ast → ∞.

ACSL Reference Manual Page A-1

The source code for this model is shown in Figure A1-1. SQ defines the root sumsquare value as a named item so that it can be listed and plotted. Calculating acommon subexpression only once also saves computer execution time, and so KK isalso calculated separately. X and Y specify the integration equations. The expressionsfor the derivatives are placed directly in the INTEG arguments along with the initialconditions. They could be named and calculated in separate statements (as XD andYD, for example) so they could be plotted and/or printed. Breaking out suchcalculations is often helpful in debugging programs.

Every program must have a termination condition, expressed in a TERMT statement.In this case, the program stops when time becomes equal to or greater than TF. TF isspecified in a CONSTANT statement as slightly less than the desired termination timeof 10 sec. If it were to be specified exactly 10.0, an extra integration step would betaken since equality is rarely obtained in floating point numbers. The value of T,obtained by summing many small increments, will in general be slightly less than theexact value. By terminating at just under 10.0, we automatically have a plot scalewhich makes the best use of the plot area. If the model stops after 10.0, the plot scalesautomatically to 20.0, the next rounding point.

The runtime commands are listed in Figure A1-2 and a log of the runtime session inFigure A1-3. The runtime commands may be entered interactively, from a commandfile, or in batch mode. See the documentACSL Sim User's Guidefor instructions onexecuting an interactive ACSL runtime session, using a command file, or running inbatch mode.

DERIVATIVE ! limit cycle!-----------------------define all the preset variablesCONSTANT xz = 0.5 , yz = 1.0CONSTANT k = 0.2 , tf = 9.99CINTERVAL cint = 0.2 ! communication interval!-----------------------give name to radius valuesq = SQRT(x**2 + y**2)!-----------------------common factorkk = (1.0 - sq**2)/sq!-----------------------limit cycle equationsx = INTEG( y + k*x*kk, xz)y = INTEG(-x + k*y*kk, yz)!-----------------------define stopping conditionTERMT(t .ge. tf, 'Time Limit')

END ! of derivative

Figure A1-1. Limit cycle model

SET TITLE = 'Limit Cycle Example'SPARESET TCWPRN=72 ! Force 3 column output widthOUTPUT t,x,y,sq/NCIOUT=5 ! Define list to be printed during runPREPARE t,x,y,sq ! Define list to be saved for later useSTARTPLOT x,y,sq ! Plot as function of timePLOT/XAXIS=x,y ! Phase plane plotSPARE ! List execution timeQUIT

Figure A1-2. Limit cycle runtime commands

A. ACSL Example Programs A1. Limit Cycle

Page A-2 ACSL Reference Manual

SPARE is a utility which gives the accumulated and elapsed cp time by default. It iscalled SPARE because it is available to be linked to a user-supplied subroutine forruntime invocation. Finding the elapsed cp time is useful for comparing the executiontimes of various runs, integration algorithms, etc.

The OUTPUT command lists the variables to be output at the terminal (and echoed onthe PRN unit) during the run. The /NCIOUT switch is set to five so that output isreduced to only every fifth communication interval (every second).

ACSL Runtime Exec Version 6 Level 10A 9-DEC-90 16:48:11 Page 1

SET TITLE = 'Limit Cycle Example'SPAREAccumulated cp time 15.19000. Elapsed cp time 0.SET TCWPRN=72 ! Force 3 column output widthOUTPUT t,x,y,sq/NCIOUT=5 ! Define list to be printed during runPREPARE t,x,y,sq ! Define list to be saved for later useSTART

T 0. X 0.50000000 Y 1.00000000SQ 1.11803000

T 1.00000000 X 1.07143000 Y 0.11524400SQ 1.07761000

T 2.00000000 X 0.65941100 Y-0.81887100SQ 1.05137000

T 3.00000000 X-0.32732300 Y-0.98097500SQ 1.03414000

T 4.00000000 X-0.99128100 Y-0.25178700SQ 1.02276000

T 5.00000000 X-0.74193800 Y 0.69293300SQ 1.01520000

T 6.00000000 X 0.18130800 Y 0.99375800SQ 1.01016000

T 7.00000000 X 0.93107100 Y 0.38308500SQ 1.00680000

T 8.00000000 X 0.82357300 Y-0.57520100SQ 1.00455000

T 9.00000000 X-0.03897800 Y-1.00229000SQ 1.00305000

Time LimitT 10.0000000 X-0.86359200 Y-0.50823200

SQ 1.00204000

PLOT X,Y,sq ! Plot as function of timeDrawing plot number 1PLOT/XAXIS=x,y ! Phase plane plotDrawing plot number 2SPARE ! List execution timeAccumulated cp time 18.29000. Elapsed cp time 3.100000QUIT

Figure A1-3. Limit cycle log file

A1. Limit Cycle A. ACSL Example Programs


PREPARE specifies which variables are to be collected for later printing or plotting.START initiates the run, with output appearing during the run. When the run iscompleted, the first PLOT command is given, producing the plot in Figure A1-4. Ascan be seen, X and Y are sinusoidal and the root sum square value SQ approaches 1.0.

A phase plane plot, in which Y is plotted against X, is shown in Figure A1-5. X isspecified as the X axis variable with the PLOT switch /XAXIS.

Another SPARE command produces the elapsed cp time from the beginning of theruntime session, and QUIT returns you to the computer operating system.

You can exercise the model by changing the values of the CONSTANTs (XZ, YZ, K)with SET commands followed by another START command, etc.

Figure A1-4. Limit cycle time plot

Figure A1-5. Limit cycle phase plane plot

A. ACSL Example Programs A1. Limit Cycle


2. Spring

The spring damping example illustrates the use of the RANGE command and theeffect of setting scales with the PLOT command. It is written in English units of lbs,slugs, and seconds and demonstrates the complexities involved when we have to useslugs as the unit of mass even though colloquially we talk of mass in lbs. A muchbetter system is the SI (System Internationale) set of units where force, mass, and timeare expressed in Newtons, kg, and seconds.

Figure A2-1 shows a spring supporting a mass with a viscous damper attached. Thissystem can be modeled by a linear second order differential equation derived bywriting the expression for the force acting on the mass and then using Newton's Lawto calculate the acceleration. Ifx is the linear displacement of the spring, the springrestoring force is-Ax lbs, whereA is the spring constant (lbs/ft). The viscous dampingis proportional to the velocity and opposing it;i.e., −Kx

.lbs, whereK is the coefficient

of viscous friction in lbs/(ft/sec). IfW is the weight in lbs attached to the spring(tending to extend it), then the mass isW ⁄ g slugs, whereg is the acceleration due togravity. With this, Newton's Law can be expressed:

Wg x

..= W − Kx

.− Ax

Dividing both sides of the above equation byW ⁄ g, the expression for the highestderivative is obtained and then integrated twice:

x..

=W − Kx

.− Ax

Wg

x.

= ∫ x..

dt

x = ∫ x.

dt

Figure A2-1. Spring with weight and damper

A2. Spring A. ACSL Example Programs


Figure A2-2 shows the ACSL program statements that represent the dynamics of themass when it is released. Note the alternate way of obtaining time by integrating aconstant one.

The runtime commands for this model are shown in Figure A2-3, the log file in FigureA2-4, and the resulting plots in Figures A2-5, 6, and 7.

The communication interval is defined in the model code to be 0.02 seconds; with atime limit of 4 seconds, 201 data points are logged and result in smooth plots. Sincethe /NCIOUT switch is set to 20, only eleven lines of OUTPUT are listed, enough tosee that the program is executing and the results appear as expected.

The RANGE command tells you the maximum and minimum value of each variablespecified over the length of the run. /ALL specifies all variables on the PREPARE list.This information can be used to check the validity of the results or plan plot scales, forexample.

PROGRAM springDERIVATIVE

!-----------------------spring damping problem. models releasing! a mass from initial conditions of zero! velocity and displacementCINTERVAL cint = 0.02!-----------------------define model default constantsCONSTANT k = 0.02 , a = 1.0 , g = 32.2CONSTANT w = 1.0!-----------------------another way of changing the independent! variabletime = INTEG(1.0, 0.0)!-----------------------calculate accelerationxdd =(w - k*xd - a*x)/(w/g)!-----------------------integrate accel for velocity and positionCONSTANT xic = 0.0 , xdic = 0.0xd = INTEG(xdd, xdic)x = INTEG(xd , xic )!-----------------------specify termination conditionCONSTANT tstp = 3.99TERMT(t.ge.tstp, 'Time Limit')

END ! of derivativeEND ! of program

Figure A2-2. Spring model source code

SET TITLE = 'Spring Damping Example'SPARESET TCWPRN=72 ! Force 3 column output widthOUTPUT/NICOUT=20 time,xdd,xd,xPREPARE xdd,xd,time,xSTARTRANGE/ALL ! List maximum and minimum valuesPLOT/XAXIS=time ! Set time as x-axis for subsequent plotsPLOT x,xd ! Use automatic scalingPLOT x/HI=1.0/LO=0.0,xd ! Force scales for X out of rangePLOT/XAXIS=xd x ! Phase plane plotSPARE ! List execution timeQUIT

Figure A2-3. Spring example runtime commands

A. ACSL Example Programs A2. Spring



SET TITLE = 'Spring Damping Example'SPAREAccumulated cp time 17.79000. Elapsed cp time 0.SET TCWPRN=72 ! Force 3 column output widthOUTPUT/NCIOUT=20 time,xdd,xd,xPREPARE xdd,xd,time,xSTART

TIME 0. XDD 32.2000000 XD 0.X 0.

TIME 0.40000000 XDD-19.3714000 XD 3.83669000X 1.52486000

TIME 0.80000000 XDD-3.06642000 XD-4.32187000X 1.18167000

TIME 1.20000000 XDD 18.4264000 XD 1.90302000X 0.38969000

TIME 1.60000000 XDD-18.3866000 XD 1.19672000X 1.54708000

TIME 2.00000000 XDD 6.46987000 XD-2.81891000X 0.85545100

TIME 2.40000000 XDD 6.92303000 XD 2.25044000X 0.73999000

TIME 2.80000000 XDD-12.7991000 XD-0.35627900X 1.40461000

TIME 3.20000000 XDD 9.06683000 XD-1.33804000X 0.74518200

TIME 3.60000000 XDD-0.32093100 XD 1.78262000X 0.97431400

Time LimitTIME 3.99200000 XDD-6.92517000 XD-0.91957400

X 1.23346000

RANGE/ALL ! List maximum and minimum valuesXDD-27.0957000 32.2000000

XD-4.35500000 5.20222000TIME 0. 3.99200000

X 0. 1.83607000PLOT/XAXIS=time ! Set time as x-axis for subsequent plotsDrawing plot number 1PLOT x,xd ! Use automatic scalingDrawing plot number 2PLOT x/HI=1.0/LO=0.0,xd ! Force scales for X out of rangeDrawing plot number 3PLOT/XAXIS=xd x ! Phase plane plotDrawing plot number 4SPARE ! List execution timeAccumulated cp time 24.44000. Elapsed cp time 6.650000QUIT

Figure A2-4. Spring example runtime log

A2. Spring A. ACSL Example Programs


The first PLOT command specifies the variable for the X axis. If we did not specifythis, ACSL would use the first item on the PREPARE list as the default (XDD in thiscase). The X axis switches remain in effect until explicitly changed. The second PLOTcommand produces the time plot in Figure A2-5, which shows the sinusoidal motionand damping of X and XD.

The /HI and /LO switches on the third PLOT command force the scales for X out ofrange as shown in Figure A2-6. This illustrates how interpolation is performed to findthe intersection points with the edge of the plot so that the slope at the boundaries iscorrect. Sections of the curve that are off the plot area are not drawn.

Figure A2-7 is a phase plane plot of X against XD.

Figure A2-5. Spring time plot Figure A2-6. Spring plot with forced scale

Figure A2-7. Spring phase plane plot

A. ACSL Example Programs A2. Spring


3. Control Loop

The control loop program illustrates how ACSL macros are used to represent transferfunctions from a system block diagram. It also demonstrates the use of a runtimeprocedure (PROCEDURE). The design is of a lead-lag controller for a second orderplant that has a measurement device containing a first order lag (real pole). FigureA3-1 shows the system block diagram. Constants in the model are as follows:

T1 = 0.020 sec K1 = to be determined A= 0.012 sec2

T2 = 0.005 sec K2 = 0.5 B = 0.200 secT3 = 0.002 sec K3 = 1.0

The model code is shown in Figure A3-2. The communication interval (CINT) isdefined to be 5 msec, a step in input (TZ) is applied at 20 msec, and the transient isallowed to run to the stop time (TSTP) of 499 msec or 100 recorded data points. Thetransfer function operators REALPL, CMPXPL, and LEDLAG are embedded in theexpressions on the right side of the equal sign. This form of the macro invocation isacceptable when the output is a single numeric quantity, and in fact such operators canbe nested to any depth desired. An alternate form of invoking the macros would be asfollows for the three lines calculating XM, X, and U, respectively:

REALPL(xm = ta3, k3*x, 0.0)CMPXPL(x = a, b, k2*xp)LEDLAG(u = ta1, ta2, k1*e, 0.0)

This standalone form of the macro invocation is sometimes preferable since it restrictsgeneration of dummy names (in the form Znnnnn). In changing to the standaloneform, the above takes advantage of the property of linear operators that pre- andpost-multiplication by scalars are equivalent.

In the runtime commands (Figure A3-3), the OUTPUT and PREPARE lists arespecified and a procedure GO defined. The commands between the PROCEDURE andits matching END are saved and not executed. Then two runs are made using thePROCEDURE as a command, the first run with K1 equal to 100.0 and the second withK1 at 10.0. Each GO invokes the START and PLOT sequence saved in thePROCEDURE. Figures A3-4 shows the log file resulting from the runtime commands,and Figures A3-5 and A3-6 are the plots.

Figure A3-1. Control Loop Block Diagram

A3. Control Loop A. ACSL Example Programs


PROGRAM loop!-----------------------communication intervalCINTERVAL cint = 0.005!-----------------------output of first order lag is measurementCONSTANT k3 = 1.0 , ta3 = 0.002xm = k3*REALPL(ta3, x, 0.0)!-----------------------forcing functionCONSTANT tz = 0.02xc = STEP(tz)!-----------------------error between reference and measurede = xc - xm!-----------------------controller outputCONSTANT k1 = 50.0 , ta1 = 0.020 , ta2 = 0.005u = k1*LEDLAG(ta1, ta2, e)!-----------------------define 2-nd order plantCONSTANT k2 = 0.5 , a = 0.012 , b = 0.200x = k2*CMPXPL(a, b, u)!-----------------------specify termination conditionCONSTANT tstp = 0.499TERMT(t.GE.tstp, 'Time Limit')

END ! of program

Figure A3-2. Control loop model code

SET TITLE = 'Control Loop Example'SPARESET TCWPRN=72 ! Force 3 column output widthOUTPUT t,xc,e,u,x/NCIOUT=10PREPARE t,xc,e,u,x,xmPROCEDURE goSTARTPLOT x,xc,xm/SAME,e ! Force same scales for command and

! measured - first variable is referenceEND ! of procedure

! Make two runs and produce plots of eachSET k1=100.0 ; go ! High gain, plot oneSET k1=10.0 ; go ! Low gain, plot twoSPARE ! List execution timeQUIT

Figure A3-3. Control loop runtime commands

A. ACSL Example Programs A3. Control Loop



SET TITLE = 'Control Loop Example'SPAREAccumulated cp time 30.31000. Elapsed cp time 0.SET TCWPRN=72 ! Force 3 column output widthOUTPUT t,xc,e,u,x/NCIOUT=10PREPARE t,xc,e,u,x,xmPROCEDURE goSTARTPLOT x,xc,xm/SAME,e ! Force same scales for command and

! measured - first variable is referenceEND ! of procedure

! Make two runs and produce plots of eachSET k1=100.0 ; go ! High gain, plot oneSTART

T 0. XC 0. E 0.U 0. X 0.

T 0.05000000 XC 1.00000000 E-0.34333400U-78.7033000 X 1.36501000

T 0.10000000 XC 1.00000000 E 0.06227730U 4.46694000 X 0.94377200

T 0.15000000 XC 1.00000000 E 0.01899680U 2.65121000 X 0.98016900

T 0.20000000 XC 1.00000000 E 0.01921870U 1.88171000 X 0.98078600

T 0.25000000 XC 1.00000000 E 0.01964500U 1.96027000 X 0.98036300

T 0.30000000 XC 1.00000000 E 0.01960870U 1.96161000 X 0.98039100

T 0.35000000 XC 1.00000000 E 0.01960740U 1.96074000 X 0.98039300

T 0.40000000 XC 1.00000000 E 0.01960780U 1.96077000 X 0.98039200

T 0.45000000 XC 1.00000000 E 0.01960780U 1.96078000 X 0.98039200

Time LimitT 0.49950000 XC 1.00000000 E 0.01960780U 1.96078000 X 0.98039200

PLOT x,xc,xm/SAME,e ! Force same scales for command andDrawing plot number 1

! measured - first variable is referenceSET k1=10.0 ; go ! Low gain, plot twoSTART

T 0. XC 0. E 0.U 0. X 0.

T 0.05000000 XC 1.00000000 E 0.75738200U 5.99485000 X 0.26580700

T 0.10000000 XC 1.00000000 E 0.23426900U 1.07450000 X 0.78126900

Figure A3-4. Control loop log file

A3. Control Loop A. ACSL Example Programs


T 0.15000000 XC 1.00000000 E 0.02159260U-0.03372380 X 0.98063500

T 0.20000000 XC 1.00000000 E 0.05584250U 0.80529000 X 0.94062000

T 0.25000000 XC 1.00000000 E 0.14417800U 1.67291000 X 0.85293700

T 0.30000000 XC 1.00000000 E 0.18782500U 1.94275000 X 0.81151400

T 0.35000000 XC 1.00000000 E 0.18682100U 1.83494000 X 0.81368300

T 0.40000000 XC 1.00000000 E 0.17240800U 1.68318000 X 0.82811200

T 0.45000000 XC 1.00000000 E 0.16383700U 1.62366000 X 0.83632400

Time LimitT 0.49950000 XC 1.00000000 E 0.16309100U 1.63467000 X 0.83684500

PLOT x,xc,xm/SAME,e ! Force same scales for command andDrawing plot number 2

! measured - first variable is referenceSPARE ! List execution timeAccumulated cp time 38.68000. Elapsed cp time 8.370000QUIT

Figure A3-4. Control loop log file (continued)

Figure A3-5. Control loop input step XC,output X, and measurement XM to same

scales plus error E for K 1 = 100

Figure A3-6. Control loop input step,output, measurement, and error for K 1 = 10

A. ACSL Example Programs A3. Control Loop


4. Pilot EjectionStudy

The pilot ejection example illustrates explicit program structure (explained in Chapter3), the ACTION command (see Chapter 5), and the debug facility (described in detailin Chapter 7). An IF-THEN-ELSE block is also used in the example.

The purpose of the pilot ejection study is to determine the trajectory of a pilot ejectedfrom a fighter aircraft in order to ascertain whether he will strike the vertical stabilizerof the aircraft. Several combinations of aircraft speed and altitude are investigatedsince the drag on the pilot, causing his relative horizontal motion with respect to theaircraft, is a function of air density and velocity (squared).

The ejection system is devised so that it causes the pilot and his seat to travel alongrails at a specified exit velocity (VE) at an angle (θE) backward from vertical. The seatbecomes disengaged from the rails atY = Y1. This first phase of the ejection isillustrated in Figure A4-1.

Once the pilot and seat unit leaves the rails, it follows a ballistic trajectory which canbe determined; however, since it is therelativemotion of the pilot with respect to theaircraft (which is assumed to fly level at constant speed) that is important, theequations are formulated to obtain this trajectory directly. This phase of the ejection isshown in Figure A4-2.

The equations which govern the motion are stated as follows:

x.

= V cosθ − VA

y.

= V sin θV.

= 0 ; 0 ≤ y < y1

V.

= − D ⁄ m − g sin θ ; y ≥ y1

θ.

= 0 ; 0 ≤ y < y1

θ.

= − ( g cosθ ) ⁄ V ; y ≥ y1

D = ρ CD s V2 ⁄ 2

Figure A4-1. First Phase of Ejection

A4. Pilot Ejection Study A. ACSL Example Programs


whereD is drag,CD is the aerodynamic drag coefficient,m is the mass of the pilot andseat,g is the acceleration of gravity,ρ is air density, ands is the effectivecross-sectional area of the pilot and seat. The following two cases are examined:

Case 1: VA = 900 ft ⁄ sCase 2: VA = 500 ft ⁄ s

The air density for sea level is used for both the cases run in this example, but in a fullstudy, the effects of air density would also be examined.

ρ = 2.3769 x 10−3 slugs⁄ ft3 (sea level)

The other constants are set as follows:

m = 7 slugsg = 32.2 ft/s2

CD = 1s = 10 ft2

y1 = 4 ftθE = 15 deg (15/57.3 rad)VE = 40 ft/sec

The initial values of V andθ (pilot's initial velocity vector at the moment of leavingthe cockpit rails) are calculated in the INITIAL section of the program (using thenames VIC and THIC) by the equations:

V (0) = √(VZ − VE sin θE )2 + ( VE cosθE )2

θ (0) = tan−1 VE cosθE

VA − VE sin θE

X(0) and Y(0) are zero. Initial conditions are calculated in the INITIAL section, whichis evaluated just once before the DERIVATIVE section is evaluated and time movesforward. The initial condition table is transferred to the state table before theDERIVATIVE section is evaluated.

Figure A4-2. Space Trajectories of Vehicle and Pilot

A. ACSL Example Programs A4. Pilot Ejection Study


A run is terminated when any one of the following conditions occurs:

x ≤ -60 ft (pilot beyond vertical stabilizer)y ≥ 30 ft (pilot well above 12 ft high tail)t ≥ 4.0 sec

The program for this example is shown in Figure A4-3. The TERMT statements at theend of the DYNAMIC section define the termination conditions. They are interrogatedevery communication interval; as soon as one of the conditions becomes true, the stopflag is set and control is handed back to the runtime executive.

PROGRAM ejectionINITIAL

!-----------------------ejection angle in radians from degreesCONSTANT thedeg = 15.0 , degrad = 57.3the = thedeg/degrad!-----------------------seat initial velocity componentsCONSTANT ve = 40.0 , va = 900.0vx = va - ve*SIN(the)vy = ve*COS(the)!-----------------------total velocity and angle from horizontalvic = SQRT(vx**2 + vy**2)thic = ATAN2(vy, vx)

END ! of initialDYNAMIC

!-----------------------communication intervalCINTERVAL cint = 0.01

DERIVATIVE

!-----------------------relative positionsx = INTEG(v*COS(th) - va, 0.0)y = INTEG(v*SIN(th), 0.0)!-----------------------space velocity and flight path angleCONSTANT mass = 7.0, g = 32.2v = INTEG(rail*(-d/mass - g*SIN(th)), vic)th = INTEG(rail*(-g*COS(th)/v), thic)!-----------------------compute dragCONSTANT cd = 1.0, s = 10.0, ro = 0.0023769d = 0.5*ro*cd*s*v**2!-----------------------use if/then else for switch to keep seat! constrained to guide rails.CONSTANT y1 = 4.0IF(y.LT.y1) THEN

rail = 0.0ELSE

rail = 1.0ENDIF

END ! of derivative!-----------------------specify termination conditionsTERMT(x.LE.xmn, 'Distance Limit') ; CONSTANT xmn = -60.0TERMT(y.GE.ymx, 'Height Limit') ; CONSTANT ymx = 30.0TERMT(t.GE.tmx, 'Time Limit') ; CONSTANT tmx = 4.0

END ! of dynamicEND ! of program

Figure A4-3. Pilot ejection program



The value of RAIL (either 0.0 or 1.0) is controlled within an IF-THEN-ELSE blockthen used in the calculation of V and TH (θ).

At runtime, the following outputs are requested:

Print t, θ, V, X, Y, andD every 0.01 secPlotθ, V, X, and YversustPlotX versusY

The log file from running the model is shown in Figures A4-4 and A4-7, and the plotsare shown in Figures A4-5, A4-6, and A4-8. The runtime commands can be enteredinteractively or from a command file. The method for using a command file dependson your computer system; for further information, seeACSL Sim User's Guide.

ACSL Runtime Exec Version 6 Level 10B 15-FEB-91 13:57:45 Page 1

SET TITLE = 'Pilot Ejection'SPAREAccumulated cp time 28.46000. Elapsed cp time 0.SET TCWPRN=72,PCWPRN=80 ! Force 3 column output widthOUTPUT t,th,v,x,y,d/NCIOUT=5PREPARE t,th,v,x,ySTART

T 0. TH 0.04340250 V 890.487000X 0. Y 0. D 9424.01000

T 0.05000000 TH 0.04340250 V 890.487000X-0.51760200 Y 1.93186000 D 9424.01000

T 0.10000000 TH 0.04340250 V 890.487000X-1.03521000 Y 3.86372000 D 9424.01000

T 0.15000000 TH 0.04167640 V 832.329000X-2.92273000 Y 5.70253000 D 8233.24000

T 0.20000000 TH 0.03967530 V 777.340000X-7.74561000 Y 7.33859000 D 7181.29000

T 0.25000000 TH 0.03753730 V 729.162000X-15.1368000 Y 8.79211000 D 6318.71000

T 0.30000000 TH 0.03526240 V 686.604000X-24.7875000 Y 10.0802000 D 5602.65000

T 0.35000000 TH 0.03285050 V 648.737000X-36.4412000 Y 11.2170000 D 5001.71000

T 0.40000000 TH 0.03030150 V 614.827000X-49.8830000 Y 12.2146000 D 4492.49000

Distance LimitT 0.44000000 TH 0.02816380 V 590.149000X-61.8006000 Y 12.9191000 D 4139.08000

PLOT/XAXIS=t, th, v, x, y ! Time historiesDrawing plot number 1PLOT/XAXIS=x/XLO=xmn y ! Geometrical x vs.yDrawing plot number 2

Figure A4-4. Pilot ejection log file (part 1)



A title is established, SPARE gives the accumulated and elapsed cp time, and theterminal and log file widths are set for narrow printout. Next, the OUTPUT andPREPARE lists are defined and the first run is generated (with the START command)using the default parameter values defined in the program (i.e., aircraft velocity of 900ft/sec.). As the run progresses, OUTPUT values are listed every five communicationintervals (0.05 sec). The run stops at 0.44 seconds with the messageDistance Limitfrom the TERMT statement indicating that X has become more negative than theminimum specified (-60 ft).

Figure A4-5 shows the time histories (i.e., where the X axis variable is T). Correlatingthe curves with the printed OUTPUT data, we see that (from the top) X starts at zeroand decreases,θ starts at 0.0434 rad and decreases after 0.1 sec, V starts at 890 ft/s anddrops off after 0.1 sec, and Y starts at zero and increases.

Figure A4-6 is a trajectory plot. The X axis is X (the relative distance of the pilotalong the aircraft from the cockpit, negative towards the tail). At 60 ft., the pilot justclears the 12 ft. high tail. Note that this PLOT command specifies /XLO = XMN or-60 ft. so that the plot runs from this value to zero. If the XLO subcommand had notbeen used, normal rounding with automatic scaling would have caused the scales torun from -100 to zero, wasting 40% of the plotting area.

In Figure A4-7, the log file continues with a second run. This run is set up with adebug printout generated with ACTION at the derivative evaluation where T is equalto or greater than 0.1 so that we can see all the values in the model at the moment ofthe ejection. The OUTPUT rate is reduced to every ten communication intervals or 0.1sec. Changing the rate with /NCIOUT does not affect the list of variables to be output.Not only is it not necessary to restate the OUTPUT list at this point, but doing sowould result in the variables being printed out twice each because the OUTPUT list iscumulative. The aircraft speed is changed to 500 ft/sec and the model run again.

Figure A4-5. Pilot ejection time plot Figure A4-6. Pilot ejection trajectoryVA = 900 ft/s



ACSL Runtime Exec Version 6 Level 10B 15-FEB-91 13:57:55 Page 2Pilot Ejection

! Set up for debug list of all variables when t = 0.1ACTION/VARIABLE=0.1/VALUE=1/LOCATION=NDBUGOUTPUT/NCIOUT=10 ! Same output list,lower rate

! List of commands on one lineSET va=500.0 ; START ; PLOT/XAXIS=x/XLO=xmn y

T 0. TH 0.07874500 V 491.170000X 0. Y 0. D 2867.11000

T 0.10000000 TH 0.07874500 V 491.170000X-1.03520000 Y 3.86372000 D 2867.11000

....Debug dump - System Variables. NDBUG is 1, block number 1T 0.10100000 ZZTICG 0. CINT 0.01000000

ZZIERR F ZZNBLK 1 ZZICON 1ZZSTFL F ZZFRFL T ZZICFL FZZRNFL F ZZJEFL F ZZNIST 4ZZNAST 0 IALG 5 NSTP 10

MAXT 1.0000E+09 MINT 1.0000E-09

State Variables Derivatives Initial ConditionsTH 0.07874500 Z09993 0. THIC 0.07874500

V 491.170000 Z09994 0. VIC 491.170000X-1.04555000 Z09998-10.3520000 Z09997 0.Y 3.90236000 Z09996 38.6372000 Z09995 0.

Algebraic Variables

Common Block /ZZCOMU/CD 1.00000000 D 2867.11000 DEGRAD 57.3000000

G 32.2000000 MASS 7.00000000 RAIL 0.RO 0.00237690 S 10.0000000 THE 0.26178000

THEDEG 15.0000000 TMX 4.00000000 VA 500.000000VE 40.0000000 VX 489.648000 VY 38.6372000

XMN-60.0000000 Y1 4.00000000 YMX 30.0000000ZZSEED 55555555

T 0.20000000 TH 0.07220480 V 454.489000X-3.86296000 Y 7.44086000 D 2454.87000

T 0.30000000 TH 0.06486210 V 421.727000X-10.1960000 Y 10.4422000 D 2113.70000

T 0.40000000 TH 0.05696620 V 393.366000X-19.5502000 Y 12.9250000 D 1838.97000

T 0.50000000 TH 0.04851700 V 368.580000X-31.5330000 Y 14.9354000 D 1614.52000

T 0.60000000 TH 0.03951440 V 346.740000X-45.8242000 Y 16.5115000 D 1428.86000

Distance LimitT 0.69000000 TH 0.03093920 V 329.197000X-60.4399000 Y 17.5845000 D 1287.93000

Drawing plot number 3SPAREAccumulated cp time 35.30000. Elapsed cp time 6.840000QUIT

Figure A4-7. Pilot ejection log file (part 2)

DEBUGdump



The ACTION command generates a debug output. The complete command is read asfollows: When the independent variable (/VARIABLE) becomes 0.1, take a value(/VALUE) of 1 and store it into a location (/LOCATION) called NDBUG. Theprintout following the START command begins with the OUTPUT listing at timeequal to 0.0 and 0.1 (note the reduced frequency) and then comes the DEBUG dump.Note that NDBUG is 1 as specified by the ACTION command. Although werequested the dump to be produced at 0.1 sec, the time is actually 0.101 sec. Thisindicates that T was not 0.1 at the previous integration step, or else the dump wouldhave been produced then. Instead, because of the way digital computers add decimalnumbers, time was 0.0999999999999 (depending on the computer system and whethermodel is run in single or double precision) at the previous step.

The debug dump comprises three sections: first, system variables (described in moredetail in Chapter 7); next, state variables with their associated derivatives and initialconditions; and, finally, the algebraic variables by common block. /ZZCOMU/ is theuser single precision and integer common block. If any double precision variables areused in the model, a double precision common block called /ZZCOMP/ appears. If anycharacter variables are used, there is a common block called /ZZCOMC/.

Since the ACTION command specified the system variable NDBUG to be 1, only onedebug list is written out and the run continues normally from that point with outputevery 0.1 seconds. The trajectory plot of the second run, Figure A4-8, shows the pilotnow clearing the tail by 5 ft. at the lower velocity. Note that the level of detail in theplot is not affected the lower rate of OUTPUT. Variables on the PREPARE list arestill logged (and plotted) at the communication interval (CINT); this program uses thedefault of 0.01 sec. as can be seen in the debug listing.

This example illustrates how you can vary a parameter at runtime and compare theresults. You could continue the study by choosing one value for the velocity andvarying the air density to see its effect on the pilot clearing aircraft.

Figure A4-8. Pilot ejection trajectory, VA = 500 ft/s



5. TemperatureDistribution alonga Radiating Fin

The radiating fin example illustrates the use of a loop from the TERMINAL sectionback to the INITIAL section for generating a series of runs. The independent variableis the distance along the fin (rather than time) and it is given the name X rather thantaking the default name of T.

The only practical way of rejecting heat from a power plant operating in outer space isby thermal radiation. If the working fluid of the power plant passes through tubes, anefficient radiating surface could be created by placing many tubes side by side. Thisdesign would maintain the entire surface at the highest possible temperature. Such asystem, though, is highly vulnerable to being punctured by a meteor fragment or someother particle, and this could lead to the loss of the vital working fluid.

A less efficient but also less vulnerable arrangement is shown in Figure A5-1. Thenumber of tubes has been reduced and the space between the tubes has been filled by afin of rectangular cross section. The temperature profile across the fin is to bedetermined for various tube spacings, fin thicknesses, fin material, etc. Thetemperature profile, in turn, can be used to calculate the efficiency of the radiatingsystem.

This example is a problem in static temperature distribution. Time is not a factorbecause steady state conditions throughout the system are assumed.

5.1 Assumptions

Figure A5-2 shows two views of the geometry of the fin. In terms of this figure, thepertinent assumptions are as follows:

1. Steady-state conditions have been established.2. Heat is transferred out of the fin only by radiation through a nonabsorbing me-

dium.3. Thermal properties of the material are constant.4. There is no heat conduction in the Y direction.

Figure A5-1. A Radiating Surface Using Tubes and Fins

A. ACSL Example Programs A5. Temperature Distribution along a Radiating Fin


5. Heat loss from the two exposed side edges is small enough to consider theedges as being insulated.

6. Temperature is effectively constant across the fin thickness (2H) at all valuesof X, which implies 2H << W, 2H << L.

These assumptions reduce the problem to mathematical formulation forone-dimensional steady-state heat transfer under combined radiation and conduction.

5.2 MathematicalFormulation

Consider the heat balance for an element strip shown in Figure A5-3 where the widthis W, half thickness isH, and length is∆x. The local rate of heat conduction throughthe cross-sectional area 2HWat positionx is given by Fourier's equation to be

qx + ∆x = − K (2HW) dTdx | x + ∆x

whereK is the thermal conductivity of the material. The rate of heat conduction out ofthe segment is:

qx = − K (2HW) dTdx | x

The rate of heat lost by radiation is the difference, namely:

∆q = − K (2HW)

dTdx

|x − dTdx

|x + ∆x

Figure A5-2. Geometry of the Radiating Fin

A5. Temperature Distribution along a Radiating Fin A. ACSL Example Programs


This condition can also be expressed by means of the Stephan-Boltzman law for heatradiation, taking into account both the top and bottom surfaces of the element:

∆q = σ ε ( T 4 − Ts4 ) ( 2W∆x )

where:

σ = Stephan-Boltzman constant for the materialε = emissivity of the materialT = temperature of the segment, inoRTs = temperature of the surroundings, inoR

The heat balance equation then becomes:

− K ( 2HW )

dTdx |x

− dTdx |x + ∆x

= σ ε ( T 4 − Ts4 ) ( 2W∆x )

Dividing both sides by− K (2HW) ∆x and inverting the order on the left side gives:

1∆x

dTdx | x + ∆x

− dTdx | x

=σ εKH

( T 4 − Ts4 )

In the limit, as∆x→0, the left side becomes the second derivative ofT with respect tox, so the final equation becomes:

d 2T

dx2 =σ εKH

( T 4 − Ts4 )

Figure A5-3. Heat Balance for an Element of Radiating Fin



5.3 Initial Conditionsand Parameters

Since the equation derived above is a second order differential equation, appropriateinitial conditions must be specified for the temperature and the temperature gradient atx = 0. While the initial temperature (the temperature where the fin joins the tube) isknown, the initial temperature gradient is not known. However, it is clear from thesymmetry of the arrangement that the temperature gradient at the midpoint betweentubes wherex = L is zero. Thus, the problem falls in the category of a two-pointboundary value problem that must satisfy these conditions:

T(0) = 2000oR

dTdx | x = L

= 0

The variables and constants and their appropriate units are as follows:

T = temperature oRx = distance ftσ = 0.173x10-8 BTU/(hr)(ft2)(oR4)ε = 0.9 -K = 25 BTU/(hr)(ft2)(oR)H = 0.00125 ftL = 0.25 ftTs = 0 oR

Note that the temperature of the surroundings (Ts) has been taken to be absolute zerofor this example.

5.4 Solution

A solution is considered to be successful if:

[ dT ⁄ dx ] < 0.2 whenx = L

The current run is terminated and a new run started by looping back from theTERMINAL section to the INITIAL section if:

1. T exceeds its initial value by one percent or more2. T becomes negative3. [dT ⁄ dx ] > 0.2 whenx = L

A new estimate of in the initial temperature gradient (DTDXZ) is computed using theold value as follows:

DTDXZ(new) = DTDXZ(old) - 0.07*DTDX(x = L)

where DTDX(x = L) is the final value of the temperature gradient. One case is run forthis example with an initial temperature of 2000oR and an estimated temperaturegradient of -20,000oR/ft.

The listing of the model source code is shown in Figure A5-4. The program has a loopfrom the TERMINAL to the INITIAL section. In the TERMINAL section, it checksthe final value of temperature slope; if the slope is not within the specified tolerance,the program recycles to the INITIAL section (to the label L1) for another run with a



new value of initial slope. The independent variable is specified in the VARIABLEstatement to be X, and the initial condition (XZ) is set to 1.0E-10 to give it a lead onthe roundoff error.

Figure A5-5 is a listing of the log file.

PROGRAM radiating fin

!-----------------------communication intervalCINTERVAL cint = 0.0025!-----------------------off-set initial value to handle accumu-! lated round off - change name from t to xVARIABLE x = 1.0e-10

INITIAL

!-----------------------initial temp rate guessCONSTANT dtdxz = -20000.0!-----------------------note n is handled as an integerINTEGER nn = 0

l1..CONTINUEn = n + 1 ! bump run countCALL INITD ! clear event list

END ! of initial!-----------------------note no dynamic section since not used

DERIVATIVE

!-----------------------integrate for temp rate and temperatureCONSTANT sg = 1.73e-9 , ep = 0.9CONSTANT h = 0.00125 , k = 25.0CONSTANT ts = 0.0dtdx = INTEG(sg*ep*(t**4 - ts**4)/(k*h), dtdxz)!-----------------------note t is now temperature not timet = INTEG(dtdx, tz)!-----------------------specify termination conditionCONSTANT l = 0.25 , tz = 2000.0TERMT(x.GE.l .OR. t.GE.1.01*tz .OR. t.LT.0.0)

END ! of derivative

TERMINAL

!-----------------------force output at end of every sweepCALL LOGD(.TRUE.)!-----------------------if converged or too many triesCONSTANT error = 0.2IF((ABS(dtdx).GE.error) .AND. n.LE.10) THEN

!----------------------find new guess for initial temp rateCONSTANT gain = 0.07dtdxz = dtdxz - gain*dtdx!----------------------try run againGO TO l1

ENDIF

END ! of terminal

END ! of program

Figure A5-4. Radiating fin program




SET TITLE = 'Radiating Fin Example'SPAREAccumulated cp time 118.5200. Elapsed cp time 0.SET TCWPRN=72,PCWPRN=80 ! Force 3 column output widthOUTPUT/NCIOUT=20 x,t,n,dtdx,dtdxzPREPARE x,dtdx,t,n,dtdxzSTART ! Perform iteration

X 1.0000E-10 T 2000.00000 N 1DTDX-20000.0000 DTDXZ-20000.0000

X 0.05000000 T 1655.09000 N 1DTDX 3125.64000 DTDXZ-20000.0000

X 0.08400000 T 2022.13000 N 1DTDX 20882.3000 DTDXZ-20000.0000

X 1.0000E-10 T 2000.00000 N 2DTDX-21461.8000 DTDXZ-21461.8000

X 0.05000000 T 1548.18000 N 2DTDX-347.340000 DTDXZ-21461.8000

X 0.10000000 T 1950.17000 N 2DTDX 19621.8000 DTDXZ-21461.8000

X 0.10350000 T 2023.48000 N 2DTDX 22336.7000 DTDXZ-21461.8000

X 1.0000E-10 T 2000.00000 N 3DTDX-23025.3000 DTDXZ-23025.3000

X 0.05000000 T 1436.77000 N 3DTDX-3799.77000 DTDXZ-23025.3000

X 0.10000000 T 1496.70000 N 3DTDX 6488.72000 DTDXZ-23025.3000

X 0.13925000 T 2023.07000 N 3DTDX 23828.8000 DTDXZ-23025.3000

X 1.0000E-10 T 2000.00000 N 4DTDX-24693.3000 DTDXZ-24693.3000

X 0.05000000 T 1320.94000 N 4DTDX-7222.55000 DTDXZ-24693.3000

X 0.10000000 T 1102.75000 N 4DTDX-2124.58000 DTDXZ-24693.3000

X 0.15000000 T 1081.88000 N 4DTDX 1246.12000 DTDXZ-24693.3000

X 0.20000000 T 1241.96000 N 4DTDX 5559.13000 DTDXZ-24693.3000

Figure A5-5. Radiating fin log file (part 1)



ACSL Runtime Exec Version 6 Level 10B 18-FEB-91 10:17:21 Page 2Radiating Fin Example

X 0.25000000 T 1744.38000 N 4DTDX 17143.4000 DTDXZ-24693.3000

X 0.25025000 T 1748.68000 N 4DTDX 17259.3000 DTDXZ-24693.3000

X 1.0000E-10 T 2000.00000 N 5DTDX-25901.5000 DTDXZ-25901.5000

X 0.05000000 T 1238.82000 N 5DTDX-9554.59000 DTDXZ-25901.5000

X 0.10000000 T 855.500000 N 5DTDX-6501.77000 DTDXZ-25901.5000

X 0.15000000 T 551.324000 N 5DTDX-5844.27000 DTDXZ-25901.5000

X 0.20000000 T 262.112000 N 5DTDX-5758.90000 DTDXZ-25901.5000

X 0.24575000 T-1.27562000 N 5DTDX-5756.76000 DTDXZ-25901.5000

X 1.0000E-10 T 2000.00000 N 6DTDX-25498.5000 DTDXZ-25498.5000

X 0.05000000 T 1266.05000 N 6DTDX-8789.50000 DTDXZ-25498.5000

X 0.10000000 T 935.122000 N 6DTDX-5165.11000 DTDXZ-25498.5000

X 0.15000000 T 711.010000 N 6DTDX-4006.11000 DTDXZ-25498.5000

X 0.20000000 T 521.885000 N 6DTDX-3633.05000 DTDXZ-25498.5000

X 0.25000000 T 343.205000 N 6DTDX-3538.70000 DTDXZ-25498.5000

X 0.25025000 T 342.320000 N 6DTDX-3538.53000 DTDXZ-25498.5000

X 1.0000E-10 T 2000.00000 N 7DTDX-25250.8000 DTDXZ-25250.8000

X 0.05000000 T 1282.87000 N 7DTDX-8312.99000 DTDXZ-25250.8000

X 0.10000000 T 985.412000 N 7DTDX-4286.58000 DTDXZ-25250.8000

X 0.15000000 T 816.696000 N 7





DTDX-2664.22000 DTDXZ-25250.8000

X 0.20000000 T 706.275000 N 7DTDX-1832.88000 DTDXZ-25250.8000

X 0.25000000 T 627.859000 N 7DTDX-1342.21000 DTDXZ-25250.8000

X 0.25025000 T 627.523000 N 7DTDX-1340.28000 DTDXZ-25250.8000

X 1.0000E-10 T 2000.00000 N 8DTDX-25157.0000 DTDXZ-25157.0000

X 0.05000000 T 1289.26000 N 8DTDX-8131.24000 DTDXZ-25157.0000

X 0.10000000 T 1004.75000 N 8DTDX-3941.41000 DTDXZ-25157.0000

X 0.15000000 T 858.474000 N 8DTDX-2102.45000 DTDXZ-25157.0000

X 0.20000000 T 782.803000 N 8DTDX-992.930000 DTDXZ-25157.0000

X 0.25000000 T 755.061000 N 8DTDX-137.438000 DTDXZ-25157.0000

X 0.25025000 T 755.027000 N 8DTDX-133.389000 DTDXZ-25157.0000

X 1.0000E-10 T 2000.00000 N 9DTDX-25147.7000 DTDXZ-25147.7000

X 0.05000000 T 1289.89000 N 9DTDX-8113.11000 DTDXZ-25147.7000

X 0.10000000 T 1006.68000 N 9DTDX-3906.67000 DTDXZ-25147.7000

X 0.15000000 T 862.689000 N 9DTDX-2044.73000 DTDXZ-25147.7000

X 0.20000000 T 790.655000 N 9DTDX-903.288000 DTDXZ-25147.7000

X 0.25000000 T 768.495000 N 9DTDX-0.34978200 DTDXZ-25147.7000

X 0.25025000 T 768.495000 N 9DTDX 3.99474000 DTDXZ-25147.7000

X 1.0000E-10 T 2000.00000 N 10DTDX-25147.9000 DTDXZ-25147.9000





X 0.05000000 T 1289.87000 N 10DTDX-8113.65000 DTDXZ-25147.9000

X 0.10000000 T 1006.62000 N 10DTDX-3907.71000 DTDXZ-25147.9000

X 0.15000000 T 862.563000 N 10DTDX-2046.46000 DTDXZ-25147.9000

X 0.20000000 T 790.419000 N 10DTDX-905.987000 DTDXZ-25147.9000

X 0.25000000 T 768.091000 N 10DTDX-4.50258000 DTDXZ-25147.9000

X 0.25025000 T 768.090000 N 10DTDX-0.16719500 DTDXZ-25147.9000

X 0.25025000 T 768.090000 N 10DTDX-0.16719500 DTDXZ-25147.9000

S FTSPLT=.T. ! Synchronize output with start of each swePRINT/NCIPRN=5 x,dtdx,t,n,dtdxz ! Demonstrate column print

Line X DTDX T N DTDXZ0 1.0000E-10 -20000.0000 2000.00000 1 -20000.00005 0.01250000 -11950.2000 1803.78000 1 -20000.0000

10 0.02500000 -6205.17000 1691.85000 1 -20000.000015 0.03750000 -1436.42000 1644.65000 1 -20000.000020 0.05000000 3125.64000 1655.09000 1 -20000.000025 0.06250000 8146.51000 1724.67000 1 -20000.000030 0.07500000 14529.5000 1864.32000 1 -20000.0000

0 1.0000E-10 -21461.8000 2000.00000 2 -21461.80005 0.01250000 -13560.0000 1784.86000 2 -21461.8000

10 0.02500000 -8190.94000 1650.67000 2 -21461.800015 0.03750000 -4016.33000 1575.19000 2 -21461.800020 0.05000000 -347.340000 1548.18000 2 -21461.800025 0.06250000 3280.23000 1566.34000 2 -21461.800030 0.07500000 7313.52000 1631.86000 2 -21461.800035 0.08750000 12375.5000 1753.40000 2 -21461.800040 0.10000000 19621.8000 1950.17000 2 -21461.8000

0 1.0000E-10 -23025.3000 2000.00000 3 -23025.30005 0.01250000 -15278.6000 1764.64000 3 -23025.3000

10 0.02500000 -10289.2000 1606.79000 3 -23025.300015 0.03750000 -6681.27000 1501.74000 3 -23025.300020 0.05000000 -3799.77000 1436.77000 3 -23025.300025 0.06250000 -1278.37000 1405.26000 3 -23025.300030 0.07500000 1129.93000 1404.34000 3 -23025.300035 0.08750000 3638.00000 1433.92000 3 -23025.300040 0.10000000 6488.72000 1496.70000 3 -23025.300045 0.11250000 10037.6000 1599.01000 3 -23025.300050 0.12500000 14913.9000 1753.09000 3 -23025.300055 0.13750000 22426.0000 1982.62000 3 -23025.3000

0 1.0000E-10 -24693.3000 2000.00000 4 -24693.3000





Line X DTDX T N DTDXZ5 0.01250000 -17108.4000 1743.07000 4 -24693.3000

10 0.02500000 -12499.3000 1560.15000 4 -24693.300015 0.03750000 -9424.86000 1424.29000 4 -24693.300020 0.05000000 -7222.55000 1320.94000 4 -24693.300025 0.06250000 -5550.13000 1241.54000 4 -24693.300030 0.07500000 -4214.40000 1180.79000 4 -24693.300035 0.08750000 -3097.99000 1135.27000 4 -24693.300040 0.10000000 -2124.58000 1102.75000 4 -24693.300045 0.11250000 -1240.93000 1081.79000 4 -24693.300050 0.12500000 -406.731000 1071.52000 4 -24693.300055 0.13750000 411.723000 1071.55000 4 -24693.300060 0.15000000 1246.12000 1081.88000 4 -24693.300065 0.16250000 2130.18000 1102.91000 4 -24693.300070 0.17500000 3104.29000 1135.51000 4 -24693.300075 0.18750000 4221.77000 1181.11000 4 -24693.300080 0.20000000 5559.13000 1241.96000 4 -24693.300085 0.21250000 7234.09000 1321.49000 4 -24693.300090 0.22500000 9440.46000 1425.01000 4 -24693.300095 0.23750000 12521.8000 1561.10000 4 -24693.3000

100 0.25000000 17143.4000 1744.38000 4 -24693.30000 1.0000E-10 -25901.5000 2000.00000 5 -25901.50005 0.01250000 -18431.5000 1727.46000 5 -25901.5000

10 0.02500000 -14082.7000 1526.48000 5 -25901.500015 0.03750000 -11352.8000 1368.75000 5 -25901.500020 0.05000000 -9554.59000 1238.82000 5 -25901.500025 0.06250000 -8333.95000 1127.50000 5 -25901.500030 0.07500000 -7491.48000 1028.91000 5 -25901.500035 0.08750000 -6906.54000 939.145000 5 -25901.500040 0.10000000 -6501.77000 855.500000 5 -25901.500045 0.11250000 -6225.01000 776.069000 5 -25901.500050 0.12500000 -6039.69000 699.495000 5 -25901.500055 0.13750000 -5919.29000 624.808000 5 -25901.500060 0.15000000 -5844.27000 551.324000 5 -25901.500065 0.16250000 -5800.05000 478.573000 5 -25901.500070 0.17500000 -5775.88000 406.240000 5 -25901.500075 0.18750000 -5763.97000 334.125000 5 -25901.500080 0.20000000 -5758.90000 262.112000 5 -25901.500085 0.21250000 -5757.19000 190.139000 5 -25901.500090 0.22500000 -5756.80000 118.177000 5 -25901.500095 0.23750000 -5756.76000 46.2177000 5 -25901.5000

0 1.0000E-10 -25498.5000 2000.00000 6 -25498.50005 0.01250000 -17990.4000 1732.67000 6 -25498.5000

10 0.02500000 -13556.1000 1537.70000 6 -25498.500015 0.03750000 -10715.0000 1387.23000 6 -25498.500020 0.05000000 -8789.50000 1266.05000 6 -25498.500025 0.06250000 -7431.22000 1165.14000 6 -25498.500030 0.07500000 -6445.11000 1078.73000 6 -25498.500035 0.08750000 -5714.34000 1002.96000 6 -25498.500040 0.10000000 -5165.11000 935.122000 6 -25498.500045 0.11250000 -4748.63000 873.280000 6 -25498.500050 0.12500000 -4431.42000 815.994000 6 -25498.500055 0.13750000 -4189.71000 762.181000 6 -25498.500060 0.15000000 -4006.11000 711.010000 6 -25498.5000





Line X DTDX T N DTDXZ65 0.16250000 -3867.60000 661.841000 6 -25498.500070 0.17500000 -3764.19000 614.174000 6 -25498.500075 0.18750000 -3688.07000 567.622000 6 -25498.500080 0.20000000 -3633.05000 521.885000 6 -25498.500085 0.21250000 -3594.20000 476.729000 6 -25498.500090 0.22500000 -3567.53000 431.979000 6 -25498.500095 0.23750000 -3549.88000 387.503000 6 -25498.5000

100 0.25000000 -3538.70000 343.205000 6 -25498.50000 1.0000E-10 -25250.8000 2000.00000 7 -25250.80005 0.01250000 -17719.2000 1735.87000 7 -25250.8000

10 0.02500000 -13231.7000 1544.61000 7 -25250.800015 0.03750000 -10320.4000 1398.61000 7 -25250.800020 0.05000000 -8312.99000 1282.87000 7 -25250.800025 0.06250000 -6863.85000 1188.48000 7 -25250.800030 0.07500000 -5779.61000 1109.76000 7 -25250.800035 0.08750000 -4944.75000 1042.95000 7 -25250.800040 0.10000000 -4286.58000 985.412000 7 -25250.800045 0.11250000 -3757.37000 935.253000 7 -25250.800050 0.12500000 -3324.66000 891.077000 7 -25250.800055 0.13750000 -2965.72000 851.830000 7 -25250.800060 0.15000000 -2664.22000 816.696000 7 -25250.800065 0.16250000 -2408.15000 785.035000 7 -25250.800070 0.17500000 -2188.54000 756.340000 7 -25250.800075 0.18750000 -1998.55000 730.199000 7 -25250.800080 0.20000000 -1832.88000 706.275000 7 -25250.800085 0.21250000 -1687.39000 684.293000 7 -25250.800090 0.22500000 -1558.79000 664.020000 7 -25250.800095 0.23750000 -1444.44000 645.264000 7 -25250.8000

100 0.25000000 -1342.21000 627.859000 7 -25250.80000 1.0000E-10 -25157.0000 2000.00000 8 -25157.00005 0.01250000 -17616.4000 1737.08000 8 -25157.0000

10 0.02500000 -13108.7000 1547.22000 8 -25157.000015 0.03750000 -10170.4000 1402.92000 8 -25157.000020 0.05000000 -8131.24000 1289.26000 8 -25157.000025 0.06250000 -6646.37000 1197.35000 8 -25157.000030 0.07500000 -5522.88000 1121.60000 8 -25157.000035 0.08750000 -4645.43000 1058.26000 8 -25157.000040 0.10000000 -3941.41000 1004.75000 8 -25157.000045 0.11250000 -3363.11000 959.204000 8 -25157.000050 0.12500000 -2878.02000 920.280000 8 -25157.000055 0.13750000 -2463.30000 886.961000 8 -25157.000060 0.15000000 -2102.45000 858.474000 8 -25157.000065 0.16250000 -1783.26000 834.226000 8 -25157.000070 0.17500000 -1496.49000 813.758000 8 -25157.000075 0.18750000 -1234.94000 796.709000 8 -25157.000080 0.20000000 -992.930000 782.803000 8 -25157.000085 0.21250000 -765.814000 771.824000 8 -25157.000090 0.22500000 -549.706000 763.612000 8 -25157.000095 0.23750000 -341.249000 758.050000 8 -25157.0000

100 0.25000000 -137.438000 755.061000 8 -25157.00000 1.0000E-10 -25147.7000 2000.00000 9 -25147.70005 0.01250000 -17606.2000 1737.20000 9 -25147.7000

10 0.02500000 -13096.4000 1547.48000 9 -25147.7000





Line X DTDX T N DTDXZ15 0.03750000 -10155.5000 1403.35000 9 -25147.700020 0.05000000 -8113.11000 1289.89000 9 -25147.700025 0.06250000 -6624.65000 1198.24000 9 -25147.700030 0.07500000 -5497.18000 1122.78000 9 -25147.700035 0.08750000 -4615.39000 1059.79000 9 -25147.700040 0.10000000 -3906.67000 1006.68000 9 -25147.700045 0.11250000 -3323.27000 961.603000 9 -25147.700050 0.12500000 -2832.68000 923.211000 9 -25147.700055 0.13750000 -2412.01000 890.495000 9 -25147.700060 0.15000000 -2044.73000 862.689000 9 -25147.700065 0.16250000 -1718.57000 839.206000 9 -25147.700070 0.17500000 -1424.21000 819.592000 9 -25147.700075 0.18750000 -1154.38000 803.499000 9 -25147.700080 0.20000000 -903.288000 790.655000 9 -25147.700085 0.21250000 -666.157000 780.858000 9 -25147.700090 0.22500000 -438.943000 773.960000 9 -25147.700095 0.23750000 -218.091000 769.858000 9 -25147.7000

100 0.25000000 -0.34978200 768.495000 9 -25147.70000 1.0000E-10 -25147.9000 2000.00000 10 -25147.90005 0.01250000 -17606.5000 1737.20000 10 -25147.9000

10 0.02500000 -13096.8000 1547.47000 10 -25147.900015 0.03750000 -10155.9000 1403.34000 10 -25147.900020 0.05000000 -8113.65000 1289.87000 10 -25147.900025 0.06250000 -6625.30000 1198.21000 10 -25147.900030 0.07500000 -5497.95000 1122.75000 10 -25147.900035 0.08750000 -4616.29000 1059.74000 10 -25147.900040 0.10000000 -3907.71000 1006.62000 10 -25147.900045 0.11250000 -3324.47000 961.531000 10 -25147.900050 0.12500000 -2834.04000 923.123000 10 -25147.900055 0.13750000 -2413.55000 890.389000 10 -25147.900060 0.15000000 -2046.46000 862.563000 10 -25147.900065 0.16250000 -1720.51000 839.057000 10 -25147.900070 0.17500000 -1426.38000 819.418000 10 -25147.900075 0.18750000 -1156.80000 803.295000 10 -25147.900080 0.20000000 -905.987000 790.419000 10 -25147.900085 0.21250000 -669.161000 780.587000 10 -25147.900090 0.22500000 -442.287000 773.649000 10 -25147.900095 0.23750000 -221.815000 769.503000 10 -25147.9000

100 0.25000000 -4.50258000 768.091000 10 -25147.9000START ! Repeat last case of previous run

X 1.0000E-10 T 2000.00000 N 1DTDX-25147.9000 DTDXZ-25147.9000

X 0.05000000 T 1289.87000 N 1DTDX-8113.65000 DTDXZ-25147.9000

X 0.10000000 T 1006.62000 N 1DTDX-3907.71000 DTDXZ-25147.9000

X 0.15000000 T 862.563000 N 1DTDX-2046.46000 DTDXZ-25147.9000

X 0.20000000 T 790.419000 N 1




The initial value for temperature rate (DTDXZ) is a guess. It is given in aCONSTANT statement so that different guesses can be tried at runtime. BecauseDTDXZ is calculated later in the program (i.e., in the TERMINAL section), thetranslator issues a warning:

dtdxz = dtdxz - gain*dtdx;...Multiply defined symbol.... DTDXZ

This warning is issued any time a variable defined in a CONSTANT statement is alsodefined in an assignment statement. In most situations, the results of such a procedurewill be in incorrect, or at least have the potential for being incorrect, but this is anexample of a case where it is the best solution. Giving the initial guess in anassignment statement would not allow experimenting at runtime.

The warning message can be avoided by specifyingNO WARNINGSwhen calling theACSL translator. This switch is handled differently for different computer systems.See the documentACSL Sim User's Guide.

Subroutine LOGD is called in the TERMINAL section to force data logging at the endof each loop and each run. This call also forces an OUTPUT operation, and with theargument set to TRUE it resets the counter for /NCIOUT (number of communicationintervals per OUTPUT) so that the last value of the run is always listed.

This program has no DYNAMIC section. It is not necessary to include a DYNAMICsection in a program when there is no code to be put in it. The communication intervalis still in effect and the data is still logged as though there were a DYNAMIC sectionsince ACSL automatically provides one to handle these operations.

The event list is cleared by calling utility subroutine INITD after looping back to theINITIAL section. This subroutine is described in Appendix B. Its purpose is to removeany events (such as the next communication interval) left over at the end of theprevious loop. In this program, the only event left on the list is the nextcommunication interval, which actually would not affect subsequent loops, but


DTDX-905.987000 DTDXZ-25147.9000

X 0.25000000 T 768.091000 N 1DTDX-4.50258000 DTDXZ-25147.9000

X 0.25025000 T 768.090000 N 1DTDX-0.16719500 DTDXZ-25147.9000

X 0.25025000 T 768.090000 N 1DTDX-0.16719500 DTDXZ-25147.9000

PLOT/XHI=l,dtdx,t ! Plot converged profile. Use default xaxisDrawing plot number 1SPARE ! List execution timeAccumulated cp time 146.3200. Elapsed cp time 27.80000QUIT




programs with DISCRETE sections and SCHEDULE statements would need the callto INITD in order to work correctly.

The log file shows the runtime session beginning with a title definition. A SPAREcommand gives the accumulated and elapsed cp time. Narrow printout on both theinteractive terminal and the log file is set with TCWPRN and PCWPRN. OUTPUTand PREPARE lists are established, and the run is executed with START.

During the run, OUTPUT appears, showing that the first three iterations find that theintermediate temperature is more than one percent greater than the starting value,triggering the terminate (TERMT) condition. For the fourth and subsequent iterations,the final value of X is 0.25, and now the final value of dT/dx is slowly reduced until atiteration number ten the value is -0.153, well within the ERROR tolerance of 0.2.

Values for variables on the PREPARE list are logged on an intermediate file (raw runrecord, or RRR) for printing and plotting after the run. On page 4 of the log file,system symbol FTSPLT (flyback trace suppression) is set TRUE and and a PRINTcommand issued. FTSPLT resynchronizes the line count to zero when the independentvariable (first variable on the PREPAR list) becomes more negative than its previousvalue. PRINT produces the same information as OUTPUT, but in a more readableform.

Once the iteration has converged, a second START (on page 7 of the log file) rerunsthe last case, since the initial condition on temperature slope (DTDXZ) is still thevalue from the converged iteration of the previous run. Rerunning the last caseoverwrites the data in the intermediate file so that only one run is plotted, as shown inFigure A5-6. The temperature gradient (DTDX) and temperature (T) are plottedagainst distance (X) along the fin. It is often easier and more cost effective merely torepeat the last run of an iteration rather than make complicated arrangements to saveeach run separately before it is known that the convergence criteria have beensatisfied. Plotting after the first START command would have shown the parametricset of curves as the iteration proceeded, since the RRR file is not rewound betweenruns on cycling from TERMINAL to INITIAL sections. In this case, the cluster ofcurves causes rather an cluttered plot and does not provide much information; only thefinal profile is needed.

Figure A5-6. Radiating fin temperature profile and gradient



6. AircraftArresting Gear

The aircraft arresting gear example includes a function generator and input relays. Itillustrates line and strip plot capabilities. It also shows the use of standard FORTRANoutput statements within ACSL.

Figure A6-1 shows the geometry of the aircraft arresting gear system, which isdesigned to halt a moving aircraft that would otherwise overrun the end of a runway.

Figure A6-1. Aircraft arresting gear system

A. ACSL Example Programs A6. Aircraft Arresting Gear


It is similar in principle to the gear used on aircraft carriers. A plot of the "watersqueezer" damping function,f(y3), is also shown on the figure. The aims of thesimulation are to determine the range of aircraft weights and speeds that can beaccommodated without exceeding the working limits of the cables or the allowablepiston travel. Two cases involving different aircraft velocities are investigated.

The differential equations describing the acceleration of the three masses are:

m3d 2y3

dt 2= f K2 − f D

m2d 2y2

dt 2= w f K1 − f K2

m1d 2x

dt 2= − 2 f K1 sin θ

where the cable tension is given by:

f K1 =

k1 (y1 − 2y2)0

y1 > 2y2

y1 ≤ 2y2

f K2 =

k2 (y2 − y3 )0

y2 > y3

y2 ≤ y3

Drag force from the water squeezer is given by:

f D = F( y3)

dy3

dt

2

Geometrical constraints lead to:

y1 = √x2 + h2 − h

sin θ =x

h + y1=

x

√x2 + h2

Constants used in the example are as follows:

m1 = 1400 slugsm2 = 45.28 slugsm3 = 20 slugsk1 = 4550 lb/ftk2 = 25,300 lb/fth = 125 ft

Initial conditions are given by:

y.3(0) = 0 y3(0) = 0

y.2(0) = 0 y2(0) = 0

x.(0) = 200 ft/s (Run 1) x(0) = 0

= 290 ft/s (Run 2)

A6. Aircraft Arresting Gear A. ACSL Example Programs


A function of one variable is used for the squeezer drag coefficient. The data points forthe function are shown in the plot off(y3) in Figure A6-1 and in TABLE FY3 in thelisting of the model in Figure A6-2. Interpolation between points is linear. For thisfunction, sixteen breakpoints (15 segments) have been used. The degree of fit to agiven function can be adjusted by using more (or fewer) breakpoints as necessary.

This example is programmed in the explicit mode with INITIAL, DYNAMIC, andDERIVATIVE sections being defined. Using explicit structure allows us to show theuse of standard FORTRAN output to write out information. In this program, the initialspeed and case number are printed out at the beginning of each run;i.e., in theINITIAL section. Logical unit 9 in the WRITE statement refers to the PRN highvolume print unit (the log file). The DERIVATIVE section contains the descriptiveequations modeling the system.

Cables transmit only tensile forces, and account must be taken of the fact that whenthe cable extension is negative, the force is zero. Expressing the force as proportionalto the simple extensionk2(y2 − y3) is more representative of a spring. In the originalformulation of this problem, the function real switch operator RSW was used;i.e.,

fk2 = RSW(y2 .GE. y3, k2*(y2 - y3), 0.0)

RSW operates so that when the first argument is true, the second argument is returned;if the first argument is false, then the third argument is returned. A more elegant wayof accomplishing the same thing is to use the FORTRAN function DIM that returnsthe positive difference between the two arguments; if the difference is negative(argument 1 minus argument 2), the result is zero. The force equation then becomes:

fk2= k2*DIM(y2, y3)

Note the choice of termination conditions. The TERMT statement stops the problemafter 10 seconds, or when X reaches 1000 ft.

The runtime log file is shown in Figure A6-3. The TITLE is set, the OUTPUT andPREPARE lists are specified, SPEED is set, and the run is started.

The integration step size is set to take into account the small time constant associatedwith the third mass (m3) and the nonlinearity of the function that makes the programparticularly susceptible to step size. The system becomes unstable if the step size isincreased to 4 msec. Using the default fixed step algorithm (IALG = 5), NSTP is set to1 and the maximum step size (MAXT = 0.001) controls the integration step. Theadvantage of this method is that MAXT and CINT can be controlled independently,CINT need not be an even multiple of MAXT, and MAXT alone (rather than CINTand NSTP together) controls the step size. CINTERVAL (with the variable named DLin this program) controls the step size only if it is smaller than MAXT, since it is thesmaller of these two values which becomes the integration step size.

The second run illustrates two types of plots, CALPLT (line) and STRPLT (strip).When system variable CALPLT is TRUE, the curves are all drawn in the same areaand the Y axes are side by side, as in Figure A6-5. A strip plot (STRPLT=.TRUE.) isshown in Figure A6-6. Each curve occupies a separate slot, nominally two inches byfive inches, stacked from the bottom up in the order given. /XTAG adds a unitspecification to indpendent variable T on the X axis for both plots.

These plot show that the peak deceleration increases from about 100 ft/s2 (3 g's) to 150ft/s2 (5 g's). A factor of even more interest is the force in the cable, since the cable willsnap if too much force is applied. As a follow-on exercise, plot FK2 for the two runs.



PROGRAM aircraft arresting gear

ncase = 0 ! done once at very beginning

INITIALINTEGER ncasencase = ncase + 1 ! bump case numberLINES(5) ! tell system about to print five linesWRITE(9, 200) speed, ncase

200..FORMAT(//20x,'Aircraft speed - ',f6.2,' Run no. ',i3//)END ! of initialDYNAMIC

CINTERVAL dl = 0.10 ! communication intervalMAXTERVAL maxt = 0.001 ! integration step sizeNSTEPS nstp = 1 ! decouple maxt from cinterval

DERIVATIVE!-----------------------compute second derivativesy3dd =(fk2 - fd)/m3 ; CONSTANT m3 = 20.0y2dd =(2.0*fk1 - fk2)/m2 ; CONSTANT m2 = 45.28xdd =-2.0*fk1*sth/m1 ; CONSTANT m1 = 140.0!-----------------------integrate for first derivativesy3d = INTEG(y3dd, 0.0)y2d = INTEG(y2dd, 0.0)xd = INTEG(xdd , speed) ; CONSTANT speed = 250.0!-----------------------integrate for positionsy3 = INTEG(y3d, 0.0)y2 = INTEG(y2d, 0.0)x = INTEG(xd , 0.0)!-----------------------cable tension becomes zero when slack! can never go negative - so use positive! difference functionfk1 = k1*DIM(y1, 2.0*y2) ; CONSTANT k1 = 4550.0fk2 = k2*DIM(y2, y3) ; CONSTANT k2 = 25300.0!-----------------------water squeezer drag.table fy3, 1 , 16 &

/ -10.0 , 0.0 , 30.0 , 60.0 , 120.0 &, 150.0 , 180.0 , 210.0 , 240.0 , 270.0 &, 282.0 , 294.0 , 306.0 , 312.0 , 324.0 &, 350.0 &, 8.33 , 8.33 , 4.0 , 1.6 , 5.2 &, 5.2 , 6.6 , 8.3 , 10.7 , 16.0 &, 21.0 , 28.0 , 41.0 , 50.0 , 90.0 &, 90.0 /

fd = fy3(y3)*y3d**2!-----------------------geometrical relationsCONSTANT h = 125.0y1 = SQRT(x**2 + h**2) - hsth = x/(h + y1)

END ! of derivative!-----------------------specify termination conditionTERMT(t.GE.tstp, 'Time Limit') ; CONSTANT tstp = 9.999TERMT(x.GE.xmx, 'Position Limit') ; CONSTANT xmx = 1000.0


Figure A6-2. Aircraft arresting gear program




SET TITLE = 'Aircraft Arresting Gear Example'SPAREAccumulated cp time 406.1000. Elapsed cp time 0.SET TCWPRN=72 ! force 3 column output widthOUTPUT/NCIOUT=20 t, y3dd, y3d, y3, fd, y2dd, y2d, y2, fk2 &

, xdd, xd, x, fk1, y1PREPARE t, x, xd, xddSET speed=200.0 ; START ; PLOT x, xd, xdd

Aircraft speed - 200.00 Run no. 1

T 0. Y3DD 0. Y3D 0.Y3 0. FD 0. Y2DD 0.

Y2D 0. Y2 0. FK2 0.XDD 0. XD 200.000000 X 0.FK1 0. Y1 0.

T 2.00000000 Y3DD-18.0099000 Y3D 45.9393000Y3 96.2946000 FD 7972.47000 Y2DD-18.8128000

Y2D 45.8335000 Y2 96.5955000 FK2 7612.27000XDD-44.4254000 XD 99.1682000 X 293.417000FK1 3380.22000 Y1 193.934000

T 4.00000000 Y3DD-6.57992000 Y3D 20.9752000Y3 158.437000 FD 2461.01000 Y2DD-6.69082000

Y2D 20.9324000 Y2 158.529000 FK2 2329.41000XDD-13.8845000 XD 43.5150000 X 424.248000FK1 1013.22000 Y1 317.280000

T 6.00000000 Y3DD-2.88461000 Y3D 12.1193000Y3 190.313000 FD 1055.24000 Y2DD-2.88286000

Y2D 12.1044000 Y2 190.353000 FK2 997.546000XDD-6.00084000 XD 24.9457000 X 490.112000FK1 433.505000 Y1 380.801000

T 8.00000000 Y3DD-1.46565000 Y3D 7.98094000Y3 209.945000 FD 528.472000 Y2DD-1.44382000

Y2D 7.97485000 Y2 209.964000 FK2 499.159000XDD-3.01584000 XD 16.3712000 X 530.447000FK1 216.891000 Y1 419.976000

Time LimitT 10.0000000 Y3DD-0.84401900 Y3D 5.73444000

Y3 223.460000 FD 308.346000 Y2DD-0.85578000Y2D 5.73184000 Y2 223.472000 FK2 291.466000XDD-1.76148000 XD 11.7405000 X 558.146000FK1 126.358000 Y1 446.972000

Drawing plot number 1

Figure A6-3. Aircraft arresting gear log file (part 1)



ACSL Runtime Exec Version 6 Level 10B 20-FEB-91 11:16:18 Page 2Aircraft Arresting Gear Example

SET speed=290.0 ; START

Aircraft speed - 290.00 Run no. 2

T 0. Y3DD 0. Y3D 0.Y3 0. FD 0. Y2DD 0.

Y2D 0. Y2 0. FK2 0.XDD 0. XD 290.000000 X 0.FK1 0. Y1 0.

T 2.00000000 Y3DD-27.0523000 Y3D 45.5412000Y3 128.366000 FD 10784.8000 Y2DD-29.7800000

Y2D 44.9787000 Y2 128.771000 FK2 10243.8000XDD-60.0685000 XD 93.2928000 X 362.577000FK1 4447.66000 Y1 258.519000

T 4.00000000 Y3DD-6.47941000 Y3D 18.5077000Y3 185.759000 FD 2372.52000 Y2DD-6.43700000

Y2D 18.4580000 Y2 185.847000 FK2 2242.94000XDD-13.4908000 XD 38.0155000 X 480.930000FK1 975.734000 Y1 371.909000

T 6.00000000 Y3DD-2.52881000 Y3D 10.3046000Y3 213.274000 FD 909.146000 Y2DD-2.49377000

Y2D 10.2911000 Y2 213.308000 FK2 858.569000XDD-5.18757000 XD 21.0975000 X 537.351000FK1 372.826000 Y1 426.699000

T 8.00000000 Y3DD-1.24592000 Y3D 6.73013000Y3 229.892000 FD 448.026000 Y2DD-1.23620000

Y2D 6.72517000 Y2 229.909000 FK2 423.108000XDD-2.56178000 XD 13.7554000 X 571.344000FK1 183.566000 Y1 459.858000

Time LimitT 10.0000000 Y3DD-0.69317600 Y3D 4.84296000

Y3 241.289000 FD 256.301000 Y2DD-0.72364700Y2D 4.84055000 Y2 241.299000 FK2 242.438000XDD-1.46562000 XD 9.88800000 X 594.623000FK1 104.836000 Y1 482.620000

SET STRPLT=.T.,PSFSPL=0.8 ! Turn on strip plots and scale for screenPLOT/XTAG='(sec)' x,xd,xddDrawing plot number 2SPARE ! List execution timeAccumulated cp time 469.0100. Elapsed cp time 62.91000QUIT

Figure A6-3. Aircraft arresting gear log file (part 2)



Figure A6-5. SPEED = 290 ft/s - line plot Figure A6-6. SPEED = 290 ft/s - strip plots

Figure A6-4. Displacement and its derivatives for SPEED of 200 ft/s



7. AircraftLongitudinalStudy

The aircraft longitudinal study illustrates an iteration to establish correct initialconditions (trim), the solution of an implicit loop, and the use of fixed versus variablestep integration algorithms.

The equations describing the motion of an aircraft in three degrees-of-freedom in alongitudinal plane are as follows:

Velocity

mV.

= T cosα − D − Wsin γ

wherem is mass,V is longitudinal velocity,T is thrust,α is angle-of-attack,D is drag,W is weight,γ is flight path angle,q is dynamic pressure,S is reference cross-sectionalarea,ρ is air density,δ is fin deflection, and:

m = W / 32.2 slugsD = qSCD lbsq = 0.5ρ V2 lbs/ft2

CD = CD0 + CDαα + CDδε |δε|

Flight Path

mVγ.

= L − W cosγ + T sin αL = qSCL lbs

CL = CL0 + CLα α + CLδδε + (c_

⁄ 2V ) (CLα. α

.+ CLqθ

.)

whereL is lift, c_

is the characteristic chord, andθ is pitch angle.

Pitch

Iy θ..

= M

whereM is moment and:

M = qS c_CM lbs

CM = CM0 + CMαα + CMδ δε + ( c_

⁄ 2V ) (CMα. + CMqθ

.)

Angle of Attack

α.

= θ.

− γ.

Position

h.

= V sin γx.

= V cosγ

A7. Aircraft Longitudinal Study A. ACSL Example Programs


Constants

T = 2,000 lbIy = 27x106 slug-ft2

ρ = 0.0023 slugs/ft3

S = 6,000 ft2

W = 500,000 lbc_

= 30 ft

Aerodynamic Coefficients

CD0 = 0.14CDα = 0.63 /radCDδε = 0.003 /rad

CL0 = 1.1CLα = 5.2 /radCLδε = 0.36 /rad

CLα. = 2 /rad/sec

CLq = 5.5 /rad/secCM0 = -0.05CMα = 0.2 /radCMδε = 1.4 /rad

CMα. = 8 /rad/sec

CMq = 22 /rad/sec

Initial Conditions

V(0) = 200 ft/sech(0) = 1500 ftθ(0) = 0 rad

Values ofθ(0), γ(0), andδε are to be computed so that the aircraft is flying in atrimmed condition;i.e., the angular accelerationθ

.., flight path rateγ

., and longitudinal

accelerationV.

should all be zero. It is more usual to adjust throttle setting as thrustTto maintain a given flight path angle rather than the other way around.

The program listing is shown in Figure A7-1. The iteration is mechanized by choosingstarting values in the INITIAL section forθ(0), γ(0), andδε (zero seems good enough).In the DYNAMIC section, after the first evaluation of derivatives, a weighted meansquare error is calculated:

E = V. 2 + (20 θ

..)2 + (100γ

.)2

This error is checked on whether it is less than a maximum allowable error (0.1). Ifnot, the initial guess is corrected by:

γ (0) = γ (0) + 0.02V.

θ(0) = θ(0) − 1.0γ.

δε(0) = δε(0) + 2.0θ..

A. ACSL Example Programs A7. Aircraft Longitudinal Study


A more precise (and faster) iteration would calculate the derivative of the error vector(V, γ, θ) with respect to the control vector (γ, θ, δ), which would result in athree-by-three Jacobian matrix (called J, for instance). The matrix J would then beinverted and the new control vector given by:

(γ, θ, δε)T = (γ, θ, δε)T − J−1 (V., γ

., θ

..)T

However, the simple iteration given suffices for this fixed example.

Once convergence has been satisfied, the variable START is set FALSE and the errorcheck is never examined again. Note that in order to recompute the derivatives, theprogram cycles from the DYNAMIC section back to the INITIAL section. Theintegration routine is set up and derivatives calculated at the transition from INITIALinto DYNAMIC.

Another feature illustrated in this example is the use of the IMPLC operator tocalculate angle-of-attack rate. Angle-of-attack rate is the difference between body rateand flight path rate. Flight path rate depends on lift, which in turn depends on thecoefficientCL. This coefficient includes angle-of-attack rate, so an algebraic (implicit)loop is formed. Such a loop is a problem for the sorting algorithm, but it can be solvedby including the IMPLC operator to calculate the angle-of-attack rate as follows:

α.

= IMPLC(γ.

+ α.

− q, aldz)

The residual is the difference between the sum ofα.

andq and flight path rateγ., which

should be zero. The IMPLC operator adjusts the angle of attack rateα.

to make this so.

This iteration is time consuming and is performed at each derivative evaluation. In thisexample, since the equations are linear, it would be possible (and better) to solvealgebraically forα

.before writing the model equations. However, ifCL is given in

functional form as a table (e.g., CL(α, α.)), then the implicit operator is required.

The log file from a runtime session is shown in Figure A7-2. An OUTPUT list isestablished to be output at every ten communication intervals; a similar set of variablesis specified in the PREPARE command for later printing and plotting. The STARTcommand initiates the run and the iteration is reported (via a WRITE statement in theprogram) in the next eight lines of output during which the error, ERR, is reducedfrom 55.4 to 0.1. Then the run starts and the OUTPUT variables are written out every0.5 seconds. At the end of the run (TMX = 6.49 seconds), two PRINT commands listselected variables, the first at every four communication intervals (0.2 seconds) andthe second at every eight (0.4 seconds).

A strip plot is shown in Figure A7-3. The strip plot option is set up (STRPLT=.T.) atthe bottom of Page 3 of the log file. The plot scale factor reduces the plot to fit on thescreen (PSFSPL=0.3), the X axis length is increased (XINSPL=10.0), and the distancebetween tick marks is increased (XTISPL=2.0). Reducing the overall plot size anddoubling XINSPL maintains the X axis length but reduces the strip width, allowingseven variables to be stacked on one frame. The first PLOT command sets /XHI to avalue chosen in a CONSTANT statement; the second PLOT command actually drawsthe picture. PLOT commands relating to the X axis remain in effect for subsequentplots until explicitly changed. Automatic scaling would round the X axis scale so thatit runs from zero to ten, thus wasting 35% of the plot area. With our choice of /XHI,the scales are marked in fractions rather than whole numbers, but this is the user'soption; we prefer maximum area utilization over even scales.



PROGRAM aircraft longitudinal stability studyINITIAL

!-----------------------need mass from weight in lbsCONSTANT g = 32.2aldz = qzmass = w/g!-----------------------set initial guess for initial conditionsgaz = 0.0 ! flight path anglethz = 0.0 ! pitch angledlz = 0.0 ! fin deflection!-----------------------start will be made true when iteration! convergesLOGICAL startstart = .false.

i1: CONTINUEEND ! of initial

!-----------------------the transition from initial to dynamic! transfers all initial conditions to the! state variables and evaluates the code! in the derivative section once

DYNAMIC!-----------------------change name of independent variable! to avoid name conflictVARIABLE time = 0.0!-----------------------communication intervalCINTERVAL cint = 0.05

DERIVATIVE!-----------------------fin deflection is kicked to excite systemCONSTANT tz = 0.5dle = 0.1*STEP(tz) + dlz!------------------------angle of attackal = th - ga!-----------------------drag coefficientCONSTANT cdz = 0.14 , cdal = 0.63 , cdde = 0.003cd = cdz + cdal*al + cdde*ABS(dle)!-----------------------lift coefficientCONSTANT clz = 1.1 , clal = 5.2 , clde = 0.36CONSTANT cb = 30.0 , clad = 2.0 , cltd = 5.5cl = &

clz + clal*al + clde*dle + (cb/(2*v))*(clad*ald + cltd*q)!-----------------------pitch moment coefficientCONSTANT cmz = 0.05 , cmal =-0.2 , cmde =-1.4CONSTANT cmad =-8.0 , cmtd =-22.0cm = &

cmz + cmal*al + cmde*dle + (cb/(2*v))*(cmad*ald + cmtd*q)!-----------------------dynamic pressureCONSTANT ro = 2.3e-3 ! air densityqp = 0.5*ro*v**2!-----------------------drag and liftCONSTANT s = 6000.0 ! characteristic spand = qp*s*cd ; l = qp*s*cl!-----------------------pitching momentm = qp*s*cb*cm

Figure A7-1. Aircraft longitudinal study program (part 1)



!-----------------------flight path rateCONSTANT w = 500000.0 , t = 2000.0gad = (l - w*COS(ga) + t*SIN(al))/(mass*v)!-----------------------longitudinal velocity ratevd = (t*COS(al) - d - w*SIN(ga))/mass!-----------------------need pitch rate derivative explicitly! for iterationCONSTANT iy = 27.0e6 ! pitch moment of inertiaqd = m/iy!-----------------------implicit loop for angle of attach rate! sum of flight path rate and angle of attack rate = pitch rateald = IMPLC(gad + ald - q, aldz)!-----------------------pitch rateCONSTANT qz = 0.0 ; q = INTVC(qd, qz)!-----------------------pitch angleth = INTEG(q, thz)!-----------------------velocityCONSTANT vz = 200.0 ; v = INTVC(vd, vz)!-----------------------flight path anglega = INTVC(gad, gaz)!-----------------------heightCONSTANT hz = 1500.0 ; h = INTEG(v*SIN(ga), hz)!-----------------------horizontal distance travelledCONSTANT xz = 0.0 ; x = INTEG(v*COS(ga), xz)

END ! of derivative!-----------------------if iteration convergedif(start) GO TO d1!-----------------------weighted error from trimerror = vd**2 + (20.0*qd)**2 + (100.0*gad)**2!-----------------------if within toleranceCONSTANT ermx = 0.1start = error .LE. ermx!-----------------------compute new trial valuesCONSTANT k1 = 0.02 , k2 = -1.0 , k3 = 2.0gaz = gaz + k1*vdthz = thz + k2*gaddlz = dlz + k3*qd!-----------------------print iteration information by writing! to a buffer and then displaying this string. It is given an! initial value to prevent message about used but not definedCHARACTER buffer*80; constant buffer = ' 'WRITE(buffer, 99) gaz, thz, dlz, errorCALL DISSTR(buffer)

99: FORMAT(' gaz ',e12.4,' thz ',e12.4,' dle ',e12.4,' err ',f10.1)!-----------------------return to initial region to restart! the integration algorithmGO TO i1

d1: CONTINUE!-----------------------express stopping criteriaCONSTANT tmx = 6.49TERMT(time.GE.tmx, 'Time Limit')


Figure A7-1. Aircraft longitudinal study program (part 2)




SET TITLE = 'Longitudinal Aircraft Stability Study'SPAREAccumulated cp time 11.44000. Elapsed cp time 0.S TCWPRN=80,PCWPRN=80 ! Force 3 column output widthOUTPUT/NCIOUT=10 time, m, q, vd, gad, dle, x, v, th, ga, al, ef, aldPREPARE time, m, q, vd, gad, dle, v, th, ga, alSET nstp = 10STARTgaz -0.4719E-01 thz 0.6241E-01 dle 0.7700E-02 err 44.5gaz -0.8857E-01 thz 0.7434E-01 dle 0.1392E-01 err 5.7gaz -0.1153E+00 thz 0.6129E-01 dle 0.1745E-01 err 3.5gaz -0.1280E+00 thz 0.4143E-01 dle 0.1878E-01 err 4.3gaz -0.1310E+00 thz 0.2455E-01 dle 0.1874E-01 err 2.9gaz -0.1290E+00 thz 0.1397E-01 dle 0.1813E-01 err 1.1gaz -0.1254E+00 thz 0.9211E-02 dle 0.1745E-01 err 0.3gaz -0.1222E+00 thz 0.8352E-02 dle 0.1694E-01 err 0.0

TIME 0. M-3821.85000 Q 0.VD 0.10212400 GAD-0.00105422 DLE 0.01693790

X 0. V 200.000000 TH 0.00835185GA-0.12222800 AL 0.13058000 EF 0.

ALD 0.00105423

TIME 0.50000000 M-2106.67000 Q-5.3857E-05VD 0.10956200 GAD-7.6518E-04 DLE 0.01693790

X 99.2640000 V 200.053000 TH 0.00833707GA-0.12268000 AL 0.13101700 EF 0.

ALD 7.1134E-04

TIME 1.00000000 M-818848.000 Q-0.01804110VD 0.14483600 GAD-8.2791E-04 DLE 0.11693800

X 198.557000 V 200.110000 TH 0.00356959GA-0.12216600 AL 0.12573500 EF 0.

ALD-0.01721320

TIME 1.50000000 M-588024.000 Q-0.03094360VD 0.31523900 GAD-0.00616469 DLE 0.11693800

X 297.882000 V 200.220000 TH-0.00885432GA-0.12385800 AL 0.11500400 EF 0.

ALD-0.02477890

TIME 2.00000000 M-424769.000 Q-0.04023500VD 0.60363600 GAD-0.01228010 DLE 0.11693800

X 397.249000 V 200.445000 TH-0.02677470GA-0.12845700 AL 0.10168200 EF 0.

ALD-0.02795490

TIME 2.50000000 M-308552.000 Q-0.04696490VD 0.99488200 GAD-0.01837100 DLE 0.11693800

X 496.689000 V 200.840000 TH-0.04866420GA-0.13613300 AL 0.08746840 EF 0.

ALD-0.02859490

TIME 3.00000000 M-225198.000 Q-0.05186500VD 1.47280000 GAD-0.02398200 DLE 0.11693800

X 596.251000 V 201.454000 TH-0.07343580

Figure A7-2. Aircraft longitudinal study log file (part 1)



ACSL Runtime Exec Version 6 Level 10B 27-FEB-91 11:48:34 Page 2Longitudinal Aircraft Stability Study

GA-0.14674700 AL 0.07331110 EF 0.ALD-0.02788300

TIME 3.50000000 M-164879.000 Q-0.05544720VD 2.02151000 GAD-0.02888260 DLE 0.11693800

X 696.002000 V 202.325000 TH-0.10031000GA-0.15999500 AL 0.05968500 EF 0.

ALD-0.02656460

TIME 4.00000000 M-120820.000 Q-0.05807150VD 2.62617000 GAD-0.03298520 DLE 0.11693800

X 796.020000 V 203.485000 TH-0.12872400GA-0.17549600 AL 0.04677210 EF 0.

ALD-0.02508630

TIME 4.50000000 M-88335.5000 Q-0.05999310VD 3.27343000 GAD-0.03629170 DLE 0.11693800

X 896.391000 V 204.958000 TH-0.15826500GA-0.19284800 AL 0.03458240 EF 0.

ALD-0.02370150

TIME 5.00000000 M-64181.2000 Q-0.06139440VD 3.95168000 GAD-0.03885730 DLE 0.11693800

X 997.210000 V 206.763000 TH-0.18863100GA-0.21166400 AL 0.02303340 EF 0.

ALD-0.02253710

TIME 5.50000000 M-46110.4000 Q-0.06240760VD 4.65109000 GAD-0.04076760 DLE 0.11693800

X 1098.57000 V 208.913000 TH-0.21959500GA-0.23159600 AL 0.01200050 EF 0.

ALD-0.02164000

TIME 6.00000000 M-32562.0000 Q-0.06313010VD 5.36369000 GAD-0.04212250 DLE 0.11693800

X 1200.58000 V 211.417000 TH-0.25099000GA-0.25233900 AL 0.00134915 EF 0.

ALD-0.02100760

Time LimitTIME 6.50000000 M-22446.0000 Q-0.06363470

VD 6.08326000 GAD-0.04302590 DLE 0.11693800X 1303.33000 V 214.278000 TH-0.28268900

GA-0.27364300 AL-0.00904608 EF 0.ALD-0.02060880

! Make column print of selected variables from prepar listPRINT/NCIPRN=4,time,m,q,vd,gad

Line TIME M Q VD GAD0 0. -3821.85000 0. 0.10212400 -0.001054224 0.20000000 -3054.08000 -2.5393E-05 0.10544200 -9.2969E-048 0.40000000 -2397.99000 -4.5523E-05 0.10829700 -8.1730E-04

12 0.60000000 -1.0717E+06 -0.00412532 0.10163300 0.0020084116 0.80000000 -936348.000 -0.01155060 0.11255400 8.1324E-04





Line TIME M Q VD GAD20 1.00000000 -818848.000 -0.01804110 0.14483600 -8.2791E-0424 1.20000000 -716758.000 -0.02371970 0.19797000 -0.0027983728 1.40000000 -627988.000 -0.02869260 0.27127400 -0.0050014232 1.60000000 -550735.000 -0.03305160 0.36393400 -0.0073574436 1.80000000 -483444.000 -0.03687620 0.47504600 -0.0098013240 2.00000000 -424769.000 -0.04023500 0.60363600 -0.0122801044 2.20000000 -373551.000 -0.04318750 0.74869300 -0.0147511048 2.40000000 -328804.000 -0.04578510 0.90917900 -0.0171804052 2.60000000 -289625.000 -0.04807230 1.08405000 -0.0195416056 2.80000000 -255308.000 -0.05008770 1.27227000 -0.0218139060 3.00000000 -225198.000 -0.05186500 1.47280000 -0.0239820064 3.20000000 -198741.000 -0.05343300 1.68465000 -0.0260349068 3.40000000 -175460.000 -0.05481710 1.90683000 -0.0279650072 3.60000000 -154941.000 -0.05603920 2.13841000 -0.0297679076 3.80000000 -136831.000 -0.05711850 2.37848000 -0.0314413080 4.00000000 -120820.000 -0.05807150 2.62617000 -0.0329852084 4.20000000 -106646.000 -0.05891290 2.88065000 -0.0344012088 4.40000000 -94079.0000 -0.05965540 3.14116000 -0.0356920092 4.60000000 -82922.3000 -0.06031020 3.40694000 -0.0368617096 4.80000000 -73005.3000 -0.06088700 3.67733000 -0.03791500

100 5.00000000 -64181.2000 -0.06139440 3.95168000 -0.03885730104 5.20000000 -56323.2000 -0.06184020 4.22939000 -0.03969470108 5.40000000 -49320.7000 -0.06223100 4.50993000 -0.04043330112 5.60000000 -43079.5000 -0.06257280 4.79278000 -0.04107970116 5.80000000 -37516.9000 -0.06287090 5.07751000 -0.04164050120 6.00000000 -32562.0000 -0.06313010 5.36369000 -0.04212250124 6.20000000 -28152.1000 -0.06335460 5.65098000 -0.04253220128 6.40000000 -24234.9000 -0.06354830 5.93903000 -0.04287640

PRINT/NCIPRN=8,time,dle,th,ga,al

Line TIME DLE TH GA AL0 0. 0.01693790 0.00835185 -0.12222800 0.130580008 0.40000000 0.01693790 0.00834205 -0.12260100 0.13094300

16 0.80000000 0.11693800 0.00654326 -0.12217100 0.1287140024 1.20000000 0.11693800 -6.1909E-04 -0.12252400 0.1219050032 1.60000000 0.11693800 -0.01205520 -0.12453400 0.1124790040 2.00000000 0.11693800 -0.02677470 -0.12845700 0.1016820048 2.40000000 0.11693800 -0.04402600 -0.13435500 0.0903288056 2.80000000 0.11693800 -0.06323690 -0.14216600 0.0789286064 3.20000000 0.11693800 -0.08396890 -0.15175100 0.0677817072 3.60000000 0.11693800 -0.10588500 -0.16292800 0.0570432080 4.00000000 0.11693800 -0.12872400 -0.17549600 0.0467721088 4.40000000 0.11693800 -0.15228300 -0.18924800 0.0369656096 4.80000000 0.11693800 -0.17640100 -0.20398500 0.02758360

104 5.20000000 0.11693800 -0.20095500 -0.21952100 0.01856590112 5.60000000 0.11693800 -0.22584400 -0.23568800 0.00984395120 6.00000000 0.11693800 -0.25099000 -0.25233900 0.00134915128 6.40000000 0.11693800 -0.27633000 -0.26934800 -0.00698215

S STRPLT=.T.,CALPLT=.F.,PSFSPL=0.3,XINSPL=10.0,XTISPL=2.0PLOT/XHI=tmx ! Plot nothing - but establish full range for scaleDrawing plot number 1PLOT th,al,ga,gad,q,m,dleDrawing plot number 2





! Change output list for time trial between rk4 and adams-moultonOUTPUT/CLEAR time,cioitg,cssitg/NCIOUT=30SPARE ; START ; SPAREAccumulated cp time 24.19000. Elapsed cp time 12.75000gaz -0.4719E-01 thz 0.6241E-01 dle 0.7700E-02 err 44.5gaz -0.8857E-01 thz 0.7434E-01 dle 0.1392E-01 err 5.7gaz -0.1153E+00 thz 0.6129E-01 dle 0.1745E-01 err 3.5gaz -0.1280E+00 thz 0.4143E-01 dle 0.1878E-01 err 4.3gaz -0.1310E+00 thz 0.2455E-01 dle 0.1874E-01 err 2.9gaz -0.1290E+00 thz 0.1397E-01 dle 0.1813E-01 err 1.1gaz -0.1254E+00 thz 0.9211E-02 dle 0.1745E-01 err 0.3gaz -0.1222E+00 thz 0.8352E-02 dle 0.1694E-01 err 0.0

TIME 0. CIOITG 4 CSSITG 0.00500000TIME 1.50000000 CIOITG 4 CSSITG 0.00500000TIME 3.00000000 CIOITG 4 CSSITG 0.00500000TIME 4.50000000 CIOITG 4 CSSITG 0.00500000TIME 6.00000000 CIOITG 4 CSSITG 0.00500000

Time LimitTIME 6.50000000 CIOITG 4 CSSITG 0.00500000

Accumulated cp time 30.68000. Elapsed cp time 6.490000SET ialg = 1 ! Try adams-moulton integrationSPARE ; START ; SPAREAccumulated cp time 30.74000. Elapsed cp time 0.060001gaz -0.4719E-01 thz 0.6241E-01 dle 0.7700E-02 err 44.5gaz -0.8857E-01 thz 0.7434E-01 dle 0.1392E-01 err 5.7gaz -0.1153E+00 thz 0.6129E-01 dle 0.1745E-01 err 3.5gaz -0.1280E+00 thz 0.4143E-01 dle 0.1878E-01 err 4.3gaz -0.1310E+00 thz 0.2455E-01 dle 0.1874E-01 err 2.9gaz -0.1290E+00 thz 0.1397E-01 dle 0.1813E-01 err 1.1gaz -0.1254E+00 thz 0.9211E-02 dle 0.1745E-01 err 0.3gaz -0.1222E+00 thz 0.8352E-02 dle 0.1694E-01 err 0.0

TIME 0. CIOITG 1 CSSITG 0.00500000TIME 1.50000000 CIOITG 1 CSSITG 0.05000000TIME 3.00000000 CIOITG 3 CSSITG 0.05000000TIME 4.50000000 CIOITG 3 CSSITG 0.05000020TIME 6.00000000 CIOITG 3 CSSITG 0.05000020

Time LimitTIME 6.50000000 CIOITG 3 CSSITG 0.05000020

Count of times state controlled step sizeMinus (-) means relative error always below absolute error

GA pc fail 0 err control 18-H pc fail 0 err control 0Q pc fail 0 err control 6-

TH pc fail 0 err control 99-V pc fail 0 err control 0X pc fail 0 err control 16

Accumulated cp time 32.49000. Elapsed cp time 1.750000PRINT/NCIPRN=20 time,m,q,vd,gad

Line TIME M Q VD GAD0 0. -3821.88000 0. 0.10212300 -0.00105422

20 1.00000000 -822255.000 -0.01786570 0.15172300 -9.4945E-0440 2.00000000 -430787.000 -0.03991230 0.61984500 -0.0122988060 3.00000000 -228140.000 -0.05170150 1.48509000 -0.0239013080 4.00000000 -122287.000 -0.05798640 2.63490000 -0.03288610

100 5.00000000 -64935.0000 -0.06134890 3.95764000 -0.03877090120 6.00000000 -32967.2000 -0.06310520 5.36772000 -0.04205790




The sequence on Page 4 of the log file compares results from the standardRunge-Kutta fourth order integration routine with those from the Adams-Moultonvariable order, variable step routine. The OUTPUT list is cleared (/CLEAR) andreestablished as TIME, CIOITG (current integration order), and CSSITG (current stepsize) to be printed out every thirty communication intervals. The SPARE ; START ;SPARE sequence runs the simulation with the default algorithm (IALG = 5,Runge-Kutta fourth order) and shows an elapsed central processor time of about 6.49sec. Then IALG is changed to 1 (Adams-Moulton) and the program run again. Theintegration order rises to four and the step size to the communication interval (0.05sec), where it stops increasing. The current step size variable CSSITG shows the actualstep size the integration algorithm last used before the communication interval endedand the data was logged. From the report at the end of the Adams-Moulton variablestep run, it can be deduced thatθ (TH) was the controlling integrator; the minus sign(-) indicates that the relative error never exceeded the absolute error specified. Theallowable error was therefore set at the default of 0.0001. The elapsed time for this runis about 1.75 sec, so the Adams-Moulton integrator is nearly four times faster than theRunge-Kutta in this example. Results of the Adams-Moulton run are printed out at onesecond intervals for comparison with the same variables printed in the previous runs.Agreement is within two or three decimal places.


ANALYZE/FREEZE=x/JACOBIAN/EIGEN ! List jacobian and eigenvaluesFunction evaluation not repeatable, row 3 (QD)Row vector names

GA 1 H 2 Q 3TH 4 V 5

Column vector namesGAD 1 Z09989 2 QD 3

Z09990 4 VD 5

Matrix elements - rows across, columns down1 2 3 4 5

1 -0.5294010 0. 0.0493415 0.4893170 0.00114602 206.37500 0. 0. 0. -0.27042703 -0.0339586 0. -0.7297710 0.0260465 3.824E-054 0. 0. 1.0000200 0. 0.5 -18.143700 0. 0. -12.860300 -0.0256390

Function evaluation not repeatable, row 3 (QD)Complex eigenvalues in ascending order

REAL1 0.011319002 0.3 -0.108658004 -0.366068005 -0.82140400

SPARE ! List execution timeAccumulated cp time 33.32000. Elapsed cp time 0.830002QUIT ! Note intermediate spare




The ratio of execution for Runge-Kutta to Adams-Moulton may be misleading. Theartificially small step size (0.005 sec) chosen arbitrarily for the Runge-Kutta fourthorder algorithm unfairly penalizes the comparison. In actual tests with typicalnonlinear systems, the second order Runge-Kutta method (IALG=4) does best in termsof cpu seconds per simulated second. The penalty is that the user must choose the stepsize, normally by experimentation, but sometimes by familiarity with the model. Asmentioned above, a good rule of thumb is to make the integration step size (MAXT)equal to the smallest time constant in the model. Of course, if the controlling timeconstants change significantly, then the variable step algorithms are called for.

The use of the ANALYZE command is shown on Page 5 of the log file. The Jacobianand its eigenvalues are printed out with the /JACOBIAN and /EIGEN switches. Thelargest eigenvalue is 0.82 per second, which implies a rather slowly varying systemand in actual fact promises good results with integration step sizes the reciprocal ofthis value or about one second, a further factor of twenty increase in solution speed. Inthis case, the constant constraint on the step size is the data recording interval (CINT)chosen to produce acceptable plots.

Figure A7-3. Aircraft longitudinal study plot



8. PhysiologicalBenchmark

A benchmark model called PHYSBE (physiological simulation benchmarkexperiment)* demonstrates various techniques for solving simulation problems,including macro expansion and concatenation.

The system models blood flow through a human body. The blood is driven by twopumps;i.e., the right and left ventricles of the heart. Figure A8-1 shows theinterconnection of the various components of the system. Each component isconsidered to be a large bag or balloon that can be filled with blood. The salientcharacteristic of the components is that the more blood forced in, the higher thepressure.

There are valves between the vena cava (VC) and the right ventricle (RV), the rightventricle and the lungs (LN), the lungs and the left ventricle (LV), and the leftventricle and the aorta (AO). These valves allow blood flow only in the forwarddirection.

The blood is driven around the loop by changing the compliance of the right and leftventricles as a function of time, thus modeling the squeezing of the blood in thechambers by the heart muscle as it contracts and releases. Figure A8-2 shows thisreciprocal compliance as a function of time; the function is repeated every second asthe heart beats.

Figure A8-1. Interconnection of lumps to form blood distribution system

A. ACSL Example Programs A8. Physiological Benchmark


* McLeod, J., "PHYSBE: A Physiological Simulation Benchmark Experiment",SIMULATION7 (1966)pp. 324-329.

Each component of the system is considered a lump which contains mass balance andheat balance constraints. The model operates on the following assumptions:

1. Physical parameters of the system are linear.2. Blood flow within each area is influenced only by:

a. inlet pressureb. inflow resistancec. compliance (volume/unit pressure)d. outflow resistancee. outlet pressure

3. There is no resistance to blood flow within components.4. All endogenous heat will be absorbed by the blood and conducted by

the blood.5. The specific heat of blood and all body components is unity.6. Temperature change within the arteries, ventricles, and great veins is

negligible.

Figure A8-3 is a schematic representation of the mass and heat flow for any lump.This structure is programmed in a macro (as seen in the program listing in FigureA8-6), which is later invoked for each of the nine lumps in turn with the XX in theequations (X in the macro definition) replaced by the appropriate two charactermnemonic. The equations for the macro are developed beginning with the input flowrate, which is a function of the pressure differential and input resistance as follows:

fxxi = (pxxi - pxx)/rxxi

Pressure in the bag is volume divided by compliance:

pxx = vxx/cxx

Outlet flow rate is given by the pressure differential and output resistance:

fxxo = (pxx - pxxo)/rxxo

Figure A8-2. Reciprocal compliance (pressure per unit volume) for PHYSBE heart chambers

A8. Physiological Benchmark A. ACSL Example Programs


The volume of blood is the mass flow rate integrated as follows:

vxx = ∫0

T

(fxxi - fxxo) dt + vxxz

Heat (enthalpy) flow in is:

qxxi = fxxi*txxi

Temperature is the total enthalpy in the lump divided by the mass:

txx = hxx/wxx

Heat flow out is:

qxxo = fxxo*txx

Heat dissipated to the surroundings is:

qxxd = k*axx*(txx - ta)

where K is the thermal transfer coefficient, AXX is area associated with the givenlump, and TA is the ambient temperature. The accumulated heat is:

hxx = ∫0

T

(qxxi - qxxo + qxxe - qxxd) dt + hxxz

The first line of the macro definition identifies the macro name (LUMP) and thesubstitutable parameter (X) as follows:

MACRO lump(x)

This macro uses concatenation (indicated by &) in all of its assignment statements.Concatenation allows one macro to be used for all the lump components with uniquenames for each component. For example, input flow is expressed as follows in themacro:

f&x&o = (p&x&i - p&x)/r&x&i

Figure A8-3. Lump definition - mass and enthalpy balance



which means F concatenated with the argument, concatenated with an O, etc. Whenthe macro is invoked to describe the head (designated by HD), quoting the letters HDimplies that it is a literal string (i.e., substitutable parameter) rather than a symbol oran argument. The macro call is this case is:

lump("hd")

The expansion of the macro for this invocation is shown in Figure A8-4.

A second macro is required for the valves. The VALVE macro calculates resistance(R) from outlet pressure (PO), inlet pressure (PI), and the open resistance of the valve(RZ). If the valve is closed, the resistance rises to a large value (1020) to effectivelyshut off flow. The macro header definition is as follows:

MACRO valve(r, po, pi, rz)

The names in the VALVE macro header are arguments. The action of the valve isdefined as follows:

r = rz po ≤ pir = 10 20 po < pi

This is accomplished by an IF-THEN-ELSE block as follows:

MACRO valve(r, po, pi, rz)IF(po .GT. pi) THEN

r = 1.0e20ELSE

r = rzENDIF

MACRO END

An example of use of the VALVE macro is the following invocation to calculateresistance into the right ventricle:

valve(rrvi = prv, pvc, rrvic)

which expands as shown in Figure A8-5. This expansion can be read as follows: theinput resistance to the right ventricle is RRVIZ if the pressure in the right ventricle(PRV) is less than the pressure in the vena cava (PVC); otherwise, it is 1020 (to preventany backflow).

The constants necessary to specify the system behavior are defined in the programlisting (Figure A8-6). Since no heat flux constants were given in the problem

lump("hd") ! headRHDI = (PHDI - PHD)/RHDIPHD = VHD/CHDFHDO = (PHD - PHDO)/RHDOVHD = INTEG(FHDI - FHDO, VHDZ)QHDI = FHDI*THDITHD = HHD/WHDQHDO = FHDO*THDQHDD = K*AHD*(THD - TA)HHD = INTEG(QHDI - QHDO + QHDE - QHDD, HHDZ)MACROEND

Figure A8-4. Macro invocation and expansion for HD (head) lump



definition, they are set to zero. The temperature equations therefore do not calculateany significant quantities even though they are present. Since there is no feedback, thetemperature does not affect the system.

The first calculations in the DERIVATIVE section determine the compliance of theventricles (CRV and CLV), which drive the system that causes the heart to pump. Thereciprocal compliance (shown in Figure A8-2) is a function of time that repeats eachsecond. This code uses the IF-THEN-ELSE structure.

Next, the four valves are defined, one in and one out of the right and left ventricles.The interconnections of each lump (Figure A8-1) define the inlet and outlet. For thesimple case of two elements in cascade, the outlet pressure is the effect of tworesistances connected between two pressure sources, depicted as follows:

pxx pxxo pyyi pyy

o___ΛΛΛΛ____ o______ o____ ΛΛΛΛ____ orxxo ryyi

pxxo = (pxx*ryyi + pyy*rxxo)/(ryyi + rxxo)pyyi = pxxo

The aorta and vena cave are more difficult since the first feeds five other lumps andthe second receives flow from the five. Writing down the flow balance — equivalentto Kirchoff's law — leads to the following for the aorta output pressure:

pao/raoo + phd/rhdi + par/rari + plg/rlgi + ptr/rtripaoo = ____________________________________________________

1/rcvi + 1/rhdo + 1/raro + 1/rlgo + 1/rtro

and similarly for the vena cava inlet pressure:

pvc/rcvi + phd/rhdo + par/raro + plg/rlgo + prt/rtropvci = ____________________________________________________

1/rcvi + 1/rhdo + 1/raro + 1/rlgo + 1/rtro

The last statements in the DERIVATIVE section define each of the nine lumps byinvoking the LUMP macro with the appropriate two-character string.

MACRO valve(r, po, pi, rz)IF(po .GT. pi) THEN

r = 1.0E20ELSE

r = rzENDIF

MACRO END

VALVE(rrvi = prv, pvc, rrviz)IF(prv .GT. pvc) THEN

rrvi = 1.0E20ELSE

rrvi = rrvizENDIF

Figure A8-5. VALVE macro and its expansion for inlet valve



The DYNAMIC section code (interrogated every communication interval) follows theend of the DERIVATIVE section and contains the termination condition (TERMT).The program terminates when time exceeds TSTP. The default of TSTP is set at fourseconds so that the model will go through four cycles during a run.

Figure A8-7 shows the log file of a runtime session. Prior to the START, thecommunication interval (CINT) is set to 0.02 sec, NSTP (number of integration stepsper communication interval) to 1, and the integration step size specified by themaximum step size (MAXT) to be 0.01 sec. CINTERVAL, NSTEPS, andMAXTERVAL are not specified in the program, but default names CINT, NSTP, andMAXT can be accessed at runtime. Here we override the default values of 0.1, 10, and1.0E10 so that CINT is the data logging rate and MAXT controls the integration stepsize.

PROGRAM physbeINITIALMACRO lump(x)

f&x&i =(p&x&i - p&x)/r&x&ip&x = v&x/c&xf&x&o =(p&x - p&x&o)/r&x&ov&x = INTEG(f&x&i - f&x&o, v&x&z)q&x&i = f&x&i*t&x&it&x = h&x/w&xq&x&o = f&x&o *t&xq&x&d = k*a&x*(t&x - ta)h&x = INTEG(q&x&i - q&x&o + q&x&e - q&x&d, h&x&z)

MACRO ENDMACRO valve(r, po, pi, rz)

IF(po.GT.pi) THENr = 1.0e20

ELSEr = rz

ENDIFMACRO END

CONSTANT raoi = 1.e-2 , raoo = 1.e-2 , cao = 1.01 , vaoz= 80.8CONSTANT rari = 5.15 , raro = 10.0 , car = 4.25 , varz= 268.0CONSTANT rhdi = 2.58 , rhdo = 5.0 , chd = 1.21 , vhdz= 68.0CONSTANT rtri = 0.67 , rtro = 1.42 , ctr = 34.0 , vtrz= 2180.CONSTANT rlgi = 2.58 , rlgo = 5.00 , clg = 11.1 , vlgz= 700.0CONSTANT rvci = 1.e-2 , rvco = 1.e-2 , cvc = 250.0 , vvcz= 650.0CONSTANT rlni = 1.e-2 , rlno = 0.1875, cln = 10.0 , vlnz= 200.0CONSTANT rrviz= 0.0030, rrvoz= 0.0030CONSTANT rlviz= 0.0275, rlvoz= 0.0060CONSTANT vlvz = 319.0 , vrvz = 120.0CONSTANT aao = 0.0 , wao = 1.0 , qaoe= 0.0 , haoz= 0.0CONSTANT aar = 3670.0, war = 7000.0, qare = 0.0 , harz= 0.0CONSTANT ahd = 1400.0, whd = 4500.0, qhde = 0.0 , hhdz= 0.0CONSTANT atr = 6000.0, wtr = 53000., qtre = 0.0 , htrz= 0.0CONSTANT alg = 7000.0, wlg = 18500., qlge = 0.0 , hlgz= 0.0CONSTANT avc = 0.0 , wvc = 1.0 , qvce = 0.0 , hvcz= 0.0CONSTANT arv = 0.0 , wrv = 600.0 , qrve = 0.0 , hrvz= 0.0CONSTANT aln = 50000., wln = 1000.0, qlne = 0.0 , hlnz= 0.0CONSTANT alv = 0.0 , wlv = 600.0 , qlve = 0.0 , hlvz= 0.0CONSTANT k = 0.01 , ta = 0.0 , tstp = 3.99CONSTANT tmx = 0.4 , tmn = 0.5, &

cimx = 0.428 , cimn = 0.0133END ! of initial

Figure A8-6. Physiological benchmark program (part 1)



DYNAMICDERIVATIVE

tf = MOD(t, 1.0) ! Modulus repeats every second!-----------------------compute triangular waveIF(tf .LE. tmx) THEN

ci = (cimx - cimn)*tf/tmx + cimnELSE IF(tf .LE. tmn) THEN

ci = (cimx - cimn)*(tmn - tf)/(tmn - tmx) + cimnELSE

ci = cimnENDIF!-----------------------right and left ventricle compliancescrv = 1.0/ci ; clv = crv! valves in right and left ventriclesvalve(rrvi = prv, pvc, rrviz)valve(rrvo = pln, prv, rrvoz)valve(rlvi = plv, pln, rlviz)valve(rlvo = pao, plv, rlvoz)!-----------------------define the interconnections! vena cava feeds right ventriclepvco =(pvc*rrvi + prv*rvco)/(rrvi + rvco)prvi = pvco !right ventricletrvi = tvc!-----------------------right ventricle feeds lungsprvo =(prv*rlni + pln*rrvo)/(rlni + rrvo)plni = prvo !lung inputstlni = trv!-----------------------lungs feed left ventricleplno =(pln*rlvi + plv*rlno)/(rlvi + rlno)plvi = plno !left ventricle inputstlvi = tln!-----------------------left ventricle feeds aortaplvo =(plv*raoi + pao*rlvo)/(raoi + rlvo)paoi = plvo !aorta inputstaoi = tlv!-----------------------aorta feeds head,arms,legs and trunkpaoo =(pao/raoo + phd/rhdi + par/rari + plg/rlgi + ptr/rtri)&

/(1.0/raoo + 1.0/rhdi + 1.0/rari + 1.0/rlgi + 1.0/rtri)phdi = paoo !head inputsthdi = taopari = paoo !arms inputstari = taoplgi = paoo !leg inputstlgi = taoptri = paoo !trunk inputsttri = tao! vena cava is return from head,arms,legs and trunkpvci =(pvc/rvci + phd/rhdo + par/raro + plg/rlgo + ptr/rtro)&

/(1.0/rvci + 1.0/rhdo + 1.0/raro + 1.0/rlgo + 1.0/rtro)tvci =(thd*fhdo + tar*faro + tlg*flgo + ttr*ftro)/fvciparo = pvci ; phdo = pvci ; plgo = pvci ; ptro = pvci!-----------------------define each lumplump("rv") !right ventriclelump("ln") !lungslump("lv") !left ventriclelump("ao") !aortalump("ar") !armslump("hd") !headlump("tr") !trunklump("lg") !legslump("vc") !vena cava

END ! of derivativeTERMT(t.GE.tstp)


Figure A8-6. Physiological benchmark program (part 2)




SET TITLE='Physiological Simulation Benchmark Experiment (PHYSBE)'SPAREAccumulated cp time 88.19000. Elapsed cp time 0.SET TCWPRN=72 ! force 3 column output widthPREPARE t,prv,pln,plv,pao,phd,ptr,par,plg,pvc,fvci &

,faoo,faro,fhdo,flgo,flno,flvo,frvo,ftro,fvco,crv,clv,ciOUTPUT/NCIOUT=25 t, prv, pln, pao, phdSET cint=0.02,nstp=1,maxt=0.010START

T 0. PRV 1.59600000 PLN 20.0000000PAO 80.0000000 PHD 56.1983000

T 0.50000000 PRV 0.85087600 PLN 25.4171000PAO 100.881000 PHD 56.9120000

T 1.00000000 PRV 1.58568000 PLN 20.9539000PAO 74.2732000 PHD 56.8335000

T 1.50000000 PRV 0.87361500 PLN 26.0932000PAO 99.1535000 PHD 57.0085000

T 2.00000000 PRV 1.62192000 PLN 21.4780000PAO 73.5419000 PHD 56.7580000

T 2.50000000 PRV 0.89439700 PLN 26.7112000PAO 98.2354000 PHD 56.8378000

T 3.00000000 PRV 1.65475000 PLN 21.9627000PAO 73.0300000 PHD 56.5338000

T 3.50000000 PRV 0.91349000 PLN 27.2809000PAO 97.8142000 PHD 56.6051000

T 4.00000000 PRV 1.68449000 PLN 22.4132000PAO 72.6692000 PHD 56.2999000

PRINT/NCIPRN=4,t,prv,pln,flvo,frvo

Line T PRV PLN FLVO FRVO0 0. 1.59600000 20.0000000 -7.5757E-19 -1.8404E-194 0.08000000 11.5798000 19.8290000 -4.6118E-19 -8.2492E-208 0.16000000 21.4102000 19.9122000 -1.7011E-19 115.227000

12 0.24000000 25.9034000 21.9789000 267.249000 301.88600016 0.32000000 26.8695000 24.0743000 287.502000 215.01900020 0.40000000 27.3245000 25.4770000 279.166000 142.11400024 0.48000000 6.10522000 25.5175000 -7.6891E-19 -1.9412E-1928 0.56000000 0.96275900 24.8174000 -9.2132E-19 -2.3855E-1932 0.64000000 1.10026000 24.0467000 -8.6294E-19 -2.2946E-1936 0.72000000 1.22565000 23.3079000 -8.1456E-19 -2.2082E-1940 0.80000000 1.34014000 22.5995000 -7.7440E-19 -2.1259E-1944 0.88000000 1.44485000 21.9204000 -7.4098E-19 -2.0476E-1948 0.96000000 1.54075000 21.2693000 -7.1310E-19 -1.9729E-1952 1.04000000 6.55012000 20.7661000 -5.5885E-19 -1.4216E-1956 1.12000000 16.4692000 20.7576000 -2.7776E-19 -4.2884E-2060 1.20000000 24.8305000 21.4635000 1.19909000 259.001000

Figure A8-7. Physiological benchmark log file (part 1)



ACSL Runtime Exec Version 6 Level 10B 27-FEB-91 17:12:52 Page 2Physiological Simulation Benchmark Experiment (PHYSBE)

Line T PRV PLN FLVO FRVO64 1.28000000 27.2136000 23.7529000 281.516000 266.20900068 1.36000000 27.8311000 25.5167000 276.736000 178.03300072 1.44000000 17.0744000 26.2029000 -3.5744E-19 -9.1285E-2076 1.52000000 0.91249900 25.8843000 -9.3898E-19 -2.4972E-1980 1.60000000 1.05932000 25.0704000 -8.7719E-19 -2.4011E-1984 1.68000000 1.19308000 24.2901000 -8.2599E-19 -2.3097E-1988 1.76000000 1.31510000 23.5420000 -7.8350E-19 -2.2227E-1992 1.84000000 1.42655000 22.8248000 -7.4816E-19 -2.1398E-1996 1.92000000 1.52851000 22.1372000 -7.1871E-19 -2.0609E-19

100 2.00000000 1.62192000 21.4780000 -6.9409E-19 -1.9856E-19104 2.08000000 11.7723000 21.2659000 -4.1456E-19 -9.4935E-20108 2.16000000 21.9013000 21.2750000 -1.3855E-19 48.1771000112 2.24000000 27.1105000 23.1554000 265.840000 304.237000116 2.32000000 28.2364000 25.3151000 276.693000 224.717000120 2.40000000 28.7275000 26.7861000 268.981000 149.335000124 2.48000000 6.41881000 26.8273000 -7.4895E-19 -2.0408E-19128 2.56000000 1.01032000 26.0731000 -8.9855E-19 -2.5063E-19132 2.64000000 1.15277000 25.2532000 -8.4316E-19 -2.4100E-19136 2.72000000 1.28260000 24.4671000 -7.9723E-19 -2.3185E-19140 2.80000000 1.40106000 23.7135000 -7.5906E-19 -2.2312E-19144 2.88000000 1.50931000 22.9909000 -7.2727E-19 -2.1482E-19148 2.96000000 1.60837000 22.2982000 -7.0074E-19 -2.0690E-19152 3.04000000 6.83498000 21.7533000 -5.4946E-19 -1.4918E-19156 3.12000000 17.1855000 21.7380000 -2.7300E-19 -4.5525E-20160 3.20000000 25.9476000 22.4578000 2.67410000 268.441000164 3.28000000 28.4586000 24.8434000 277.109000 278.087000168 3.36000000 29.1073000 26.6870000 272.466000 186.172000172 3.44000000 17.8576000 27.4047000 -3.5268E-19 -9.5471E-20176 3.52000000 0.95358700 27.0605000 -9.2636E-19 -2.6107E-19180 3.60000000 1.10507000 26.2021000 -8.6562E-19 -2.5097E-19184 3.68000000 1.24300000 25.3791000 -8.1528E-19 -2.4136E-19188 3.76000000 1.36873000 24.5901000 -7.7349E-19 -2.3221E-19192 3.84000000 1.48351000 23.8337000 -7.3873E-19 -2.2350E-19196 3.92000000 1.58843000 23.1085000 -7.0974E-19 -2.1520E-19200 4.00000000 1.68449000 22.4132000 -6.8550E-19 -2.0729E-19

S STRPLT=.T.,CALPLT=.F.,PSFSPL=0.8PLOT frvo,pln,prvDrawing plot number 1S CALPLT=.T.,STRPLT=.F.PLOT prv, plnDrawing plot number 2OUTPUT/CLEAR ! No outputPREPARE/CLEAR ! No data savedSPARE ; START ; SPARE ! Measure raw computational speedAccumulated cp time 97.25000. Elapsed cp time 9.060000Accumulated cp time 100.2200. Elapsed cp time 2.970000QUIT ! Note intermediate spare

Figure A8-7. Physiological benchmark log file (part 2)



After the START command initiates the run, the values of the variables on theOUTPUT list are printed out every half second, since /NCIOUT (number ofcommunication intervals per OUTPUT) is 25.

After the simulation run has been completed, the PRINT command provides a moredetailed printout for two pressures (PRV and PLN) and two flows (FLVO and FRVO)every four communication intervals (80 msec). Next, a strip plot of the right ventricleflow and the lung and right ventricle pressures is obtained by setting STRPLT toTRUE (Figure A8-8). Then STRPLT is set back to FALSE and a regular line plot(CALPLT=.T.) is plotted (Figure A8-9).

The last action is to measure raw cpu speed by turning off all I/O functions (OUTPUT/CLEAR and PREPAR /CLEAR) and running and timing the four seconds ofexecution (SPARE ; START ; SPARE). This shows that a MicroVAX took 2.97 CPUseconds to execute this example. This procedure for measuring cpu time is useful forcomparing the capabilities of different machines, for comparing the efficiency ofdifferent integration algorithms for a particular program, or for monitoring a program'sload on the computer.

Figure A8-8. PHYSBE strip plotright ventricle and lung pressure

and right ventricle flow

Figure A8-9. PHYSBE line plot —right ventricle and lung pressures



9. Phase andGain

The Phase and Gain example illustrates frequency response analysis of a nonlinearsystem, the use of DERIVATIVE and DISCRETE sections, multiple INITIALsections, and plotting with a logarithmic scale.

The characteristics of the system are obtained by forcing the model with a sine waveand determining the in-phase and quadrature components, from which gain and phaseare calculated. Changing frequency slowly allows successive points to be calculateduntil, at the end of a single run, the complete Bode plot is generated.

This method is a relatively expensive way (i.e., in computer costs) to obtain frequencyresponse and is seldom justified for linear systems. For nonlinear plants, however, thisis the best method available, and it can be used to match hardware bench tests excitedby sinewave generators. The excitation amplitude must be chosen correctly and themodel must be in steady state while the measurements are taken. In a nonlinear plant,the results change as the amplitude of the exciting sinewave is varied.

The plant used for this example is described by the following transfer function:

yx

= G(s) =0.5 s + 1

0.03 s2 + 0.1 s + 1

The program is listed in Figure A9-1. A DISCRETE block is established to repeat atevery cycle of a given frequency and to examine the in-phase and quadraturecomponents of a full cycle of integration. When the change in phase from cycle tocycle has become small enough, the data point is recorded and the frequency changedso that another point can be calculated.

Five INITIAL sections are placed throughout the program rather than one INITIALsection at the beginning. This method has the advantage of keeping the INITIALcalculations with related code in the dynamic part of the program, making reading andunderstanding the program easier. The translator collects all the INITIAL sections andplaces them in the INITIAL section of the compile file in the order given.

The first frequency W (rad/s) and phase FI (rad) are set in their respective INITIALsections. The frequency is started at a specified maximum value and then reducedgeometrically (so that the final logarithmic plot will have equally spaced points) by:

w = MAX(wmn, kw*w)

For this application, KW is defined to be 0.8 and the frequency sweep is from amaximum value (WMX) of 100.0 down to a minimum value (WMN) of 1.0.

The plant is defined in the DERIVATIVE CONTINUE section. First the name for thestep size is defined (MAXTC) and set to 0.01. Constants for the frequency bounds(WMN and WMX), the amplitude of the forcing function (XMAG), and the settlingtime (TSETTL) are specified. Since the plant is linear, the value of XMAG has noeffect, but for a real nonlinear plant, this value should be chosen to match the plantcapability. The actual forcing function (X) is obtained from:

x = xmag*SIN(w*t + fi)

where FI is a parameter used to ensure continuity of X when the frequency W ischanged.

A. ACSL Example Programs A9. Phase and Gain


PROGRAM phase and gain

!-----------------------compute phase and gain of a given! transfer function by integrating over a complete cycle.! continue to integrate until phase change from cycle to cycle! is less than some preset minimum

CINTERVAL cint = 1.0NSTEPS nstp = 1

PARAMETER (rmn = 1.0e-30 , rmx = 1.0e30)PARAMETER (raddeg = 57.3 , pi = 3.14159)

DISCRETE

INTERVAL period = 0.0 ! indicate period will be calculated

!-----------------------change in in-phase and quadrature! integrals over last cycledlp = p - ppdlq = q - qp!-----------------------if relative change too small for mach accCONSTANT epm = 1.0e-7TERMT((dlp**2 + dlq**2)/(p**2 + q**2 + rmn) .LT. epm**2 &

, 'Change over one Cycle Too Small for Machine Accuracy')!-----------------------save new integrals as previous

INITIALpp = 1.0qp = 1.0

END ! of initialpp = pqp = q!-----------------------calculate new phase and gainpdgn = ATAN2(dlq, dlp + rmn)*raddeggdbn = 10.0*LOG10((dlp**2 + dlq**2 + rmn)*(w/(pi*xmag))**2)!-----------------------if change in phase not small enough yetCONSTANT epdg = 0.1IF(ABS(pdgn - pdgp) .GT. epdg) GO TO skip1!-----------------------ignore results until after settling timeIF(t .LT. tsettl) GO TO skip1!-----------------------terminate on frequency sweepTERMT(w .LE. wmn, 'Frequency Limit')!-----------------------save value in separate name for plotting

INITIALpdg = 0.0gdb = 0.0wfr = wmx ! put first point at far right edge

END ! of initialpdg = pdgngdb = gdbnwfr = w!-----------------------advance frequency geometrically

INITIAL; w = wmx; ENDw = MAX(wmn, kw*w) ; CONSTANT kw = 0.8!-----------------------calculate new phase for continuity! of forcing function at new frequency

INITIAL; fi = 0.0; ENDfi = fi + t*(wfr - w)!-----------------------ensure previous phase set to force at! least two cyclespdgn = rmx!-----------------------force a data logging actionCALL LOGD(.FALSE.)

skip1..CONTINUE

Figure A9-1. Phase and gain program (part 1)

A9. Phase and Gain A. ACSL Example Programs


The model is defined by the transfer operator, TRAN, and numerator and denominatorpolynomials. The numerator coefficients (A) are 0.5 and 1.0; the denominatorcoefficients (B) are 0.03, 0.1, and 1.0. In addition, a maximum step size (MAXTXZ)of 0.050 sec is chosen (conservatively) from the plant roots of (-1.5± j6) and aminimum divisor (NSTPMN) of the period. This indicates that no matter how slow thedrive sine wave is, the calculation interval (MAXTC) will be no greater thanPERIOD/NSTPMN; as the frequency gets slower and slower, the step size does notrise above MAXTXZ. MAXTC is calculated in the DISCRETE section as follows:

maxtc = MIN(period/nstpmn, maxtxz)

The output (Y) of the plant is obtained using the TRAN (general polynomial transferfunction) operator. TRAN takes arguments of the order of the numerator anddenominator, arrays of coefficients for the numerator and denominator, and the input.In this program, the plant output is expressed as follows:

y = TRAN(1, 2, a, b, x)

The in-phase (P) and quadrature (Q) components of the output are obtained bymultiplying the output (Y) by sin(W*T + FI) and cos(W*T + FI) respectively andintegrating.

!-----------------------reset previous phase for next timeINITIAL; pdgp = rmx; END

pdgp = pdgn!-----------------------recalculate new period and step sizeperiod = 2.0*pi/wmaxtc = MIN(period/nstpmn, maxtxz)!-----------------------terminate on time limitTERMT(t .GT. tstp, 'Time Limit') ; CONSTANT tstp = 10000.0

END ! of discrete

DERIVATIVE continue

MAXTERVAL maxtc = 0.010CONSTANT wmn = 1.0 , wmx = 100.0CONSTANT xmag = 1.0 , tsettl = 2.0

x = xmag*SIN(w*t + fi)

!-----------------------define modelREAL a(2), b(3)CONSTANT a = 0.5, 1.0 , b = 0.03, 0.1, 1.0CONSTANT maxtxz = 0.050 , nstpmn = 10.0y = TRAN(1, 2, a, b, x)!-----------------------integrate for in-phase and quadrature compp = INTEG(y*SIN(w*t + fi), 0.0)q = INTEG(y*COS(w*t + fi), 0.0)

END ! of continuous section

END ! of program

Figure A9-1. Phase and gain program (part 2)



The difference in the in-phase and quadrature components since the previous cycle arecalculated at the beginning of the DISCRETE section as follows:

dlp = p - ppdlq = q - qp

Since PP and QP are initialized to large numbers, DLP and DLQ are large the firsttime through.

PARAMETER statements set constants to be substituted at various points in theprogram. The variable names do not appear in the program dictionary and the valuescannot be changed at runtime. The constantπ (PI) and conversion factorradians perdegree(RADDEG) are conveniently set in a PARAMETER statement, as are a verysmall (RMN) and a very large (RMX) number. RMX is used in logic for ignoring thefirst cycle calculations, as described below. RMN is added to terms in severalequations to prevent the terms becoming zero (to avoid division by zero or a zeroargument to a logarithm function, for example).

The minimum and maximum frequencies for the frequency sweep (WMN and WMX)however are set in CONSTANT statements so that they can be changed at runtime.

The program contains three termination (TERMT) statements. Each statement uses theoptional second argument, a character string in quotes, to generate a message when itis activated. This message thus indicates which of the possible terminating conditionsactually stopped the program. The three terminating conditions in this program arerelative change too small for machine accuracy, frequency limit, and time limit.

The first termination condition checks for a frequency such that the attenuation is toogreat for the machine precision. For 32 bit computers, the error criterion (EPM) shouldprobably be set to 0.0001, which still allows room for nearly 80 dB attenuation. If thechange from cycle to cycle in P and Q is less than the machine precision, theincrements are zero and the logarithm function fails further on when calculating thegain (GDBN).

The second termination condition is a normal termination on the frequency sweepbeing completed. This is the condition that usually stops the run.

The third termination condition is a backup of a time limit. This condition could be setat runtime to a small number for an initial checkout run, for example.

Once the increments have been calculated, the current values of P and Q are saved tobecome the previous values (PP and QP) during the next pass. The phase and gainover the preceding cycle are calculated from:

phase = ATAN[ ∆Q/ ∆P]

gain = 10.0*LOG10[( ∆P2 + ∆Q2)(w/ π) 2]

If the new phase differs from the previous phase by more than a specified amount(nominally 0.1 degrees), then no data is saved. Similarly, if a settling time (TSETTL)has not elapsed, another cycle is calculated. If both these tests have been passed, thenthe phase, gain, and frequency are transferred to separately named variables (PDG,GDB, and WFR) which are used for plotting.

The forcing function frequency (W) is decreased geometrically and the phase (FI)adjusted to ensure a shorter settling time between frequency changes. The previousphase measured is again set to a large number (RMX) so that the integration over thefirst cycle will be rejected.



The final step at the end of each frequency calculation is to call the data loggingroutine, LOGD, to force data logging. The communication interval (CINT) is set to 1.0at the beginning of the program with the intent that this will produce no output beyondthe first one at time zero. All other output is obtained by means of LOGD, which iscalled when the data for a new frequency point is being recorded.

All cases then proceed through the code after the label SKIP1. The previous phase(PDGP) is set equal to the current phase (PDGN), and PERIOD and a new step sizefor the continuous section are calculated. These last two calculations need to be doneonly when the frequency changes, but they are placed here in order to handle theinitialization problem rather than repeat the code in the INITIAL section.

Figure A9-2 shows the log file of a runtime session. Note that the frequency multiplierKW was changed to 0.9 from the nominal 0.8 in order to increase the point density to23 per decade for smoother plots. The plot, shown in Figure A9-3, uses a logarithmicscale on the X axis. A minimum for the logarithmic scale is specified symbolically byusing the contents of WMN as follows:

PLOT/XLOG/XLO=wmn, pdg,gdb

This plot was made in one simulation run with a sweep of the drive frequency.Examination of the last value of time showed that it needed 221 seconds of simulatedtime to complete the sweep, which explains why it is usually considered an expensivepicture to obtain. Individual transient studies would be over in three or four seconds,whereas this run needs effectively sixty transient runs.

From an independent run with a listing of time (T) along with the frequency, phase,and gain, it can be shown that the high frequency points can be obtained quickly. Infact, it takes 35 seconds to sweep the frequency from 100 down to 10 radian/secondand a further 186 seconds to go from 10 down to 1 radian/second. The reason for this

ACSL Runtime Exec Version 6 Level 10B 3-MAR-91 10:49:28 Page 1

SET TITLE='Phase and Gain of a Transfer Function'SPAREAccumulated cp time 10.94000. Elapsed cp time 0.SET TCWPRN=72 ! Force output width to fit on pageOUTPUT wfr,gdb,pdg/NCIOUT=1000PREPARE wfr,gdb,pdg,t,dlp,dlqSET kw=0.9 ! Change geometric frequency multiplierSTART

WFR 100.000000 GDB 0. PDG 0.Frequency Limit

WFR 1.00000000 GDB 1.18776000 PDG 20.6806000PLOT/XLOG/XLO=wmn & ! Logarithmic plots with nonzero start

,pdg/CHARACTER=' ' & ! Phase and make character plotted blank& ! since problem is first point which is& ! incorrect so shouldn-t be emphasised.

,gdb/CHARACTER=' ' ! Gain, same blank characterDrawing plot number 1DISPLAY t

T 221.287000SPARE ! List execution timeAccumulated cp time 29.04000. Elapsed cp time 18.10000QUIT

Figure A9-2. Phase and gain log file



is that at least one cycle must be completed at each frequency, and at 1 radian/secondeach measurement requires over six seconds.

One caveat for this type of program is in regard to errors caused by non-steady-stateoperating conditions. At low attenuations, the drive signal dominates in the P and Qintegrators, but when the plant attenuation becomes high, the residual motion excitedby the start up transient or frequency switch can become important. An idea of themagnitude of the effect can be obtained by looking at the irregularity in the phase plotwhen the frequency is over 20 radians/second. The plot should theoretically be smoothand monotonically negative as the phase asymptotically approaches -90 degrees. InFigure A9-3, the phase at 72.9 radians/second is given as -87.8 degrees, but at the nextfrequency point of 65.6 it has gone back to -89.3. This change of 1.5 degrees in thewrong direction must be an artifact of the measurement implementation.

An empirical study of this phenomenon determined that better results are obtainedwith more heavily damped systems (shorter settling times) and certainly when theattenuation is relatively small. If problems occur, experimentation with the phasechange error parameter (EPDG) can help; another approach is to add a fixed settlingtime after each frequency change so that the system has time to reach steady statebefore the measurement is taken.

As a test of accuracy, the theoretical gain and phase was evaluated at five selectedfrequency points; the comparison is listed in Table A9-1. Note the phase error of half adegree at high frequencies. A second run was made with the allowable phase errorEPDG changed to 0.01 (from 0.1). This forced slightly longer settling times so that theoverall sweep time was 270 seconds (up from 221 seconds) and the measured phase ata frequency of 90 rad/s was now -89.07 degrees (theoretical is -89.14 degrees). Theincreased settling time was seen in the measurement at W = 100, for example, beingavailable at 2.51 sec (compared with 2.01) and the measurement at W = 90 beingproduced at 3.84 seconds (compared with 2.29). At lower frequencies, the tighterconstraint had little effect since settling has occurred within the first cycle anyway.

Figure A9-3. Nonlinear phase and gain plot



The example above shows how to generate phase and gain plots for a nonlinear plant,but the ANALYZE command is the most cost-effective way to evaluate a plant thatcan be linearized. Figure A9-4 shows a program which is the previous program withall the measurement code removed. This version is simply the transfer function withinput X+DLX and output Y.

The input to this version of the model is given as X+DLX since in most real systemsthe input comes from somewhere else and so must be calculated. Potential controlinputs must be free;i.e., only defined in CONSTANT statements (usually to zero). Inthis case, we can use the variable DLX.

Table A9-1. Comparison of measured and theoretical gain and phase

frequency measured theoretical measured theoreticalW gain gain phase phase

(rad/s) (dB) (dB) (deg) (deg)

90.00 -14.612 -14.617 -88.64 -89.1431.38 -5.230 -5.232 -87.47 -87.3710.94 5.916 5.920 -77.48 -77.47

3.09 7.484 7.484 33.67 33.671.00 1.188 1.188 20.68 20.68

PROGRAM phase and gain

!-----------------------compute phase and gain of a given! transfer function. This model uses the model linearization! features of ACSL to obtain a Bode plot from input (control)! x to observable y.

CINTERVAL cint = 1.0NSTEPS nstp = 1

DERIVATIVE continue

MAXTERVAL maxtc = 0.010

!-----------------------define modelREAL a(2), b(3)CONSTANT a = 0.5, 1.0 , b = 0.03, 0.1, 1.0CONSTANT x = 0 , dlx = 0y = TRAN(1, 2, a, b, x + dlx)


END ! of program

Figure A9-4. Linear phase and gain program



Runtime commands for this model, shown in Figure A9-5, define the control andobservable variables by:

ANALYZE/CONTROL=dlx/OBSERVE=y

The frequency sweep is by radians (not the default HERTZ). The frequency minimumstarts at the default of 1.0, but the frequency maximum is set as follows:

ANALYZE/HERTZ=.F./FREQMX=100

Finally, the Bode plot is generated, as shown in Figure A9-6, by:

ANALYZE/BODE

Note that the phase curve is smooth and monotonically negative at the higherfrequencies (i.e., W > 10).


set title='Linear Model for Frequency Response'ANALYZE/CONTROL=dlx/OBSERV=yStates not initialized. Moving IC vector to STATE vectorANALYZE/HERTZ=.F./FREQMN=1/FREQMX=100ANALYZE/BODENumber of poles is 2 - Number of zeros is 1Drawing plot number 1

Figure A9-5. Log file for linear phase and gain

Figure A9-6. Bode plot of linear phase and gain program



10. MissileAirframe

The missile example demonstrates the use of vector operators and vector integration,the use of double precision, the incorporation of FORTRAN subroutines, and the useof FORTRAN library routines.

The program is a six degree-of-freedom model of an unguided ground-to-air missilewith transient responses to control surface deflections. For a full missile system, atarget, target sensor or seeker, guidance law, and autopilot would have to be added andthe aerodynamic and motor models expanded.

Each three-dimensional axis system (or reference frame) is given a letter;i.e., E forearth (or inertial reference) and M for missile. (More frames would be added if target,seeker, or other subsystems were modeled.) The axes (commonly referred to as X, Y,and Z) for this model are numbered 1, 2, and 3 to facilitate using vector operators.

There are several possible systems of axis orientation. In this model, the second (Y)axis points up, as is found commonly in models of ground launched missiles (such asHawk, Patriot). The other major school of thought orients the axes with the third (Z)axis pointing down; this orientation is often used by engineers with a background inairplane design. Models can use any system of axes, but all frames should be parallelwhen the orientation angles are zero.

The earth (E) frame orients the E1 axis horizontal and downrange, E2 vertical up, andE3 crossrange horizontal to the right, to form a right hand set. The origin of the frameis normally on the ground, but since this model does not compensate the atmosphericdensity table look-up for ground altitude, the origin is assumed to be at sea level. Allvelocity and range vectors are assumed to be components in this frame unlessexplicitly specified otherwise.

The missile frame (shown in Figures A10-1 and A10-2) comprises M1 out of the nosealong the center line, M2 along fin one (normally viewed vertically or up), and M3 outto the right along fin two. (The designationdownin the figures actually meansinto thepaperrather than physically down.) Variables in the missile frame have a suffix of M.

The reference frames are related to each other through Euler angles:ψ (yaw),θ(pitch), andϕ (roll). The sequence of rotations starting at the ground reference or Eframe isψM (SIM) to the left about E2,θM (THM) up about the new three axis E3', andfinally ϕM (FIM) clockwise about the new one axis which should now be M1 to alignthe two and three axes with M2 and M3. The control fin deflections are shown inFigure A10-1 in their positive sense;i.e., trailing edge right for fins one and three,trailing edge down for fins two and four.

Units in the model are in the English system;i.e., slug, foot, and second for units ofmass, length, and time, respectively. Angles are in radians.

It is important that all units be consistent and fundamental since many simulationerrors can be traced to unit misconceptions, either in the equations or in the constantvalues. It is strongly recommended that non-basic units such as degrees or gees not beused in the equations (use radians for angles and ft/s2 or m/s2 for acceleration).Variables can be converted into auxiliary units in the DYNAMIC section for output.

The ACSL program is listed in Figure A10-3. Figure A10-4 lists a FORTRANsubroutine called from the ACSL program.

The missile program is distributed in two versions — single precision and doubleprecision. The version shown here is double precision;i.e., in a form to be used with

A. ACSL Example Programs A10. Missile Airframe


the global double precision translation mode. Double precision translation mode isspecified when calling ACSL from the computer operating system and so depends onthe computer system. See the documentACSL Sim User's Guidefor more information.For VAX systems, for example, a switch specifies double precision as follows:

ACSL/DOUBLE_PRECISION misdbl

For Unix systems, -x stands forextended precision:

acsl -x msldbl

The translator handles floating point variables as either single or double precision(depending on the mode requested) unless REAL or DOUBLEPRECISION isspecified. In general, vectors and arrays should be dimensioned with DIMENSION

Figure A10-1. Missile (M) frame and fin deflection direction

Figure A10-2. Missile (M) frame with pitch angle-of-attack

A10. Missile Airframe A. ACSL Example Programs


PROGRAM - missile airframe model

!-----------------------a generic missile airframe model is! developed using vectors for all three dimensional quantities.! this model will respond to fin deflections so representing the! open loop airframe response and needs a seeker, autopilot,! actuator, motor and target module in order to evaluate guidance! effectiveness

DYNAMICCINTERVAL cint = 0.020ALGORITHM ialg = 4MAXTERVAL maxt = 0.010NSTEPS nstp = 1

DERIVATIVE

!-----------------------environment module

!-----------------------velocity of sound - function of altitudeTABLE vsf, 1, 10 &

/ 0.0 , 1.0e4 , 2.0e4 , 3.0e4 , 4.0e4 &, 5.0e4 , 6.0e4 , 7.0e4 , 8.0e4 , 9.0e4 &, 1186.5 , 1077.4 , 1036.4 , 994.8 , 968.1 &, 968.1 , 968.1 , 970.9 , 977.6 , 984.3 /

vs = vsf(rm(2))!-----------------------log of atmospheric densityTABLE lro, 1, 10 &

/ 0.0 , 1.0e4 , 2.0e4 , 3.0e4 , 4.0e4 &, 5.0e4 , 6.0e4 , 7.0e4 , 8.0e4 , 9.0e4 &,-6.04191 ,-6.34502 ,-6.67084 ,-7.02346 ,-7.43995 &,-7.91851 ,-8.39664 ,-8.87953 ,-9.36448 ,-9.87239/

!-----------------------calculate actual atmospheric densityro = EXP(lro(rm(2)))

!-----------------------missile airframe module

!-----------------------define elements of stability derivative! matrix. linear aerodata is assumed for simplicity in subroutine! coeff. non-linear aerodata may be incorporated by rewriting! this subroutineCOMMON/stabd/ a(30)CONSTANT a = &

0.148 , 0.0 , 0.0 , 0.0 , 0.0 , 0.0 &, 0.0 ,-0.26 , 0.0 , 0.0 , 0.0 ,-0.286 &, 0.0 , 0.0 ,-0.26 , 0.0 , 0.286 , 0.0 &, 0.0 , 0.528 , 0.0 , 0.0 , 0.0 , 2.0 &, 0.0 , 0.0 , 0.528 , 0.0 ,-2.0 , 0.0

!-----------------------magnitude of missile velocityREAL dotmvm = SQRT(dot(vm, vm))!-----------------------make *me* matrix from orientation anglesDOUBLEPRECISION me(9)CALL mmk(me = fim, 1, thm, 3, sim, 2)!-----------------------rotate velocity to missile frameDOUBLEPRECISION vmm(3)CALL vecrot(vmm = vm, me)!-----------------------lateral and vertical angles of attackal2 = ATAN(-vmm(3)/vmm(1))al3 = ATAN( vmm(2)/vmm(1))

Figure A10-3. Missile airframe program (part 1)



!-----------------------mach number and dynamic pressuremach = mvm/vsq = 0.5*ro*mvm**2!-----------------------fin deflectionsDOUBLEPRECISION dl(4)CONSTANT dl = 4*0.0!-----------------------missile dimensional constantsCONSTANT b = 3.95 , cbar = 5.62CONSTANT s = 13.9!-----------------------roll damping - function of mach numberTABLE clp, 1, 5 &

/ 0.0 , 0.8 , 1.0 , 1.2 , 2.0 &,-0.21 ,-0.21 ,-0.20 ,-0.19 ,-0.18 /

!-----------------------pitch damping - function of mach numberTABLE cmq, 1, 5 &

/ 0.0 , 0.8 , 1.0 , 1.2 , 2.0 &,-3.8 ,-2.0 ,-1.5 ,-2.0 ,-2.1 /

!-----------------------calculate damping derivativesPROCEDURAL(cd = mvm, mach, wm)

DIMENSION cd(3)cd(1) = 0.5*clp(mach)*b*wm(1)/mvmccvv = 0.5*cmq(mach)*cbar/mvmcd(2) = ccvv*wm(2)cd(3) = ccvv*wm(3)

END ! of procedural!-----------------------get moments and force aero coefficients! and correct lateral moments for shift in center of gravity! position

PROCEDURAL(c = al2, al3, dl, mach, dxcg)DOUBLEPRECISION c(6)CALL coeff(c = al2, al3, dl, mach)CONSTANT dxref = 9.60c(2) = c(2) - (dxcg - dxref)*c(6)/cbarc(3) = c(3) + (dxcg - dxref)*c(5)/cbar

END ! of procedural!-----------------------aerodynamic acceleration

PROCEDURAL(nm = q, c, mass, thrust)DOUBLEPRECISION nm(3)nm(1) =(q*s*c(4) + thrust)/massnm(2) = q*s*c(5)/massnm(3) = q*s*c(6)/mass

END ! of procedural!-----------------------rotation rate derivatives

PROCEDURAL(wmd = q, c, cd, wm, ixx, iyy)wmd(1) = q*s*b*(c(1) + cd(1))/ixxwmd(2) = q*s*cbar*(c(2) + cd(2))/iyy + wm(1)*wm(3)wmd(3) = q*s*cbar*(c(3) + cd(3))/iyy - wm(1)*wm(2)

END ! of procedural!-----------------------rotate acceleration vector to earth frameDOUBLEPRECISION nme(3)CALL invrot(nme = nm, me)!-----------------------calculate velocity derivatives in the! earth frame - needs gravity adding in

PROCEDURAL(vmd = nme)vmd(1) = nme(1)vmd(2) = nme(2) - g ; CONSTANT g = 32.2vmd(3) = nme(3)

END ! of procedural!-----------------------yaw angle derivativesimd = (wm(2)*COS(fim) - wm(3)*SIN(fim))/COS(thm)




statements so that either mode can be used without editing the program. The ACSLmacro library, for example, contains two versions of most macros and uses theappropriate version for the global precision in effect.

Many calls to subroutines need to have the precision specified. In the missile program,the DOT function always returns a single precision result and so has to be defined by aREAL statement. The subroutines from the geometrical subroutine library handleeither, depending on how the variables are defined. When considering the precision ofvariables, check particularly any calls to subroutines.

The program controls are specified at the beginning of the DYNAMIC section. Thesesystem variables (communication interval, integration algorithm, maximum

!-----------------------integrate for all euler angles - note use! of vector integrator for single elementCONSTANT simic = 0.0 , thmic = 0.0 , fimic = 0.0sim = INTVC(simd, simic)thm = INTEG(wm(2)*SIN(fim) + wm(3)*COS(fim), thmic)fim = INTEG(wm(1) - simd*SIN(thm), fimic)!-----------------------vector integrate for rotational velocityDIMENSION wm(3), wmd(3), wmic(3)wm = INTVC(wmd, wmic) ; CONSTANT wmic = 3*0.0!-----------------------translational velocityDIMENSION vm(3), vmd(3), vmic(3)vm = INTVC(vmd, vmic) ; CONSTANT vmic = 2154.8, 2*0.0!-----------------------translational position - note the deriv-! ative vector cannot be a state vector (velocity) as wellDIMENSION rm(3), rmd(3), rmic(3)CALL XFERBR(rmd = vm, 3)rm = INTVC(rmd, rmic) ; CONSTANT rmic = 0.0, 10000.0, 0.0

!-----------------------motor module

!-----------------------simple version with zero thrust specifying! a burnt or glide conditionCONSTANT thrust = 0.0 , mass = 8.77CONSTANT ixx = 8.77 , iyy = 361.8CONSTANT dxcg = 10.2

END ! of derivative

!-----------------------stop on elapsed timeCONSTANT tstp = 1.99TERMT(t .GE. tstp, 'Time Limit')

END ! of dynamic

TERMINAL!-----------------------set up in case dictionary desiredLOGICAL dictionaryCONSTANT dictionary = .false.IF(dictionary) CALL LISTD(11)





integration step size, and number of integration steps per communcation interval) andtheir default names and values are listed in Chapter 1. Each variable is also explainedin greater detail in Chapter 4. The second order Runge-Kutta integration algorithm ischosen. Setting NSTP to 1 and using MAXT to control the integration step size isrecommended for most models.

The DERIVATIVE section is split up into logically connected code sequences ormodules (e.g., environment, airframe, motor). Modules help in documenting thesimulation and in checking out individual code sequences, since they can be removedand assigned to various team members for verification. Since the ACSL translatorsorts the code, you do not have to be concerned with the order of statements forcomputation. You can also use INCLUDE statements (see Chapter 4) to bring variousmodules into a complex model such as this.

The environment model comprises tables for the velocity of sound (for Mach numbercalculation) and air density (for dynamic pressure calculation) as a function of altitude.

SUBROUTINE coeff(al2, al3, dl, mach, c)c-----------------------------computes six aerodynamic coefficients -c three moments, c(1), c(2) and c(3), and three forces, c(4), c(5)c and c(6). moments are about axes centred at the reference pointc and must be corrected for centre of gravity shift.cc inputscc al2 angle of attack about *m2* - positive wind from leftc al3 angle of attack about *m3* - positive wind from abovec dl array of four fin deflectionsc mach mach number (real)cc outputscc c array of six aerodynamic coefficientscc-@@--------------------------double/single

DOUBLEPRECISION dl(4), c(6), al2, al3, machcc-----------------------------separate user common (real)

COMMON/stabd/ a(6,5)cc-----------------------------compute equivalent control surface defl-c ections from the four surface angles

dla = 0.25*(dl(3) + dl(4) - dl(1) - dl(2))dly = 0.50*(dl(1) + dl(3))dlz = 0.50*(dl(2) + dl(4))

c-----------------------------compute each moment assuming it is linearc in each of the arguments

DO 110 j = 1, 6c(j) = a(j,1)*dla + a(j,2)*dly + a(j,3)*dlz + a(j,4)*al2

. + a(j,5)*al3110 CONTINUE

RETURNc

END

Figure A10-4. Subroutine called from missile program



The missile airframe module is the largest in the program. It begins with a definitionof common block STABD (stability derivative). The common block also appears insubroutine COEFF, which is called later in the module, where aerodynamiccoefficients are determined. User common blocks allow sharing variables withoutnaming them as arguments in the call.

The FORTRAN subroutine COEFF is appended to the end of the ACSL program. Thefirst line of the subroutine comes immediately after the ACSL program ENDstatement, with no intervening comments or blank lines. Subroutines appended to anACSL program are transferred by the translator directly to the beginning of theFORTRAN compile file. The translator does not check the subroutine for errors; thatis done by the FORTRAN compiler.

Subroutines can also be accessed from libraries. Several subroutines from a library ofthree-dimensional geometric subroutines (available from Mitchell & GauthierAssociates) are called to handle functions such as generating a direction cosine matrixand rotating vectors using the direction cosine matrix. Libraries are made available byspecifying them in the call to ACSL from the operating system and so depends on thecomputer system. See the documentACSL Sim User's Guidefor more information.

Matrix A contains the stability derivative coefficients that determine the aerodynamiccharacteristics. The COMMON statement in the ACSL program establishes the matrixas having 30 elements; the COMMON statement in the COEFF subroutine dimensionsthe matrix to be 6 by 5. A CONSTANT statement in the ACSL program fills in thestability derivative values.

VM, the three-component vector for velocity in the E frame, and DOT, an external(library) function for finding a dot product, are used to calculate the magnitude of themissile velocity as follows:

mvm = SQRT(DOT(vm, vm))

The next step is to form the direction cosine matrix ME, which is a three by threematrix for transforming vectors expressed in the E frame to components in the Mframe. The direction cosine matrix is calculated from the three anglesψM, θM, andϕM.Subroutine MMK (matrix make) from the geometrical subroutine library creates thematrix, which transforms vectors between two axis systems connected by a rotation Aabout the NA axis, rotation B about the NB axis, and rotation C about the NC axis.The general FORTRAN call to this routine is as follows::

CALL mmk(a, na, b, nb, c, nc, m)

The ACSL call is expressed as follows:

CALL mmk(me = fim, 1, thm, 3, sim, 2)

Using the equal sign rather than a comma after the first argument tells the ACSL sorterthat ME is an output of the routine. The translator, in producing the FORTRAN code,changes the order of the arguments so that the outputs are on the right and MEcoincides with M of the previous call.

The direction cosine matrix is then used to obtain components of the missile velocityvector in the M frame from:

VM(M) = [ME] VM(E)

The subroutine VECROT (vector rotation) does this rotation and is called in theprogram as follows:



CALL vecrot(vmm = vm, me)

where again the order of the arguments is inverted by the translator so that the actualFORTRAN call is:

CALL vecrot(vm, me, vmm)

A corresponding subroutine INVROT (inverse rotation), used later in the program,inverts a vector (NM, for example) from the M frame into the E frame:

NME = [ME]−1 NM

with code in the form:

CALL invrot(nme = nm, me)

Lateral and vertical angles-of-attack are calculated next. The lateral angle-of-attackα2(AL2) is the angle between M1 and the projection of the velocity vector on to theM1/M3 plane and is positive for a positive rotation from M1 to the wind vector aboutM2 (wind from left). Vertical angle-of-attackα3 (AL3) is the angle between M1 andthe projection of the velocity vector on the M1/M2 plane and is positive for a positiverotation from M1 to the wind vector about M3 (wind from above). See Figure A10-2.The angle-of-attack equations are expressed (in radians) in terms of the missilevelocity vector components as follows:

α2 = tan−1

−VM(M3)

VM(M1)

α3 = tan−1

VM(M2)

VM(M1)

Atmospheric densityρ (RO, with units of slug/ft3), is taken from table LRO (log ofρ)in the environment module. Using the log function for the density reduces the dynamicrange of the function, making the straight line interpolation over 10 kft incrementsmore accurate. Air density is a function of height, which is the component of themissile range along E2 (i.e., RM(2)):

ρ = EXP[LRO(RM(2))]

Dynamic pressure (in lb/ft2) is calculated from air density and the magnitude of themissile velocity (MVM in the program) as follows:

Q =ρV2

2

Mach number is calculated from the missile velocity and the velocity of sound (fromtable VSF in the environment model as a function of the missile's altitude) as follows:

MACH = VVSF(RM(2))

Dimensionless damping coefficients are obtained from normalized spin rates. Themissile spin rate is expressed as a three component vectorWM giving the rates ascomponents resolved along the M1, M2, and M3 axes. In conventional aerodynamicterminology, L, M, and N refer to roll, pitch, and yaw axes and P, Q, and R refer to theroll, pitch, and yaw rates. In the model, the rates are namedWM(1), WM(2), and



WM(3) so that vector operations are convenient. The characteristic span isb and thereference chord isc

_. With Clp

andCmqtaken from tables as a function of Mach number,

the damping coefficient components (CD) of the total moment coefficients are nowcalculated as follows:

CD(1) = Clp(MACH) ∗ pb ⁄ 2V

CD(2) = Cmq(MACH) ∗ qc ⁄ 2V

CD(3) = Cmq(MACH) ∗ rc ⁄ 2V

From the symmetry of the missile, the pitch and yaw damping derivatives are assumedto be identical, soCmq

is used in place of the usualCnrin the yaw direction, making a

third coefficient table unnecessary.

The translator objects if a variable name appears on the left side of more than oneequation, so the calculation of the various elements of arrays are placed inPROCEDURAL blocks. The list in the header informs the translator of the outputs(listed before the equal sign) and inputs (listed after the equal sign) so that it can placethe block appropriately during the sorting process.

The aerodynamic coefficients (three moment and three force) are calculated insubroutine COEFF. They are evaluated as functions of the two angles-of-attack (α2andα3), four fin deflections (δ1 throughδ4), and Mach number;i.e., seven variables inall. One of the objects of this example is to study the effect of various techniques inevaluating aerodynamic coefficients, from full nonlinear tables of data to simple linearstability derivatives. For the case shown, simple linear stability derivatives areembedded in the (A) matrix passed to the COEFF by means of the common blockSTABD. This (A) matrix is a five by six array with components:

A ≡

Clδa

Cmδa

Cnδa

Cxδa

Cyδa

Czδa

Clδy

Cmδy

Cnδy

Cxδy

Cyδy

Czδy

Clδz

Cmδz

Cnδz

Cxδz

Cyδz

Czδz

Clα2

Cmα2

Cnα2

Cxα2

Cyα2

Czα2

Clα3

Cmα3

Cnα3

Cxα3

Cyα3

Czα3

The effective roll, yaw, and pitch fin control deflections (δa, δy, andδz) are calculatedin the subroutine from the equations:

δa =− δ1 − δ2 + δ3 + δ4

4

δy =δ1 + δ3

2

δz =δ2 + δ4

2

The subroutine returns the six component vectorC having the following elements:



C(1) rolling moment coefficient, about M1C(2) moment coefficient about M2C(3) moment coefficient about M3C(4) force coefficient along M1C(5) force coefficient along M2C(6) force coefficient along M3

Aerodynamic accelerationN(M) is the acceleration produced by aerodynamic forces; itexludes gravity (which is introduced in the equations for translational acceleration)and is the quantity which is read by any on-board accelerometers. The component inthe forward direction includes the thrust of the propulsion system.

N(M1) = (qsCx + THRUST) ⁄ MASS

N(M2) = qsCy ⁄ MASS

N(M3) = qsCz ⁄ MASS

The rotational accelerations have gyroscopic terms in the equations when applied to anormal spinning rigid body. The equations of motion of a conventional aircraft havethe following form (neglectingIxz):

Ixp.

= QsbCl + (Iy − Iz) qrIyq

.= Qsc

_Cm + (Iz − Ix) rp

However, for an axisymmetrical missile, the lateral moments of inertia are equal;i.e.,

Iz = Iy

In addition, the long thin shape assures that the roll moment of inertia is small;i.e.,

Ix << Iy

The equations for missile rotational acceleration can thus be expressed:

Ixp.

= Qsb[Cl + Clp(pb ⁄ 2V) ]

Iyq.

= Qsc_

[Cm + Cmq(qc_

⁄ 2V) ] + Iypr

Iyr.

= Qsc_

[Cn + Cmq(rc_

⁄ 2V) ] − Iypq

The aerodynamic accelerations are rotated from the missile frame (M) to the earthframe (E) using the inverse rotation subroutine INVROT. The transformation can beexpressed mathematically as follows:

NM(E) = [ME]−1 NM

(M)

With the aerodynamic acceleration in the inertial frame, gravity (g) is added to gettranslational acceleration (i.e., the velocity derivative). This is the preferred referenceframe for integrating the translational states.

VM. (E1) = NM

(E1)

VM. (E2) = NM

(E2) − g

VM. (E3) = NM

(E3)

The angular rate derivativeψ.

M is obtained from the standard gimbal equation by:



ψ.

M =q cosϕM − r sin ϕM

cosθM

The three rotational angles are obtained by integrating their respective rates:

ψM = INTVC(ψ.

M, ψMIC)

θM = INTEG(q sin ϕM + r cosϕM, θMIC)

ϕM = INTEG(p − ψ.

M sin θM, ϕMIC)

The INTVC operator requires the derivative to be given as a variable name, whichsaves an assignment statement in translation. INTEG is used when the derivative is anexpression or a state. The translator then generates a name (in the form Z0nnnn) forthe derivative. In this example, the INTEG operator is used forθM andϕM, saving twoassignment statements in the model code; however,ψ

.M is calculated separately so that

it can be part of the expression for the derivative ofϕM and thus the INTVC operatorcan be used forψM.

The vectors for missile angular spin and the translational velocity are integrated fromthe respective accelerations by the two statements:

wm = INTVC(wmd, wmic)vm = INTVC(vmd, vmic)

The next step is to integrate translational velocity to range. We cannot use the nameVM for the derivative of RM since the same name cannot be both a state and aderivative. The reason is that such a duplication causes a conflict in storage in the statetable assignment. So the three elements of VM are first transferred by the XFERBR(transfer block) utility to a range derivative vector (RMD), and then RMD is integratedwith the vector integrator.

CALL XFERBR(rmd = vm, 3)rm = INTVC(rmd, rmic)

The last section of the program describes the motor module with zero thrust andconstant mass and inertias. For a real system, the motor model would compute thrustas a function of time from motor ignition. It would also vary mass, inertia, and centerof gravity position, all of which significantly affect flight characteristics.

Figure A10-5 is the log file of a runtime session. The TITLE is set, the printout islimited to an 80-column width, and a PREPARE list is defined. Fin deflections of-0.01 radians are specified for fins two and four, which results in motion in the verticalplane;i.e., the missile nose tends to go up. The run is executed with the STARTcommand.

The messageTime Limitis generated by the optional comment argument of theTERMT operator in the program. It indicates that the run terminated on T (time)becoming greater than the value of constant TSTP.

Figure A10-6 shows a strip plot of several model variables. To generate this plot, thestrip plot option (STRPLT) is set true, the default line plot option (CALPLT) is turnedoff, and the plot scale factor (PSFSPL) is set. The X axis (XINSPL) is set longer thanthe default and the grid set further apart (XTISPL). The PLOT command thengenerates the plot, with the named variables appearing from the bottom up.

PRINT/ALL generates a columnar list of the values, over the course of the run, of allthe variables listed in the PREPARE command. Specifying NCIPRN reduces thenumber of lines printed;i.e., only every fifth line is printed in this case.




SET TITLE='Missile Longitudinal Dynamics'SPAREAccumulated cp time 18.72000. Elapsed cp time 0.SET PCWPRN=80 ! Force narrow printoutPREPARE t,nm,wm,al2,al3,vm,sim,thm,fim,mach,qSET dl(2)=-0.01,dl(4)=-0.01,TITLE(41)='Step in Fin',' Nominal CG'STARTTime LimitSET STRPLT=.T.,CALPLT=.F.,PSFSPL=0.5,XINSPL=10.0,XTISPL=2.0PLOT nm(2),wm(3),al3,vm(2),thmDrawing plot number 1PRINT/NCIPRN=5/ALL

Line T NM(1) NM(2) NM(3) WM(1) WM(2)0 0. 0. -18.4739000 0. 0. 0.5 0.10000000 0. 75.7595000 0. 0. 0.

10 0.20000000 0. 112.717000 0. 0. 0.15 0.30000000 0. 68.1165000 0. 0. 0.20 0.40000000 0. 57.5482000 0. 0. 0.25 0.50000000 0. 77.8265000 0. 0. 0.30 0.60000000 0. 79.9538000 0. 0. 0.35 0.70000000 0. 71.0253000 0. 0. 0.40 0.80000000 0. 71.1397000 0. 0. 0.45 0.90000000 0. 74.9205000 0. 0. 0.50 1.00000000 0. 74.4090000 0. 0. 0.55 1.10000000 0. 72.8277000 0. 0. 0.60 1.20000000 0. 73.2024000 0. 0. 0.65 1.30000000 0. 73.8059000 0. 0. 0.70 1.40000000 0. 73.5450000 0. 0. 0.75 1.50000000 0. 73.2836000 0. 0. 0.80 1.60000000 0. 73.3898000 0. 0. 0.85 1.70000000 0. 73.4521000 0. 0. 0.90 1.80000000 0. 73.3600000 0. 0. 0.95 1.90000000 0. 73.3023000 0. 0. 0.

100 2.00000000 0. 73.3046000 0. 0. 0.

Line WM(3) AL2 AL3 VM(1) VM(2) VM(3)0 0. 0. 0. 2154.80000 0. 0.5 0.09665400 0. -0.00729433 2154.79000 -0.92543800 0.

10 0.01834670 0. -0.01015610 2154.67000 6.38481000 0.15 -0.01375680 0. -0.00670389 2154.55000 12.3191000 0.20 0.02345740 0. -0.00588607 2154.48000 14.8958000 0.25 0.03280950 0. -0.00745698 2154.38000 18.4523000 0.30 0.01580990 0. -0.00762268 2154.24000 23.3268000 0.35 0.01379480 0. -0.00693207 2154.10000 27.6266000 0.40 0.02128740 0. -0.00694193 2153.96000 31.4283000 0.45 0.02126790 0. -0.00723605 2153.79000 35.5313000 0.50 0.01805950 0. -0.00719772 2153.60000 39.8092000 0.55 0.01843110 0. -0.00707651 2153.41000 43.9353000 0.60 0.01974970 0. -0.00710705 2153.20000 48.0009000 0.65 0.01942760 0. -0.00715547 2152.98000 52.1351000 0.70 0.01888920 0. -0.00713694 2152.74000 56.2835000 0.75 0.01907650 0. -0.00711848 2152.49000 60.3971000 0.80 0.01927220 0. -0.00712865 2152.22000 64.5044000 0.85 0.01915570 0. -0.00713552 2151.94000 68.6229000 0.90 0.01907050 0. -0.00713053 2151.65000 72.7381000 0.95 0.01911440 0. -0.00712830 2151.34000 76.8440000 0.

100 0.01912960 0. -0.00713084 2151.02000 80.9472000 0.

Figure A10-5. Missile example log file (part 1)



ACSL Runtime Exec Version 6 Level 10B 5-MAR-91 16:28:55 Page 2Missile Longitudinal Dynamics Step in Fin Nominal CG

Line SIM THM FIM MACH Q0 0. 0. 0. 2.00000000 4075.460005 0. 0.00686485 0. 1.99999000 4075.43000

10 0. 0.01311930 0. 1.99989000 4075.0000015 0. 0.01242150 0. 1.99981000 4074.5200020 0. 0.01279980 0. 1.99977000 4074.1300025 0. 0.01602180 0. 1.99972000 4073.6400030 0. 0.01845050 0. 1.99965000 4073.0100035 0. 0.01975650 0. 1.99958000 4072.3200040 0. 0.02153190 0. 1.99952000 4071.5800045 0. 0.02373160 0. 1.99945000 4070.7500050 0. 0.02568060 0. 1.99937000 4069.8300055 0. 0.02747630 0. 1.99930000 4068.8400060 0. 0.02939620 0. 1.99922000 4067.7800065 0. 0.03136610 0. 1.99914000 4066.6400070 0. 0.03327600 0. 1.99906000 4065.4100075 0. 0.03517030 0. 1.99897000 4064.1100080 0. 0.03709070 0. 1.99889000 4062.7400085 0. 0.03901350 0. 1.99880000 4061.2800090 0. 0.04092340 0. 1.99870000 4059.7500095 0. 0.04283220 0. 1.99861000 4058.14000

100 0. 0.04474510 0. 1.99851000 4056.46000ANALYZE/FREEZE=rm,vm,fim/TRIM/JACOBIAN/EIGENJacobian evaluated. Condition number is 0.37250500Row vector names

SIM 1 THM 2 WM(1) 3WM(2) 4 WM(3) 5

Column vector namesSIMD 1 Z09982 2 WMD(1) 3

WMD(2) 4 WMD(3) 5


1 0. 0. 0. 1.0000300 0.2 0. 0. 0. 0. 1.00000003 0. 0. -4.2094100 0. 0.4 -276.73200 0. 0. -2.4097800 0.5 0. -276.72600 0. 0. -2.4097800


1 -4.209410002 -1.20489000 +/-16.5914000 16.63510 0.0724314 -1.20489000 +/-16.5918000 16.63550 0.072429

REINITS tstp=0.0,NDBUG=1START

....Debug dump - System Variables. NDBUG is 1, block number 1T 0. ZZTICG 0. CINT 0.02000000

ZZIERR F ZZNBLK 1 ZZICON 1ZZSTFL F ZZFRFL T ZZICFL TZZRNFL T ZZJEFL F ZZNIST 12ZZNAST 0 IALG 4 NSTP 1

MAXT 0.01000000 MINT 1.0000D-09





State Variables Derivatives Initial ConditionsFIM 0. Z09981 0. FIMIC 0.

RM(1) 0. RMD(1) 2154.80000 RMIC(1) 0.RM(2) 10000.0000 RMD(2) 0. RMIC(2) 10000.0000RM(3) 0. RMD(3) 0. RMIC(3) 0.

SIM 0. SIMD 0. SIMIC 0.THM 0.00729676 Z09982 0. THMIC 0.00729676

VM(1) 2154.80000 VMD(1)-0.55302695 VMIC(1) 2154.80000VM(2) 0. VMD(2) 43.5894257 VMIC(2) 0.VM(3) 0. VMD(3) 0. VMIC(3) 0.WM(1) 0. WMD(1) 0. WMIC(1) 0.WM(2) 0. WMD(2) 0. WMIC(2) 0.WM(3) 0. WMD(3)-2.9816D-08 WMIC(3) 0.

Algebraic Variables

Common Block /ZZCOMU/DICTIONARY F ZZSEED 55555555

Common Block /ZZCOMP/AL2 0. AL3-0.00729676 B 3.95000000

C 0. 0. -3.3884D-110. 0.01173352 0.

CBAR 5.62000000 CCVV-0.00273854 CD 0.0. 0. CLP-0.21000000

-0.21000000 -0.20000000 -0.19000000-0.18000000 0. 0.80000000

1.00000000 1.20000000 2.00000000Z09989-0.21000000 -0.21000000 -0.20000000

-0.19000000 -0.18000000 Z09990 0.0.80000000 1.00000000 1.200000002.00000000 CMQ-3.80000000 -2.00000000

-1.50000000 -2.00000000 -2.100000000. 0.80000000 1.000000001.20000000 2.00000000 Z09987-3.80000000

-2.00000000 -1.50000000 -2.00000000-2.10000000 Z09988 0. 0.80000000

1.00000000 1.20000000 2.00000000DL 0. -0.01000000 0.

-0.01000000 DXCG 10.2000000 DXREF 9.60000000G 32.2000000 IXX 8.77000000 IYY 361.800000

LRO(20) 90000.0000 Z09993-6.04191000 -6.34502000-6.67084000 -7.02346000 -7.43995000-7.91851000 -8.39664000 -8.87953000-9.36448000 -9.87239000 Z09994 0.

10000.0000 20000.0000 30000.000040000.0000 50000.0000 60000.000070000.0000 80000.0000 90000.0000

MACH 2.00000005 MASS 8.77000000 ME 0.99997336-0.00729669 0. 0.00729669

0.99997336 0. 0.0. 1.00000000 MVM 2154.80005

NM 0. 75.7914451 0.NME-0.55302695 75.7894257 0.

Q 4075.46140 RO 0.00175547 S 13.9000000THRUST 0. TSTP 0. VMM 2154.74259

-15.7229152 0. VS 1077.40000





VSF(20) 90000.0000 Z09997 1186.50000 1077.400001036.40000 994.800000 968.100000968.100000 968.100000 970.900000977.600000 984.300000 Z09998 0.10000.0000 20000.0000 30000.000040000.0000 50000.0000 60000.000070000.0000 80000.0000 90000.0000

Z09983 0. Z09984-2.10000001 Z09985 0.Z09986-0.18000000 Z09991 0. Z09992-6.34502000Z09995 0. Z09996 1077.40000

Common Block /STABD/A(30) 0.

Time LimitANALYZE/CLEAR ! Release frozen statesANALYZE/JACOBIAN/EIGENRow vector names

FIM 1 RM(1) 2 RM(2) 3RM(3) 4 SIM 5 THM 6VM(1) 7 VM(2) 8 VM(3) 9WM(1) 10 WM(2) 11 WM(3) 12

Column vector namesZ09981 1 RMD(1) 2 RMD(2) 3RMD(3) 4 SIMD 5 Z09982 6VMD(1) 7 VMD(2) 8 VMD(3) 9WMD(1) 10 WMD(2) 11 WMD(3) 12


1 0. 0. 0. 0. 0.2 0. 0. 0. 0. 0.3 0. 0. 0. 0. 0.4 0. 0. 0. 0. 0.5 0. 0. 0. 0. 0.6 0. 0. 0. 0. 0.7 0. 0. 1.739E-05 0. 0.8 0. 0. -0.0023833 0. 0.9 -18.475500 0. 0. 0. -12918.600

10 0. 0. 0. 0. 0.11 -2.0192300 0. 0. 0. -276.7320012 0. 0. 9.376E-13 0. 0.

6 7 8 9 101 0. 0. 0. 0. 1.00000002 0. 1.0000000 0. 0. 0.3 0. 0. 1.0000000 0. 0.4 0. 0. 0. 1.0000000 0.5 0. 0. 0. 0. 0.6 0. 0. 0. 0. 0.7 -170.05400 -5.132E-04 0.0437463 0. 0.8 12917.900 0.0703363 -5.9952000 0. 0.9 0. 0. 0. -5.9955200 0.

10 0. 0. 0. 0. -4.209410011 0. 0. 0. -0.1284260 0.12 -276.72600 -2.767E-11 0.1284220 0. 0.





11 121 -0.0072969 0.2 0. 0.3 0. 0.4 0. 0.5 1.0000300 0.6 0. 1.00000007 0. 0.8 0. 0.9 0. 0.

10 0. 0.11 -2.4097800 0.12 0. -2.4097800


1 2.5909E-122 0.3 0.4 -2.9009E-185 -4.9658E-176 -3.1157E-04 +/-0.06794360 0.067944 0.0045868 -4.209410009 -4.20243000 +/-16.5380000 17.06360 0.246281

11 -4.20265000 +/-16.5382000 17.06380 0.246291

S dxref=10.7,TITLE(53)='Aft CG 'S thmic=0.0,tstp=1.99STARTTime LimitPLOT nm(2),wm(3),al3,vm(2),thmDrawing plot number 2ANALYZE/VECTORS=.T./EIGENComplex eigenvalues in ascending order

REAL IMAGINARY FREQUENCY DAMPING1 1.4193E-052 8.5494E-083 0.4 0.5 -1.0868E-116 -1.1200E-04 +/-0.03939890 0.039399 0.0028438 -4.208520009 -4.20153000 +/-24.8543000 25.20700 0.166681

11 -4.20160000 +/-24.8544000 25.20700 0.166684

Complex eigenvectors1 2 3

1 0. 0. -2.125E-13 0. 0. 0.2 1.0000000 0. 0. 0. 0. 0.3 4.046E-04 0. 0. 0. 0. 0.4 0. 0. -1.0000000 0. 1.0000000 0.5 0. 0. 3.968E-11 0. 0. 0.6 -5.976E-12 0. 0. 0. 0. 0.7 1.419E-05 0. 0. 0. 0. 0.8 5.742E-09 0. 0. 0. 0. 0.9 0. 0. -8.549E-08 0. 0. 0.

10 0. 0. 0. 0. 0. 0.11 0. 0. -1.459E-16 0. 0. 0.12 -8.482E-17 0. 0. 0. 0. 0.




The ANALYZE command is used to find a trim condition and evaluate the Jacobianand the eigenvalues. To find the trim condition, seven state variables (RM, VM, andFIM) are frozen, leaving five to be varied. The missile position is frozen so that thematrix will be invertible, and the velocity and roll angle are the conditions for trim.

ANALYZE/JACOBIAN/EIGEN produces the row and column vector names, thematrix elements, and the complex eigenvalues in ascending order. The matrix is the[A] matrix, with various states frozen and no controls or observables defined. Theeigenvectors show a real pole at -4.21 and double complex poles at -1.2±16.6.

ACSL Runtime Exec Version 6 Level 10B 5-MAR-91 16:28:55 Page 6Missile Longitudinal Dynamics Step in Fin Aft CG

4 5 61 0. 0. -2.698E-17 0. 0. 0.2 1.0000000 0. 0. 0. 0.3663980-0.04184223 0. 0. 0. 0. -0.1145630-0.92159004 0. 0. 1.0000000 0. 0. 0.5 0. 0. 5.044E-15 0. 0. 0.6 0. 0. 0. 0. 1.686E-05-2.058E-067 0. 0. 0. 0. 0.0016075 0.01444038 0. 0. 0. 0. 0.0363224-0.00441049 0. 0. -1.087E-11 0. 0. 0.

10 0. 0. 0. 0. 0. 0.11 0. 0. -1.895E-20 0. 0. 0.12 0. 0. 0. 0. 7.921E-08 6.644E-07

7 8 91 0. 0. -0.1075760 0. 0. 0.2 0.3663980 0.0418422 0. 0. 2.312E-04-2.098E-043 -0.1145630 0.9215900 0. 0. -0.0312990 0.02424734 0. 0. -0.2046220 0. 0. 0.5 0. 0. 3.477E-05 0. 0. 0.6 1.686E-05 2.058E-06 0. 0. 0.0016279-0.00102897 0.0016075-0.0144403 0. 0. 0.0042420 0.00662758 0.0363224 0.0044104 0. 0. -0.4711460-0.87979009 0. 0. 0.8611550 0. 0. 0.

10 0. 0. 0.4527350 0. 0. 0.11 0. 0. -2.219E-04 0. 0. 0.12 7.921E-08-6.644E-07 0. 0. 0.0187338 0.0447837

10 11 121 0. 0. 8.940E-06-5.138E-06 8.940E-06 5.138E-062 2.312E-04 2.098E-04 0. 0. 0. 0.3 -0.0312990-0.0242473 0. 0. 0. 0.4 0. 0. -0.0360518 0.0163680 -0.0360518-0.01636805 0. 0. -0.0016697 9.597E-04 -0.0016697-9.597E-046 0.0016279 0.0010289 0. 0. 0. 0.7 0.0042420-0.0066275 0. 0. 0. 0.8 -0.4711460 0.8797900 0. 0. 0. 0.9 0. 0. 0.5582920 0.8272740 0.5582920-0.8272740

10 0. 0. 0. 0. 0. 0.11 0. 0. 0.0308676 0.0374668 0.0308676-0.037466812 0.0187338-0.0447837 0. 0. 0. 0.

SPARE ! List execution timeAccumulated cp time 36.16000. Elapsed cp time 17.44000QUIT




In order to see the trim condition, the state variables are transferred back to the initialconditions by REINIT. A debug dump is generated from one pass through the code bysetting the stop time to zero and NDBUG to one. The START command produces thedebug listing.

The next ANALYZE command evaluates the Jacobian of the full twelve by twelvestate matrix with corresponding eigenvalues.

The last exercise is to move the center of gravity to the rear (i.e., reference pointforward), which models a launch or unburned motor condition. The plot of theresponse is shown in Figure A10-7 with the matching eigenvalues listed on page 5 ofthe log file. Note that the response is more oscillatory and the dominant roots havebecome more unstable.

Figure A10-6. Missile plots with nominal CG



Figure A10-8 shows a dictionary listing. This output is obtained by calling subroutineLISTD from the program. A dictionary file contains the variable names (starting incolumn 1) and definitions (starting in column 11). The following statements appear inthe TERMINAL section:

LOGICAL dictionaryCONSTANT dictionary = .FALSE.IF(dictionary) CALL LISTD(11)

At runtime, DICTIONARY is set to TRUE and the START command issued. Theoutput appears in the log file with values inserted between names and definitions. Forarrays, type and size are given. Askterisks for THMD indicate that there is no variableby that name in the program. ZZSEED and S (at the end of the listing) were not foundin the dictionary file. See Appendix B for more details on LISTD.

Figure A10-7. Missile plots with CG moved aft




A real((30)) Array of aerodynamic stability derivativesAL2 0. Angle of attack about M2, positive wind from above (rad)AL3-0.00713084 Angle of attack about M3, positive wind from right (rad)

B 3.95000000 Characteristic span (ft)C dble((6)) Array of aerodynamic coefficients

CBAR 5.62000000 Characteristic chord (ft)CCVV-0.00274116 Chord over velocity (sec)

CD dble((3)) Damping derivative - dimensionless moment derivativesCINT 0.02000000 Communication interval (sec)

CLP dble((10)) Roll damping coefficientCMQ dble((10)) Pitch and yaw damping coefficient

DL dble((4)) Fin deflection (rad)DXCG 10.2000000 Center of gravity position, positive to rear (ft)

DXREF 9.60000000 Aerodynamic reference point, positive to rear (ft)FIM 0. Roll angle of missile in M frame (rad)

FIMIC 0. Initial condition of FIMG 32.2000000 Acceleration of gravity (ft/s**2)

IALG 4 Integration algorithm (integer)IXX 8.77000000 Roll inertia (slug-ft**2)IYY 361.800000 Lateral inertia (slug-ft**2)LRO dble((20)) Log of atmospheric density

MACH 1.99851014 Mach numberMASS 8.77000000 Missile mass (slug)MAXT 0.01000000 Maximum integration step size (sec)

ME dble((9)) Direction cosine matrix between E frame and M frameMINT 1.0000D-09 Minimum integration step size (sec)

MVM 2152.54590 Magnitude of VM (ft/s)NM dble((3)) Aerodynamic acceleration vector of missile (ft/s**2)

NME dble((3)) NM vector expressed in E frame (ft/s**2)NSTP 1 Number of steps per communication interval (integer)

Q 4056.45841 Dynamic pressure (lb/ft**2)RM dble((3)) Range vector of missile (ft)

RMD dble((3)) Derivative of RM (ft/s)RMIC dble((3)) Initial condition of RM (ft)

RO 0.00175094 Atmospheric density (slug/ft**3)SIM 0. Yaw angle of missile (rad)

SIMD 0. Derivative of SIM (rad/s)SIMIC 0. Initial condition of SIM (rad)

T 2.00000000 Independent variable, time (sec)THM 0.04474506 Pitch angle of missile (rad)

THMD ****** Derivative of THM (rad/s)THMIC 0. Initial condition of THM (rad)

THRUST 0. Thrust from propulsion system (lb)TSTP 1.99000000 Stopping time for simulation runs (sec)

VM dble((3)) Velocity of missile (ft/s)VMD dble((3)) Acceleration of missile (ft/s**2)

VMIC dble((3)) Initial condition of VM (ft/s)VMM dble((3)) VM vector expressed in M frame (ft/s)

VS 1077.07529 Velocity of sound (ft/s)VSF dble((20)) Name of table for VS as function of Mach

WM dble((3)) Spin rate vector of missile (rad/s)WMD dble((3)) Derivative of WM (rad/s**2)

WMIC dble((3)) Initial condition of WM (rad/s)ZZSEED 55555555 *

S 13.9000000 *

Figure A10-8. Missile example dictionary output from subroutine LISTD



11. DiscreteSampledCompensator

In this example, a digitial control computer interacts with a continuous plant. ADISCRETE section is used in modeling the sampled data system. The system blockdiagram is shown in Figure A11-1. The plant is represented by a transfer function:

1s(s + 1)

This system can be visualized as a water level control problem where the valvecontrolling the flow into the tank has a one second time constant. An instantaneouslevel measurement (X) is assumed; it is compared with a desired (control) level (XC),and the error is sampled every tenth of a second. A digital controller is to take thesamples of level errorE and output a commandU to the valve, thus closing the loop.This control is taken to be a linear combination of the current error (En), the previouserror (En-1), and the previous control (Un-1). Expressed in Z-transform notation, this is:

UE

=a0 − a1z

−1

1 − b1z−1

In terms of equivalent lead/lag network, thea andb coefficients above can be writtenas follows, which gives steady state gain of one and reduces to a zero order hold whenthe lead and lag time constants are equal:

a0 =TLED

TLAGe−Ts (1 ⁄ TLAG − 1 ⁄ TLED)

a1 =TLED

TLAGe−Ts ⁄ TLAG

b1 = e−Ts ⁄ TLAG

Figure A11-1. Discrete control system block diagram

A. ACSL Example Programs A11. Discrete Sampled Compensator


The program to represent this plant and control system is shown in Figure A11-2. AnINITIAL, a DERIVATIVE, and two DISCRETE sections are used.

In the INITIAL section, the coefficients of the digital filter are calculated so that thecontroller response can be thought of in terms of equivalent lead/lag time constants.The constants for these equations are found later in the program.TSAMP, for example,is found in the INTERVAL statement in DISCRETE section ADC.TLEDandTLAGare specified in a CONSTANT statement just before the calculation ofUC, which usesthem in the LEDLAG operator. CONSTANT statements can be placed anywhere inthe program; we recommend placing them near equations where they are used or elsein a block whereall constants are specified so that they can be found easily.

Also in the INITIAL section, the discrete control (UD) and the previous error (EP) areinitialized to zero. These are effectively system state variables (i.e., since they areneeded before they are calculated) even though they are not obtained, as most statesare, by integration.

The continuous section is given a name (DERIVATIVE CONTINUOUS). Naming thesection is optional. The plant is modeled by the one line:

x = INTEG(REALPL(tad, ku*u), 0.0)

The control (U) is selected to take either the discrete value (UD) or that produced by acontinuous lead-lag compensator (UC) based on a switchDISCRETE; i.e.,

u = RSW(discrete, ud, uc)

The logicalDISCRETEis set by a CONSTANT statement and is therefore accessibleat runtime for switching between the effect of the discrete or the continuous controller.WhenDISCRETEis TRUE, the controller is discrete; when FALSE, continuous.

Integration step size for the continuous section is 0.02 seconds, specified both by thecommunication interval (CINT) and by MAXT. The reason such a comparatively shortstep is used is to record data during the sampling so that the discrete hold (sampleinterval 0.1 sec) can be seen on the plots. With five data points logged for everysample, the corners of the control (U) can be clearly seen in the plots. If thecommunication interval had been increased to 0.1 seconds or more, the straight linesdrawn between points would have masked the sampling action, though the simulationwould still behave the same internally. Another method of squaring the corners, alsoimplemented in this example, is to call the LOGD subroutine to log data at thebeginning and end of the DISCRETE sections.

In the DISCRETE ADC section, the step size is controlled by the INTERVALstatement, which specifies the name of the controlling variable as TSAMP and a valueof 0.1 seconds. The code executes once at timeT zero and then once every 0.1 secondsthereafter. A new control is calculated, but hidden from the continuous section, basedon the previous control, previous error, and current error as follows:

udp = b1*ud + a0*ep - a1*ep

The current error is transferred to the previous error by the statement:

ep = e

With the use of the DISCRETE section, the continuous section is guaranteed to stepup to the sample time, when the DISCRETE section code is executed, so the value ofcurrent error (E) used is that actually at the sample time. The new value of control iseffectively calculated instantaneously, but since the control computer action is to bemodeled, the change in actual control used (UD) must be delayed by the calculationtimeDELAYTIME. This is implemented with a SCHEDULE statement as follows:

A11. Discrete Sampled Compensator A. ACSL Example Programs


PROGRAM discrete sampled compensator!-----------------------models a continuous plant with either a! continuous or discrete feed back controller wrapped around it.! plant can be visualised as a level controller using valve! with single lag time constant (= 1 second)

INITIALCINTERVAL cint = 0.02NSTEPS nstp = 1MAXTERVAL maxt = 0.020!-----------------------calculate z transform controller gainsb1 = EXP(-tsamp/tlag)a0 = tled*EXP(-tsamp*(1.0/tlag - 1.0/tled))/tlaga1 = tled*EXP(-tsamp/tlag)/tlag!-----------------------initialise pseudo state variablesud = 0.0ep = 0.0

END ! of initial

DERIVATIVE continuous!-----------------------plant modelCONSTANT ku = 5.0 , tad = 1.0x = INTEG(REALPL(tad, ku*u), 0.0)!-----------------------continuous control actionCONSTANT tled = 0.5 , tlag = 0.5uc = LEDLAG(tled, tlag, e)!-----------------------error signalCONSTANT xc = 1.0e = xc - x!-----------------------choose discrete or continuous controlLOGICAL discreteCONSTANT discrete = .TRUE.u = RSW(discrete, ud, uc)!-----------------------terminate on time limitCONSTANT tstp = 4.9TERMT(t .GE. tstp, 'Time Limit')


discrete adcINTERVAL tsamp = 0.1!-----------------------discrete control is linear combination of! prev control, prev error and current err! use prime to hide output from continuousudp = b1*ud + a0*e - a1*ep!-----------------------current error becomes previous errorep = e!-----------------------schedule the *dac* block for output! after a simulated compute delayCONSTANT DelayTime = 0.0SCHEDULE dac .AT. t + DelayTime!-----------------------record dataCALL LOGD(.FALSE.)

END ! of adc section

DISCRETE dac!-----------------------record data at corner before changeCALL LOGD(.FALSE.)!-----------------------make control value available to continuousud = udp!-----------------------record data at corner after changeCALL LOGD(.FALSE.)

END ! of dac section

END ! of program

Figure A11-2. Discrete sampled compensator program




SET TITLE='Discrete Sampled Controller'SPAREAccumulated cp time 32.69000. Elapsed cp time 0.PREPARE t,u,ud,x,e,udpOUTPUT/NCIOUT=50 t,u,xSTART

T 0. U 0. X 0.T 0. U 0. X 0.T 0.60000000 U 0.50326300 X 0.66837700T 1.24000000 U-0.50654800 X 1.53218000T 1.88000000 U-0.41542200 X 1.34435000T 2.50000000 U 0.15728100 X 0.77153900T 3.10000000 U 0.32884700 X 0.70015700T 3.74000000 U-0.02579170 X 1.04731000T 4.38000000 U-0.20214400 X 1.19847000

Time LimitT 4.92000000 U-0.06463310 X 1.05753000

SET PCWPRN=80 ! Narrow printer pagePRINT/NCIPRN=10/ALL ! Column print of all saved variables

Line T U UD X E UDP0 0. 0. 0. 0. 1.00000000 1.00000000

10 0.10000000 1.00000000 0.97581300 0.02418710 0.97581300 0.9758130020 0.24000000 0.90693100 0.90693100 0.13173600 0.86826400 0.9069310030 0.38000000 0.79984000 0.79984000 0.30805200 0.69194800 0.7998400040 0.50000000 0.66237800 0.66237800 0.49673700 0.50326300 0.5032630050 0.60000000 0.50326300 0.33162300 0.66837700 0.33162300 0.3316230060 0.74000000 0.15652200 0.15652200 0.91257600 0.08742450 0.1565220070 0.88000000 -0.01346050 -0.01346050 1.14047000 -0.14047200 -0.0134605080 1.00000000 -0.17060300 -0.17060300 1.30835000 -0.30835000 -0.3083500090 1.10000000 -0.30835000 -0.42153900 1.42154000 -0.42153900 -0.42153900

100 1.24000000 -0.50654800 -0.50654800 1.53218000 -0.53217800 -0.50654800110 1.38000000 -0.56135300 -0.56135300 1.58310000 -0.58309700 -0.56135300120 1.50000000 -0.58551600 -0.58551600 1.58008000 -0.58008400 -0.58008400130 1.60000000 -0.58008400 -0.54744100 1.54744000 -0.54744100 -0.54744100140 1.74000000 -0.49109300 -0.49109300 1.46287000 -0.46287000 -0.49109300150 1.88000000 -0.41542200 -0.41542200 1.34435000 -0.34434900 -0.41542200160 2.00000000 -0.32541600 -0.32541600 1.22639000 -0.22638500 -0.22638600170 2.10000000 -0.22638600 -0.12369100 1.12369000 -0.12369000 -0.12369100180 2.24000000 -0.02248060 -0.02248060 0.98346600 0.01653440 -0.02248060190 2.38000000 0.07253550 0.07253550 0.85871000 0.14129000 0.07253550200 2.50000000 0.15728100 0.15728100 0.77153900 0.22846100 0.22846100210 2.60000000 0.22846100 0.28366200 0.71633800 0.28366200 0.28366200220 2.74000000 0.32140400 0.32140400 0.66852700 0.33147300 0.32140400230 2.88000000 0.34114500 0.34114500 0.65581400 0.34418600 0.34114500240 3.00000000 0.34323700 0.34323700 0.67115300 0.32884700 0.32884700250 3.10000000 0.32884700 0.29984300 0.70015700 0.29984300 0.29984300260 3.24000000 0.25865400 0.25865400 0.76061400 0.23938600 0.25865400270 3.38000000 0.20811300 0.20811300 0.83696500 0.16303500 0.20811300280 3.50000000 0.15129800 0.15129800 0.90863900 0.09136110 0.09136110290 3.60000000 0.09136110 0.03137870 0.96862100 0.03137870 0.03137870300 3.74000000 -0.02579170 -0.02579170 1.04731000 -0.04730710 -0.02579170310 3.88000000 -0.07763200 -0.07763200 1.11383000 -0.11383200 -0.07763200320 4.00000000 -0.12205800 -0.12205800 1.15749000 -0.15748800 -0.15748800330 4.10000000 -0.15748800 -0.18288200 1.18288000 -0.18288200 -0.18288200340 4.24000000 -0.19775100 -0.19775100 1.20075000 -0.20075200 -0.19775100350 4.38000000 -0.20214400 -0.20214400 1.19847000 -0.19846800 -0.20214400360 4.50000000 -0.19660400 -0.19660400 1.18211000 -0.18210600 -0.18210600370 4.60000000 -0.18210600 -0.15998500 1.15998000 -0.15998400 -0.15998500380 4.74000000 -0.13183800 -0.13183800 1.11928000 -0.11928200 -0.13183800390 4.88000000 -0.09943870 -0.09943870 1.07171000 -0.07171230 -0.09943870

Figure A11-3. Discrete sampled compensator log file (part 1)



ACSL Runtime Exec Version 6 Level 10B 14-MAR-91 16:00:39 Page 2Discrete Sampled Controller

PLOT x,ud ! Line plotDrawing plot number 1SET tled=2.5,tlag=0.5 ! Five to one lead/lag ratioSET ku=1.0 ! Reduce proportional gainSTART

T 0. U 0. X 0.T 0. U 0. X 0.T 0.60000000 U 0.88902800 X 0.46543400T 1.24000000 U-0.84162500 X 0.93225100T 1.88000000 U-0.33489500 X 0.97242200T 2.50000000 U 0.10986600 X 0.90739600T 3.10000000 U 0.13093300 X 0.89910700T 3.74000000 U 0.01873850 X 0.92664500T 4.38000000 U-0.00932653 X 0.94825300

Time LimitT 4.92000000 U 0.00200705 X 0.95680900

PRINT/ALL ! Keep same interval of every tenth point

Line T U UD X E UDP0 0. 0. 0. 0. 1.00000000 4.26072000

10 0.10000000 4.26072000 3.56763000 0.02061090 0.97938900 3.5676300020 0.24000000 2.84662000 2.84662000 0.10639900 0.89360100 2.8466200030 0.38000000 2.13983000 2.13983000 0.23408200 0.76591800 2.1398300040 0.50000000 1.47961000 1.47961000 0.35929600 0.64070400 0.8890280050 0.60000000 0.88902800 0.38268900 0.46543400 0.53456500 0.3826890060 0.74000000 -0.03217460 -0.03217460 0.60624200 0.39375800 -0.0321746070 0.88000000 -0.35447400 -0.35447400 0.72892700 0.27107300 -0.3544740080 1.00000000 -0.58800000 -0.58800000 0.81536700 0.18463200 -0.7401840090 1.10000000 -0.74018400 -0.82093700 0.87305100 0.12694900 -0.82093700

100 1.24000000 -0.84162500 -0.84162500 0.93225100 0.06774940 -0.84162500110 1.38000000 -0.81418000 -0.81418000 0.96850200 0.03149810 -0.81418000120 1.50000000 -0.75038300 -0.75038300 0.98412200 0.01587750 -0.66130100130 1.60000000 -0.66130100 -0.55689000 0.98837400 0.01162590 -0.55689000140 1.74000000 -0.44573100 -0.44573100 0.98428400 0.01571600 -0.44573100150 1.88000000 -0.33489500 -0.33489500 0.97242200 0.02757840 -0.33489500160 2.00000000 -0.22991700 -0.22991700 0.95894300 0.04105670 -0.13484200170 2.10000000 -0.13484200 -0.05234860 0.94692800 0.05307150 -0.05234860180 2.24000000 0.01609370 0.01609370 0.93070200 0.06929800 0.01609370190 2.38000000 0.07003930 0.07003930 0.91675000 0.08324980 0.07003930200 2.50000000 0.10986600 0.10986600 0.90739600 0.09260420 0.13658100210 2.60000000 0.13658100 0.15163400 0.90168300 0.09831670 0.15163400220 2.74000000 0.15674700 0.15674700 0.89688800 0.10311200 0.15674700230 2.88000000 0.15377600 0.15377600 0.89555300 0.10444700 0.15377600240 3.00000000 0.14458000 0.14458000 0.89676100 0.10323800 0.13093300250 3.10000000 0.13093300 0.11445200 0.89910700 0.10089300 0.11445200260 3.24000000 0.09654840 0.09654840 0.90391900 0.09608100 0.09654840270 3.38000000 0.07840290 0.07840290 0.90989200 0.09010800 0.07840290280 3.50000000 0.06095420 0.06095420 0.91547600 0.08452410 0.04490550290 3.60000000 0.04490550 0.03073870 0.92020500 0.07979540 0.03073870300 3.74000000 0.01873850 0.01873850 0.92664500 0.07335470 0.01873850310 3.88000000 0.00902000 0.00902000 0.93261100 0.06738920 0.00902000320 4.00000000 0.00156000 0.00156000 0.93720900 0.06279060 -0.00377259330 4.10000000 -0.00377259 -0.00718673 0.94063300 0.05936680 -0.00718673340 4.24000000 -0.00894266 -0.00894266 0.94479300 0.05520650 -0.00894266350 4.38000000 -0.00932653 -0.00932653 0.94825300 0.05174660 -0.00932653360 4.50000000 -0.00863191 -0.00863191 0.95072400 0.04927580 -0.00714196370 4.60000000 -0.00714196 -0.00511904 0.95248500 0.04751460 -0.00511904380 4.74000000 -0.00279531 -0.00279531 0.95458100 0.04541880 -0.00279531390 4.88000000 -3.6688E-04 -3.6688E-04 0.95634900 0.04365080 -3.6688E-04




SCHEDULE dac .AT. t + DelayTime

This causes the DAC block to execute at the current timeT plusDELAYTIMEtimeunits later, where the discrete control value is changed to the previously calculatedvalue by:

ud = udp

Figure A11-3 shows the log file of a runtime session. The first run (executed by theSTART command) is followed by a column PRINT of the numeric values and a lineplot of the baseline response. Next the OUTPUT list is CLEARed and another run ismade, with an equivalent lead/lag ratio of 5:1 and a reduction of the loop gain from 5.0to 1.0. Lastly, the response after introducing a computation delay is obtained, using thesame values of lead/lag time constants and gain, by setting the calculation time DLTCto 0.099 sec.

ACSL Runtime Exec Version 6 Level 10B 14-MAR-91 16:00:39 Page 3Discrete Sampled Controller

PLOT x,ud ! Line plotDrawing plot number 2SET NRWITG=.T.,FTSPLT=.T.,SYMCPL=.T. ! Accumulate next runSET delaytime=0.099, NPCCPL=50 ! Extend compute timeSTART

T 0. U 0. X 0.T 0. U 0. X 0.T 0.64000000 U 1.17811000 X 0.41961600T 1.28000000 U-1.01981000 X 0.98924100T 1.89900000 U-0.69416200 X 1.03943000T 2.50000000 U 0.19284100 X 0.91137900T 3.14000000 U 0.25626200 X 0.87461200T 3.78000000 U 0.03929200 X 0.92314200T 4.39900000 U-0.05678210 X 0.95873100

Time LimitT 4.92000000 U-0.02159760 X 0.96481000

SET TITLE(41)='Effect of computation delay'PLOT x/CHAR=1 ! Parametric plot of the two runsDrawing plot number 3SPARE ! List execution timeAccumulated cp time 45.45000. Elapsed cp time 12.76000QUIT




Figure A11-4. Discrete sampled compensator control and level, baseline case

Figure A11-5. Discrete sampled compensator, reduced loop gain, 5:1 lead/lag ratio

Figure A11-6. Discrete sampled compensator comparison using 0.1 sec computational delay



12. AspirinDosage Evaluation

This model follows mathematically the aspirin concentration level in the blood streamof a person taking variable doses at various preset times. A similar program could beused to determine the concentration of any drug which has an exponential decay.

The example shows how discontinuities can be introduced into the simulation statevariables without having to recompute the values of the output of integrators, a matterthat has to be left to the integration routine. In fact, there are no true discontinuities inthe physical world and one should really consider the dynamics of the ingestionprocess;i.e., the passage of the drug through the stomach wall, or, if injected, thevelocity of the hypodermic piston. These effects, however, are approximated in mostsimulations as discontinuities if their time of action is short compared with the overallperiod of interest.

The basic equation in the model is the exponential decay (rate of change) proportionalto the concentration (C) by the constant of proportionality (rateR) as follows:

dCdt

= − RC

Since the concentration can change suddenly as doses are taken, a term indicating thetotal dose must be added. The concentration can now be expressed as an integralequation as follows:

C = ∫ − RC dt + Σ Di

In the program, this is written as follows:

blood = INTEG(-rate*blood, 0.0) + total

whereBLOOD is the concentration in grains andTOTALcontains the sum of the dosesup until the current time.

Figure A12-1 lists the program. Two arrays are defined:DOSETIMEfor the time ofthe dose, andDOSEfor the actual dose at the corresponding time. The size of thearrays is set with a PARAMETER statement, which allows both arrays to bedimensioned in one place. An integer indexINDEX is used to advance through thearrays. The arrays are preset so that a large dose of five tablets (25 grains) is giveninitially and the time between the first and second doses is two hours. The remainingdoses are for three tablets (15 grains) each. Four hours is the usual time between doses,but eight hours elapses between the fourth and fifth doses. The last effective dose is atthirty hours.

In the INITIAL section,INDEXandTOTALare initialized;INDEX is started at one toaccess the initial dose time, andTOTAL(effectively a state variable) is set to zero.

In the DERIVATIVE section, theBLOODandURINE levels are calculated,URINEbeing the total amount excreted. TheURINErate is the opposite of the rate forBLOOD; i.e., what is removed from the bloodstream appears directly in the urine.

An IF-THEN construct determines when more aspirin is added to the total. The currentdose timeTDOS(INDEX)is tested against the independent variable, timeT. If it is notyet time for a dose, the calculations are bypassed. If the dose time has been equalled orexceeded, the dose is added to the total by the statement:

A12. Aspirin Dosage Evaluation A. ACSL Example Programs


total = total + dose(index)

and then the index is incremented by one, ready for the next dose.

PROGRAM aspirin dosage test

!-----------------------follows concentration of drug in body! given a dosage history. uses exponential elimination rate! with fixed time constant

!-----------------------define types and array dimensionsINTEGER indexPARAMETER (indexmax = 9)DIMENSION dose(indexmax) , DoseTime(indexmax)!-----------------------define preset constant valuesCONSTANT dose = 25.0 , 15.0 , 15.0 &

, 15.0 , 15.0 , 15.0 &, 15.0 , 15.0 , 0.0

CONSTANT DoseTime = 0.0 , 2.0 , 6.0 &, 10.0 , 18.0 , 22.0 &, 26.0 , 30.0 , 99.0

!-------------define communication interval and integration stepCINTERVAL cint = 0.5MAXTERVAL maxt = 0.05NSTEPS nstp = 1

INITIAL!-----------------------start with first dose, none present! at beginningindex = 1total = 0.0


!-----------------------amount left in blood streamCONSTANT rate = 0.14blood = INTEG(-rate*blood, 0.0) + total!-----------------------total amount excreted as urineurine = INTEG( rate*blood, 0.0)!-----------------------if time for doseIF(t .GE. DoseTime(index)) THEN

!----------------------add new dose to totaltotal = total + dose(index)!----------------------get set for next doseindex = index + 1!----------------------and stop when given last doseTERMT(index .GT. indexmax, 'Index Limit')

ENDIF

END ! of derivative!-----------------------stop on time limitCONSTANT tstop = 49.0TERMT(t .GE. tstop, 'Time Limit')


Figure A12-1. Aspirin dosage program

A. ACSL Example Programs A12. Aspirin Dosage Evaluation


In writing this type of simulation model, there is an inclination to change the statevariable itself, as, for example, in the following statements:

blood = INTEG(-rate*blood, 0.0)blood = blood + dose(index)

This operation, however, is illegal since the value in the state variableBLOOD is onlya temporary copy of the actual state variable, which is saved internally by theintegration routine. (See Chapter 4 SCHEDULE for a way to change state variablesdirectly.) Note that if theBLOOD integration statement is converted to the expressionform as follows:

blood = -INTEG(rate*blood, 0.0)

BLOOD is no longer a state variable, but simply the negative of the actual statevariable (the output of the INTEG operator) which is given a generated name in theform Z0nnnn.

WhenTOTAL is added to the integration (as in the example model), a similartransformation occurs so thatBLOOD is no longer a state variable; but in this case,TOTALcan be manipulated in such a way that the answer is correct.

Figure A12-2 shows the log file of a runtime session. After the START command, acolumn PRINT is obtained to list numeric values. The PLOT command produces theplot in Figures A12-3. The plot command reads as follows:

PLOT total/TAG = '+ urine', urine/SAME/OVER, blood

The tag string is used to add an extra label on theTOTALaxis, /SAME ensuresidentical scales for bothTOTALandURINE, and /OVER suppresses the nowredundant axis forURINE. BLOOD is then plotted separately with its own scale.

A second run is executed withRATEchanged to 0.28. The plot is shown in FigureA12-4. Comparing the two plots you can see that the higher decay rate has reduced theaverage blood level concentration.

The discontinuities introduced intoTOTALviolate the restrictions on the statevariables placed by most integration algorithms;i.e., that the derivatives shall becontinuous and differentiable. In practice, fixed step size algorithms step over thesediscontinuities very well with only minor differences in the calculated solutions whenthe step size changes. In the code, no attempt is made to synchronize the discontinuitywith the integration step, so it can occur at any of the derivative evaluations that makeup the step. This means that the particular step containing the discontinuity will be inerror, but the answers will be slipped only a fraction of a step length. It is thisrequirement that dictates the integration step size. From the decay rate of the aspirin(0.14 or 0.28), step sizes of two or three hours would do quite well in integrating thedifferential equations. However, uncertainty in dose times of this much is too large anerror. In the model, the step size is set (via MAXT) to 0.05 hr (3 minutes) to reduce theuncertainty, which now seems tolerable in light of what is being simulated.

If a finer time scale is required, the SCHEDULE operator can be used to determine thetime of each event exactly; then much larger steps can be used in integrating thecontinuous part of the model. For example, the following statement would find theevents more accurately:

SCHEDULE .XP. t - dosetime(index)

In this method,T is adjusted so that it just crosses the threshold set up in the dose timetable. This approach saves computer time but requires a somewhat more complexprogram.




SET TITLE = 'Aspirin Dosage Test'SPAREAccumulated cp time 19.19000. Elapsed cp time 0.S TCWPRN=72 ! Force 3 column output widthPREPARE t, blood, urine, total, indexSTARTTime LimitPRINT/NCIPRN=5/ALL

Line T BLOOD URINE TOTAL INDEX0 0. 25.0000000 0. 25.0000000 25 2.50000000 31.6031000 8.39689000 40.0000000 3

10 5.00000000 22.2703000 17.7297000 40.0000000 315 7.50000000 27.8382000 27.1618000 55.0000000 420 10.0000000 34.5998000 35.4002000 70.0000000 525 12.5000000 24.3820000 45.6180000 70.0000000 530 15.0000000 17.1817000 52.8183000 70.0000000 535 17.5000000 12.1078000 57.8922000 70.0000000 540 20.0000000 19.8689000 65.1310000 85.0000000 645 22.5000000 27.9873000 72.0127000 100.000000 750 25.0000000 19.7223000 80.2777000 100.000000 755 27.5000000 26.0569000 88.9431000 115.000000 860 30.0000000 33.3620000 96.6380000 130.000000 965 32.5000000 23.5098000 106.490000 130.000000 970 35.0000000 16.5671000 113.433000 130.000000 975 37.5000000 11.6746000 118.325000 130.000000 980 40.0000000 8.22696000 121.773000 130.000000 985 42.5000000 5.79744000 124.203000 130.000000 990 45.0000000 4.08539000 125.915000 130.000000 995 47.5000000 2.87892000 127.121000 130.000000 9

PLOT total/TAG='+ urine', urine/SAME/OVER, bloodDrawing plot number 1DISPLAY rate, dosetime, dose

RATE 0.14000000 DOSETIME 0. 2.000000006.00000000 10.0000000 18.000000022.0000000 26.0000000 30.000000099.0000000 DOSE 25.0000000 15.000000015.0000000 15.0000000 15.000000015.0000000 15.0000000 15.00000000.

SET rate=0.28, TITLE(41)='Rate = 0.28'STARTTime LimitPLOT total, urine/SAME, bloodDrawing plot number 2DISPLAY rate, dosetime, dose

RATE 0.28000000 DOSETIME 0. 2.000000006.00000000 10.0000000 18.000000022.0000000 26.0000000 30.000000099.0000000 DOSE 25.0000000 15.000000015.0000000 15.0000000 15.000000015.0000000 15.0000000 15.00000000.

SPARE ! List execution timeAccumulated cp time 24.93000. Elapsed cp time 5.740000QUIT

Figure A12-2. Aspirin dosage log file

A. ACSL Example Programs A12. Aspirin Dosage Evaluation


Figure A12-3. Aspirin dosage plots for RATE = 0.14

Figure A12-4. Aspirin dosage plots for RATE = 0.28



13. Block on aRough Surface

This example demonstrates use of the SCHEDULE statement to find a series of stateevents.

The model is a mass (or block) resting on a rough surface, attached by a spring to apoint that can be moved, thus applying a force to the block via the compression orextension of the spring. Figure A13-1 is a diagram showing the positive directions.The deflection of the mass isXB and the forcing function is the deflection of the end ofthe springXF. Units are kilogram, meter, and second for mass, length, and time,respectively.

A sinusoidal forcing function exercises the model. The block is assumed to start atrest. Motion begins only when the deflection of the spring applies a force equal to theCoulomb friction breakout force. At this point, the block starts to move and accelerate.Eventually the driving point reverses velocity due to the sine wave motion nowextending the spring and causing the block to decelerate. When the block velocityacross the table crosses zero, friction grabs the block until the spring has beenextended enough to again exceed the breakout force in the other direction. The processrepeats, the block alternately sticking and unsticking at each half cycle of the forcingsine wave.

This limit cycle is observed many times in practice when friction surfaces slowmoving bodies. This configuration has been used to study the juddering (stick-slide)that occurs as an airplane comes to a stop. In this case, the undercarriage is the springand the brake lining is the rough surface. At some critical velocity, the brake shoestarts to stick and unstick, which can cause significant vibration.

It is possible to choose parameters for the spring constant, amplitude, mass, andfriction level so that the block never moves or never stops once started. For thisexample, however, a middle path with sticking and unsticking is chosen.

Figure A13-1. Diagram of block on a rough surface

A. ACSL Example Programs A13. Block on a Rough Surface


Figure A13-2 lists the program. The forcing function deflection of the spring is givenby the equation:

xf = xfa*SIN(2*pi*freqf*t)

whereXFA is the amplitude of the deflection (nominally 0.05 m) andFREQFis thefrequency of the oscillation (nominally 0.4 Hz).

The sum of the forces acting on the block (excluding Coulomb friction) results fromspring deflection and viscous damping as follows:

sumfb = ksp*(xf - xb) + kbvd*xbd

The force due to Coulomb friction depends on whether the block is sliding or not.When the block is stuck, the Coulomb friction force exactly cancels all the otherforces; when the block is sliding, the Coulomb friction force has a constant valueequal to the sliding friction value (a little less than the breakout force) in a directionopposite to that of the velocity. The force on the block due to Coulomb friction can beexpressed as follows:

fbcf = RSW(stukb, -sumfb, fbsf)

whereFBSFis the constant sliding friction force; at breakout time,FBSFis given thecorrect sign to oppose the direction of the block velocity. RSW (real switch) is afunction which returns the second argument if the first argument is TRUE; otherwise,it returns the third argument.

The acceleration of the block is the sum of all the forces (including Coulomb friction)divided by the mass; i.e,

xbdd = (sumfb + fbcf)/mb

and the velocity and position are successive integrals of this acceleration.

A zero crossing function to define the events of unsticking and sticking is required.When the block is stuck, the force applied to it must exceed a breakout value beforethe block starts to move. When the block is sliding, it must be tested for sticking whenthe velocity crosses zero;i.e., if the force acting on the body is less than the breakoutforce required to drag the velocity through zero, the block sticks. A functionFIB isdefined as follows:

fib = RSW(stukb, ABS(sumfb) - kbbf, xbd)

This function is then specified to the zero crossing finder as a state event as follows:

SCHEDULE stick .XZ. fib

This statement schedules the execution of the DISCRETE section STICK immediatelyafter the zero crossing. The logicalSTUKBis determined in this DISCRETE section isas follows:

stukb = .NOT.stukb .AND. ABS(sumfb) .LT. kbbf

The first part of the statement (STUKB=.NOT.STUKB) acts as a toggle;i.e., whenSTUKBis FALSE, it becomes TRUE; if TRUE, it becomes FALSE. The secondclause ensures that if the sum of the forces exceeds the breakout force, the expressionis FALSE, thus ensuring thatSTUKBis also FALSE.

The sliding friction either opposes the applied force (if the block is now unstuck) or itis zero (if the block is stuck):

fbsf = RSW(stukb, 0.0, SIGN(kbsf, -sumfb))

A13. Block on a Rough Surface A. ACSL Example Programs


The sliding friction value has been calculated in the DISCRETE section deliberatelyso that the value is continuous (actually constant) within the continuousDERIVATIVE section. An alternate way of describing the situation, and the firstmethod tried in this case, was to define the Coulomb forceFBCFby the statement:

fbcf = RSW(stukb, -sumfb, SIGN(kbsf, -xbd))

PROGRAM - friction test

!-----------------------models a block sliding on a rough! surface under the action of a force applied through a! spring. the spring force must exceed a breakout coulomb! friction force in order to start to move. once it starts! to move the frictional force has a value equal to the! sliding friction in a direction opposing the motion

!-----------------------define simulation environmentCINTERVAL cint = 0.020ALGORITHM ialg = 4MAXTERVAL maxt = 0.050MINTERVAL mint = 1.0e-6NSTEPS nstp = 1!-----------------------define global constantsPARAMETER (pi = 3.14159 )

INITIAL

!-----------------------give the states the initial cond valuesRESET("NOEVAL")

END ! of initial

DERIVATIVE!-----------------------forcing function is displacement of! free end of spring attached to bodyCONSTANT xfa = 0.05 , freqf = 0.40xf = xfa*SIN(2.0*pi*freqf*t)!-----------------------sum of forces on body excluding frictionCONSTANT ksp = 100.0 , kbvd = -0.50sumfb = ksp*(xf - xb) + kbvd*xbd!-----------------------force due to coulomb friction exactly! cancels other forces when stuckfbcf = RSW(stukb, -sumfb, fbsf)!-----------------------acceleration of bodyCONSTANT mb = 1.0xbdd = (sumfb + fbcf)/mb!-----------------------integrate for velocity and positionxbd = INTVC(xbdd, xbdic) ; CONSTANT xbdic = 0.0xb = INTEG(xbd, xbic) ; CONSTANT xbic = 0.0!-----------------------define *phi* function for stick/unstickfib = RSW(stukb, ABS(sumfb) - kbbf, xbd)!-----------------------schedule the execution of the discrete! block *stick* on a zero crossingSCHEDULE stick .XZ. fib!-----------------------specify termination conditionTERMT(t .GE. tstp, 'Time Limit') ; CONSTANT tstp = 4.99

END ! of derivative

Figure A13-2. Block on a rough surface program (part 1)



In this situation, when the block is sliding (STUKB=.FALSE.), the Coulomb forcereverses sign discontinuously in response to the sign of velocityXBD. Thisdiscontinuity affects the accuracy of the integration step when the velocity just crosseszero. It is better to keep the model continuous even though the Coulomb frictionappears to increase the velocity on the far side; this is an unrealistic condition, but onewhich occurs only for the single integration step that just crosses the velocity equalzero surface. The event finder penetrates the event an insignificant amount and thenapplies the discontinuity in the DISCRETE section that handles the event.

The next step in the program (an important one) adjusts the velocity so that it isexactly zero when the block unsticks. When the block is about to stick, the zerocrossing used is the velocity, and this must cross to a small nonzero value (about1.0E-7 in this case). If on unsticking and reverting to velocity crossing control theblock continues with the same sign of acceleration, the velocity increases andpresumably sometime in the future returns to zero. However, if during the period ofsticking, the acceleration changes sign and the velocity tries to return back thoughzero, another event-finding sequence is triggered and the event is handled when thevelocity is just slightly on the other side of zero. The applied force presumably stillexceeds the breakout force, keeping the body unstuck, but there is an overhead to thezero-finding operation.

The solution to avoiding extraneous zero finding operations is to set the velocityexactly to zero. Since an exact zero is neutral as far as the zero crossing finder isconcerned, the velocity must integrate away from zero and then return. The directionof the acceleration at the point of unsticking is then of no concern.

DISCRETE stick

!-----------------------handle coulomb friction

!-----------------------initialise stuck flagsINITIAL

LOGICAL stukbstukb = xbd .EQ. 0.0

END ! of initial!-----------------------stuck flag toggles unless force exceeds! breakout force on crossing zeroCONSTANT kbbf = 2.50stukb = .NOT.stukb .AND. ABS(sumfb) .LT. kbbf!-----------------------sliding friction opposes applied forceCONSTANT kbsf = 2.00fbsf = RSW(stukb, 0.0, SIGN(kbsf, -sumfb))!-----------------------reset velocity to exactly zero. you must! know *xbd* is a state variable for thisxbd = 0.0!-----------------------record statusCALL LOGD(.TRUE.)!-----------------------define debug dump flag and conditionLOGICAL dump ; CONSTANT dump = .FALSE.IF(DUMP) CALL DEBUG

END ! of discrete

END ! of program

Figure A13-2. Block on a rough surface program (part 2)



Setting the velocity to exactly zero is possible only because it is known to be a statevariable. This is the one situation in which state variables can be changeddiscontinuously. At a state event, all state variable values are retrieved from internaltables maintained by the integration algorithms, stored in the appropriate slotaccessible to the model code, and then the DISCRETE sections designated as handlersfor the event(s) are executed in turn. After all the handler sections have been executed,the states are then stored away and are ready for the next integration step.

Initializing the model is handled by a RESET statement in the INITIAL section at thebeginning of the program plus an INITIAL region embedded in the DISCRETEsection. The code embedded in the DISCRETE section establishes the stuck/unstuckcondition depending on whether the velocity is zero or not. (This code is moved by thetranslator to the end of the explicit INITIAL section before evaluation.) To determinethe value of the velocityXBD (a state), we invoke the RESET operator, which movesall the initial condition values into the state vector. (The argument "NOEVAL"indicates that no evaluation of the derivatives is requested.) The states can then bereferenced by name.

The transfer of initial conditions to states normally takes place only on leaving theINITIAL section. If the RESET operator had not been used, the code in the INITIALsection would have had to refer to the initial condition nameXBDIC rather than thestate nameXBD.

The DISCRETE section ends with a call to LOGD and an optional DEBUG dump.The call to LOGD forces OUTPUT so you can see what is occurring during the run,and it also saves the PREPARE list variables so that any subsequent plots follow thesharp corners produced by the discontinuities.

Figure A13-3 shows the log file of a runtime session. PREPARE and OUTPUT listsare defined, then a START command begins the simulation. Integrations proceed withthe block stuck until 0.22 seconds, at which time the event is activated with a value of0.12587100;i.e., the spring force has exceeded the breakout force (KBBF= 2.50Newtons) by this amount. The event finder backs up to 0.2 seconds and a value of-0.09123350, showing that a zero crossing has really occurred. The window is nowquickly narrowed until it is below the threshold of MINT (1.0E-6 in this program) ofthe current time, at which point the event is noted as having occurred at 0.20833400seconds, which is the most positive edge of the window.

The block continues to slide (STUKB=.FALSE.) until the event is next activated at0.64 seconds with a negative value of -0.01860610. Since STUKB is FALSE, theevent is now defined by velocity crossing zero. The velocity has increased to a positivepeak of just over 0.17 m/sec (as shown in the column PRINT output on page 6 of thelog file) and then decreased until, at the 0.64 second point, the value is negative andthe event finder is again activated. As before, the integration system backs up to 0.62seconds and in four iterations establishes 0.62794300 seconds as the event time and-7.2364E-7 (m/sec), just below zero, as the event value.

This sequence continues, with the block alternately sliding and sticking, until thestopping time of 4.99 seconds is exceeded. The messageTime Limit, generated by theoptional second argument in the TERMT statement, confirms that the run terminatedas expected on the stopping time.

The event description output is fairly extensive and so is considered to be highvolume. It is sent to the PRN logical unit but does not appear on the DIS (low volume)unit, which is usually a terminal. To display the high volume output at a terminal, setHVDPRN (high volume display) to TRUE. If you would like to suppress all eventdescription information, set WEDITG (write event descriptor) to FALSE.




S TITLE='Spring Forced Body Sliding with Friction'SPAREAccumulated cp time 84.91000. Elapsed cp time 0.SET TCWPRN=72,PCWPRN=80 ! Force narrow output widthPREPARE t,xf,xb,xbd,xbdd,sumfb,fbcf,fib,stukbOUTPUT/NCIOUT=10 t,xf,xb,stukbSTART

T 0. XF 0. XB 0.STUKB T

T 0.20000000 XF 0.02408770 XB 0.STUKB T







T 0.20833400 XF 0.02500000 XB 0.STUKB F

T 0.40000000 XF 0.04221640 XB 0.01608330STUKB F

T 0.60000000 XF 0.04990130 XB 0.04473480STUKB F

Event number 1 activated at 0.64000000 with value -0.01860610

Event number 1Window between -1.0000E+37 and 0.64000000Currently at 0.62000000 with value 0.01220850




Figure A13-3. Block on rough surface log file (part 1)



ACSL Runtime Exec Version 6 Level 10B 17-MAR-91 07:15:53 Page 2Spring Forced Body Sliding with Friction


Event occurred at 0.62794300Event 1 with expression value-7.2364E-07 serviced with block 2

T 0.62794300 XF 0.04999860 XB 0.04534030STUKB T

T 0.82000000 XF 0.04411460 XB 0.04534030STUKB T

T 1.02000000 XF 0.02731980 XB 0.04534030STUKB T







T 1.08330000 XF 0.02034020 XB 0.04534030STUKB F

T 1.28000000 XF-0.00376620 XB 0.02627380STUKB F

T 1.48000000 XF-0.02731960 XB-0.01868640STUKB F

Event number 1 activated at 1.62000000 with value 0.00856440Event number 1Window between -1.0000E+37 and 1.62000000Currently at 1.60000000 with value -0.01092700









T 1.61085000 XF-0.03937990 XB-0.02900120STUKB T

T 1.80000000 XF-0.04911430 XB-0.02900120STUKB T

T 2.00000000 XF-0.04755290 XB-0.02900120STUKB T

T 2.20000000 XF-0.03422750 XB-0.02900120STUKB T

T 2.40000000 XF-0.01243470 XB-0.02900120STUKB T







T 2.46813000 XF-0.00400121 XB-0.02900120STUKB F

T 2.66000000 XF 0.01956840 XB-0.01044060STUKB F

T 2.86000000 XF 0.03931420 XB 0.03281440STUKB F





Event number 1 activated at 2.96000000 with value -0.00971345

Event number 1Window between -1.0000E+37 and 2.96000000Currently at 2.94000000 with value 0.01862030




Event number 1Window between 2.95301000 and 2.95301000Currently at 2.95301000 with value -2.0117E-06Event occurred at 2.95301000Event 1 with expression value-2.0117E-06 serviced with block 2

T 2.95301000 XF 0.04540100 XB 0.03931570STUKB T

T 3.14000000 XF 0.04996450 XB 0.03931570STUKB T

T 3.34000000 XF 0.04287650 XB 0.03931570STUKB T

T 3.54000000 XF 0.02518150 XB 0.03931570STUKB T


Event number 1Window between -1.0000E+37 and 3.64000000Currently at 3.62000000 with value -0.17318300Event number 1Window between 3.62000000 and 3.64000000Currently at 3.63443000 with value -3.7169E-04








T 3.63447000 XF 0.01431550 XB 0.03931570STUKB F

T 3.82000000 XF-0.00875077 XB 0.02219980STUKB F

T 4.02000000 XF-0.03138420 XB-0.02306740STUKB F








T 4.14379000 XF-0.04179300 XB-0.03341160STUKB T

T 4.34000000 XF-0.04980660 XB-0.03341160STUKB T

T 4.54000000 XF-0.04576230 XB-0.03341160STUKB T

T 4.74000000 XF-0.03039690 XB-0.03341160STUKB T











T 4.93275000 XF-0.00841154 XB-0.03341160STUKB F

Time LimitT 5.00000000 XF-5.0704E-07 XB-0.03175430

STUKB F

PRINT/NCIPRN=5/ALL

Line T XF XB XBD XBDD SUMFB0 0. 0. 0. 0. 0. 0.5 0.10000000 0.01243450 0. 0. 0. 1.24345000

10 0.20000000 0.02408770 0. 0. 0. 2.4087700015 0.28000000 0.03235280 0.00181926 0.05813630 1.02428000 3.0242800020 0.38000000 0.04081690 0.01281130 0.15637500 0.72237900 2.7223800025 0.48000000 0.04671640 0.03037580 0.17337400 -0.45262700 1.5473700030 0.58000000 0.04968060 0.04357050 0.07246580 -1.42523000 0.5747680035 0.66000000 0.04980670 0.04534030 0. 0. 0.4466380040 0.76000000 0.04714960 0.04534030 0. 0. 0.1809250045 0.86000000 0.04152980 0.04534030 0. 0. -0.3810460050 0.96000000 0.03330070 0.04534030 0. 0. -1.2039600055 1.06000000 0.02297910 0.04534030 0. 0. -2.2361200060 1.14000000 0.01364770 0.04424790 -0.04495110 -1.03755000 -3.0375500065 1.24000000 0.00125665 0.03382300 -0.16630400 -1.17348000 -3.1734800070 1.34000000 -0.01121340 0.01244810 -0.24428100 -0.24400900 -2.2440100075 1.44000000 -0.02297890 -0.01120710 -0.20725900 0.92645800 -1.0735400080 1.54000000 -0.03330050 -0.02617820 -0.08453230 1.33004000 -0.6699570085 1.62000000 -0.04007820 -0.02900120 0. 0. -1.1077000090 1.72000000 -0.04625380 -0.02900120 0. 0. -1.7252600095 1.82000000 -0.04952300 -0.02900120 0. 0. -2.05218000

100 1.92000000 -0.04968060 -0.02900120 0. 0. -2.06793000105 2.02000000 -0.04671650 -0.02900120 0. 0. -1.77153000110 2.12000000 -0.04081710 -0.02900120 0. 0. -1.18159000115 2.22000000 -0.03235300 -0.02900120 0. 0. -0.33517500120 2.32000000 -0.02185600 -0.02900120 0. 0. 0.71452100125 2.42000000 -0.00998576 -0.02900120 0. 0. 1.90155000130 2.50000000 -2.5352E-07 -0.02870160 0.02195290 0.85915500 2.85915000135 2.60000000 0.01243420 -0.02100150 0.13992400 1.27361000 3.27361000140 2.70000000 0.02408740 -0.00149632 0.23508400 0.44083100 2.44083000145 2.80000000 0.03422710 0.02206160 0.21160400 -0.88924700 1.11075000150 2.90000000 0.04221620 0.03724060 0.07974090 -1.54231000 0.45769100155 2.98000000 0.04671630 0.03931570 0. 0. 0.74006100160 3.08000000 0.04968050 0.03931570 0. 0. 1.03648000165 3.18000000 0.04952310 0.03931570 0. 0. 1.02074000170 3.28000000 0.04625400 0.03931570 0. 0. 0.69382800175 3.38000000 0.04007860 0.03931570 0. 0. 0.07628540





Line T XF XB XBD XBDD SUMFB180 3.48000000 0.03138490 0.03931570 0. 0. -0.79308600185 3.58000000 0.02071920 0.03931570 0. 0. -1.85966000190 3.66000000 0.01121390 0.03913620 -0.01655160 -0.78395700 -2.78396000195 3.76000000 -0.00125610 0.03226010 -0.13045200 -1.28639000 -3.28639000200 3.86000000 -0.01364720 0.01341340 -0.23388900 -0.58911900 -2.58912000205 3.96000000 -0.02518080 -0.01090990 -0.22912500 0.68747100 -1.31253000210 4.06000000 -0.03513220 -0.02877580 -0.11450300 1.42162000 -0.57838300215 4.14379000 -0.04179300 -0.03341160 0. 1.16186000 -0.83814200220 4.24000000 -0.04714940 -0.03341160 0. 0. -1.37378000225 4.34000000 -0.04980660 -0.03341160 0. 0. -1.63951000230 4.44000000 -0.04933440 -0.03341160 0. 0. -1.59228000235 4.54000000 -0.04576230 -0.03341160 0. 0. -1.23507000240 4.64000000 -0.03931480 -0.03341160 0. 0. -0.59032000245 4.74000000 -0.03039690 -0.03341160 0. 0. 0.30146100250 4.84000000 -0.01956920 -0.03341160 0. 0. 1.38424000255 4.93275000 -0.00841154 -0.03341160 0. 0. 2.50000000

Line FBCF FIB STUKB0 0. -2.50000000 T5 -1.24345000 -1.25655000 T

10 -2.40877000 -0.09123350 T15 -2.00000000 0.05813630 F20 -2.00000000 0.15637500 F25 -2.00000000 0.17337400 F30 -2.00000000 0.07246580 F35 -0.44663800 -2.05336000 T40 -0.18092500 -2.31908000 T45 0.38104600 -2.11895000 T50 1.20396000 -1.29604000 T55 2.23612000 -0.26387900 T60 2.00000000 -0.04495110 F65 2.00000000 -0.16630400 F70 2.00000000 -0.24428100 F75 2.00000000 -0.20725900 F80 2.00000000 -0.08453230 F85 1.10770000 -1.39230000 T90 1.72526000 -0.77474500 T95 2.05218000 -0.44782000 T

100 2.06793000 -0.43206600 T105 1.77153000 -0.72847200 T110 1.18159000 -1.31841000 T115 0.33517500 -2.16482000 T120 -0.71452100 -1.78548000 T125 -1.90155000 -0.59845200 T130 -2.00000000 0.02195290 F135 -2.00000000 0.13992400 F140 -2.00000000 0.23508400 F145 -2.00000000 0.21160400 F150 -2.00000000 0.07974090 F155 -0.74006100 -1.75994000 T160 -1.03648000 -1.46352000 T165 -1.02074000 -1.47926000 T170 -0.69382800 -1.80617000 T175 -0.07628540 -2.42371000 T180 0.79308600 -1.70691000 T185 1.85966000 -0.64034400 T190 2.00000000 -0.01655160 F195 2.00000000 -0.13045200 F200 2.00000000 -0.23388900 F




Data is printed at the end of the run by PRINT/ALL. The volume of output is reducedby printing only every fifth line that was logged (/NCIPRN=5). Note that the firstthree lines occur at times 0.0, 0.1, and 0.2, but the fourth line is at 0.28 because of theextra data point logged at the event time around 0.208 seconds. The output reductionfactor is applied to every data record on the PREPARE list that is saved, irrespectiveof the means by which it is placed on the file. In this case, each record is read andevery fifth one printed. Another shift is seen between lines 30 and 35 where timeT is0.58 and 0.66 seconds, respectively. Occasionally the round values ofT are replacedby all digits as at line 215 where the output line happens to coincide with a LOGD callat the event time.

The PRINT output includes the logical variableSTUKB, which alternates betweenTRUE (T) and FALSE (F).

Figure A13-4 shows several variables in strip plot form. The first line is the force dueto Coulomb friction, and the discontinuities can be clearly seen where the breakoutforce (KBBF=2.5 Newtons) jumps to the sliding force (KBSF=2.0 Newtons).

Figure A13-5 shows the block positionXBand the forcing deflectionXF against timein a line plot (CALPLT=.TRUE.). Figure A13-6 shows the zero crossing functionFIB.When this function crosses or touches the zero line, an event occurs. The sharpdiscontinuities in slope in the lower part of the curve are due to the action of theabsolute value operator as the friction force reverses sign. The smooth curves betweenzero crossings are velocity, so the units ofFIB change from Newtons to m/sec atdifferent regions in state space.


Line FBCF FIB STUKB205 2.00000000 -0.22912500 F210 2.00000000 -0.11450300 F215 2.00000000 1.8906E-07 T220 1.37378000 -1.12622000 T225 1.63951000 -0.86049200 T230 1.59228000 -0.90771700 T235 1.23507000 -1.26493000 T240 0.59032000 -1.90968000 T245 -0.30146100 -2.19854000 T250 -1.38424000 -1.11576000 T255 -2.50000000 1.4305E-06 F

S STRPLT=.T.,CALPLT=.F.S PSFSPL=0.5,XINSPL=10PLOT/XTAG='(sec)'Drawing plot number 1PLOT fib,xb,xbd,xbdd,fbcfDrawing plot number 2S CALPLT=.T.,STRPLT=.F.,PSFCPL=0.60PLOT xb/TAG='body position (m)' &

, xf/TAG='forcing deflection (m)'/TYPE=100Drawing plot number 3SET TITLE(41)='events occur at zero crossings'PLOT fib/TAG='- phi function'/TYPE=00/CHAR='*' Drawing plot number 4SPAREAccumulated cp time 96.26000. Elapsed cp time 11.35000QUIT




Figure A13-4. Block on rough surface, selected variables

Figure A13-5. Block and spring deflection Figure A13-6. Zero crossing function



14. Linearanalysis example

The linear analysis operations are applied to a system made up from a third order plantwith a compensator as shown in the block diagram in Figure A14-1. This example istaken from Truxal'sControl System Synthesispp. 259-266[7]. It shows how to addcontrol inputs and obtain both open loop and closed loop frequency responses,including Bode and root locus plots. The ACSL program is listed in Figure A14-2.

As the block diagram shows, the feedback path is completed through an unknown gainK and added constant termsEZandUZ in the forward path. These terms are initializedto zero but used as control inputs in addition to the referenceRso that the open loopresponse can be determined for either the complete system, the plant alone, or thecompensator alone by selecting the appropriate input/output pair and changing thegain K. For instance, the open loop transfer function over the complete controller/plantcascaded system is from EZ to Y with the gain K set to zero. The plant alone is fromUZ to Y with K also set to zero. The full closed loop is from R to Y with K nonzero.In fact, the same closed loop response, except for a gain factor, can also be obtainedfron EZ to Y with K nonzero.

Figure A14-3 lists the log file from a runtime session. The open loop response isobtained first. The loop gainK is set to zero, a title is specified, and the line type forthe second curve on subsequent Bode plots is set to be dotted. A START commandmoves values into the state variables. The model stopping time (TSTP) is zero, so therun terminates as soon as the code has been evaluated at time zero.

SET k=0, TITLE(41)='Open Loop Response', SLTFPL=100START

Next we check the eigenvalues of the system:

ANALYZE /EIGEN

The output from this command shows the real and imaginary roots, the frequency, andthe damping.


1 0.2 -1.60142000 +/-0.99707700 1.886460 0.8489054 -8.000000005 -20.0000000

Figure A14-1. Linear analysis example block diagram

A. ACSL Example Programs A14. Linear analysis example


We then establish a list of control variables (R, EZ, andUZ) and observable variables(YandU), and turn on /LIST so that details of the /ZEROS and /BODE operations arewritten out in the log file. To get the complete system open loop responseY/EZ,designate the control index (CINDEX) as 2 and the observable index (OINDEX) as 1(its default):

ANALYZE /CONTROL=r,ez,uz/OBSERVE=y,u/LIST=.T.ANALYZE /CINDEX=2

The poles and zeros are extracted with the /ZEROS command:

ANALYZE /ZEROSNumber of poles i s 5 - Number of zeros is 2Fractional gain is 1.00000000 with an exponent of 0Complex zeros in ascending order

REAL1 -1.000000002 -1.00000000

PROGRAM test bode

!-----------------------control analysis example taken from! control system synthesis by truxal pp 259-266

! plant model

! 1.0! ----------------------! s*(s**2 + 3.2s + 3.56)

! compensator model

! k*(s + 1)**2! --------------! (s + 8)*(s + 20)

! find the value of k to give reasonable closed loop response

!-----------------------define acsl system variablesALGORITHM ialg = 3MAXTERVAL maxt = 0.05CINTERVAL cint = 0.10NSTEPS nstp = 1

!-----------------------define model related parametersCONSTANT p1 = 8.0, p2 = 20.0, z1 = 1.0, z2 = 1.0, r = 0.0 &

, a2 = 0.281, a1 = 0.900, k = 0.0, kt = 1.0, tstp = 0.0!-----------------------define dummy control inputsCONSTANT ez = 0.0, uz = 0.0

!-----------------------planty = CMPXPL(a2, a1, a2*INTEG(u + uz, 0.0))!-----------------------controller/compensatoru = LEDLAG(1.0/z1, 1.0/p1, LEDLAG(1.0/z2, 1.0/p2 &

, (k*e + kt*ez)*z1*z2/(p1*p2)))!-----------------------error terme = r - y

TERMT(t .GE. tstp, 'Time Limit')

END

Figure A14-2. Linear analysis example program

A14. Linear analysis example A. ACSL Example Programs



SET TITLE='Frequency Response/Root Locus Example'PREPARE t,y,u,eOUTPUT/NCIOUT=50 t,y,eSET k=0,TITLE(41)='Open Loop Response',SLTFPL=100START ! Give states values

T 0. Y 0. E 0.ANALYZE /EIGEN ! List Eigen valesComplex eigenvalues in ascending order

REAL IMAGINARY FREQUENCY DAMPING1 0.2 -1.60142000 +/-0.99707700 1.886460 0.8489054 -8.000000005 -20.0000000

ANALYZE /CONTROL=r,ez,uz/OBSERVE=y,u/LIST=.T.ANALYZE /CINDEX=2ANALYZE /ZEROSNumber of poles is 5 - Number of zeros is 2Fractional gain is 1.00000000 with an exponent of 0Complex zeros in ascending order

REAL1 -1.000000002 -1.00000000

ANALYZE /HERTZ=.F./FREQMN=0.1/FREQMX=1000.0ANALYZE /BODENumber of poles is 5 - Number of zeros is 2Fractional gain is 1.00000000 with an exponent of 0Complex zeros in ascending order

REAL1 -1.000000002 -1.00000000

Frequency Phase (deg) Gain (db)0.10000000 -84.7386000 -35.03340000.20000000 -79.7027000 -40.83480000.30000000 -75.0915000 -44.00780000.37500000 -72.0066000 -45.61250000.46875000 -68.6767000 -47.06520000.58593800 -65.4018000 -48.32060000.73242200 -62.7065000 -49.34390000.91552700 -61.3450000 -50.13470001.37329000 -64.9686000 -51.23120001.54495000 -67.8517000 -51.57560001.73807000 -71.5338000 -51.98270001.95533000 -75.9104000 -52.47610002.19975000 -80.8424000 -53.07130002.47472000 -86.1841000 -53.77500002.78405000 -91.8088000 -54.58620002.95806000 -94.7826000 -55.04400003.14294000 -97.7978000 -55.52770003.33937000 -100.848000 -56.03650003.54808000 -103.930000 -56.56930003.76984000 -107.040000 -57.12540004.00545000 -110.179000 -57.70410004.25579000 -113.345000 -58.30490004.52178000 -116.541000 -58.92750004.80439000 -119.766000 -59.57190005.10466000 -123.022000 -60.2381000

Figure A14-3. Frequency analysis log file (part 1)



ACSL Runtime Exec Version 6 Level 10B 18-MAR-91 16:56:06 Page 2Frequency Response/Root Locus Example Open Loop Response

5.42371000 -126.309000 -60.92620005.76269000 -129.627000 -61.63660006.12285000 -132.976000 -62.36970006.50553000 -136.355000 -63.12580006.91213000 -139.762000 -63.90550007.34414000 -143.195000 -64.70930007.80315000 -146.652000 -65.53760008.29084000 -150.128000 -66.39090008.80902000 -153.620000 -67.26970009.35958000 -157.123000 -68.17410009.94456000 -160.633000 -69.104700010.5661000 -164.144000 -70.061600011.2265000 -167.652000 -71.044900011.9281000 -171.150000 -72.054900012.6736000 -174.633000 -73.091500013.4657000 -178.094000 -74.154700014.3074000 -181.529000 -75.244400015.2016000 -184.930000 -76.360300016.1517000 -188.293000 -77.502300017.1611000 -191.610000 -78.669900018.2337000 -194.876000 -79.862700019.3733000 -198.085000 -81.080200020.5841000 -201.231000 -82.321900021.8707000 -204.309000 -83.586900023.2376000 -207.314000 -84.874600024.6899000 -210.242000 -86.184100026.2330000 -213.088000 -87.514400027.8726000 -215.849000 -88.864700029.6146000 -218.521000 -90.233800031.4656000 -221.102000 -91.620900033.4322000 -223.591000 -93.024700035.5217000 -225.985000 -94.444300037.7418000 -228.285000 -95.878600040.1006000 -230.491000 -97.326400042.6069000 -232.602000 -98.786800045.2698000 -234.620000 -100.25900048.0992000 -236.546000 -101.74200051.1054000 -238.381000 -103.23400054.2995000 -240.129000 -104.73500057.6932000 -241.791000 -106.24500061.2990000 -243.370000 -107.76100065.1302000 -244.868000 -109.28500069.2009000 -246.289000 -110.81400077.8510000 -248.840000 -113.80000087.5824000 -251.131000 -116.80200098.5302000 -253.184000 -119.819000110.846000 -255.022000 -122.845000124.702000 -256.665000 -125.881000140.290000 -258.131000 -128.923000157.826000 -259.439000 -131.971000197.283000 -261.540000 -137.757000246.604000 -263.226000 -143.553000308.254000 -264.578000 -149.356000462.382000 -266.383000 -159.909000693.572000 -267.588000 -170.4700001000.00000 -268.327000 -180.002000

Drawing plot number 1




A frequency sweep from 0.1 to 1000 rad/s by setting the units with /HERTZ andminimum and maximum frequencies. The resulting Bode plot for the open loopsystem is shown in Figure A14-4 with phase as a solid line and gain dotted.

ANALYZE /HERTZ=.F./FREQMN=0.1/FREQMX=1000ANALYZE /BODE

The log file shows a long list of frequency values and corresponding phase and gainpoints as the frequency is swept from /FREQMN to /FREQMX. This output resultsfrom /LIST being set to TRUE. It can be eliminated by setting /LIST to FALSE priorto invoking /BODE.

Figure A14-5 is a root locus plot of the open loop system obtained by the followingcommands setting the plot scales and turning off /LIST:

ANALYZE /IMAGMN=-10/IMAGMX=10/REALMN=-10/REALMX=0.0ANALYZE /LIST=.F./ROOTLOC

If the boundaries of the plot are not specified, the area will be sized from the poles(-20 to zero on the real axis) and -1 to +1 on the imaginary axis, resulting in asomewhat distorted view. Note the scales chosen for this plot have a real axis extent of10 and an imaginary axis of 20, so angles still cannot be read accurately.

The loci from the two complex poles at -1.6+/-j meet at the real axis at -2.869 and thenbreak away again at 3.83 to finally leave towards the asymptotic slopes of +/-60degrees. Truxal on page 260 shows no breakaway points!

ACSL Runtime Exec Version 6 Level 10B 18-MAR-91 16:56:06 Page 3Frequency Response/Root Locus Example Open Loop Response

ANALYZE /REALMN=-10/REALMX=0.0/IMAGMN=-10/IMAGMX=10ANALYZE /LIST=.F./ROOTLOCUSNumber of poles is 5 - Number of zeros is 2Drawing plot number 2SET k=1438,TITLE(41)='Closed Loop Response'ANALYZE /ZEROS/EIGENNumber of poles is 5 - Number of zeros is 2Fractional gain is 10.0000000 with an exponent of -1Complex zeros in ascending order

REAL1 -1.000000002 -1.00000000


1 -0.650551002 -1.350870003 -2.62156000 +/-7.83751000 8.264330 0.3172145 -23.9583000

ANALYZE /CINDEX=1/BODENumber of poles is 5 - Number of zeros is 2Drawing plot number 3SET DTCFPL=.T.,YINFPL=6,PSFFPL=0.9ANALYZE /bodeNumber of poles is 5 - Number of zeros is 2Drawing plot number 4QUIT




If /LIST had been true, position, gain, and step length would have been printed outduring the locus tracking.

For the control system, Truxal picks a loop gain of 1438, which corresponds toprincipal roots of 2.62+/-j7.83. This corresponds to a damping of 0.316 at an angle of71 degrees (arctan 3). These can be tested by setting the value ofK to 1438 and thenasking for the eigenvalues (which confirm the gain calculation) with the commands:

SET k=1438ANALYZE /EIGEN

The closed loop Bode plot is obtained by changing the control toR, leaving the gainKat 1438, as follows:

SET TITLE(41)='Closed Loop Response'ANALYZE CINDEX=1/BODE

Figure A14-6 is the closed loop Bode plot. Again, gain is shown dotted. To see theother form of Bode plots, the system symbol DTCFPL (draw two curves) is set TRUE,the nominal Y axis length is changed to six, and a plot scale factor (PSFFPL) of 0.9 isspecified so that the plot fits on the screen for monitoring purposes;i.e.,

SET DTCFPL=.T.,YINFPL=6,PSFFPL=0.9ANALYZE /BODE

The control system can be checked by running the model and plotting a time history ofthe plant dynamics. The program stopping time is set to 4.99 sec, K to 1438, and R to1 (to excite the system).

In the linear analysis, when time is not a consideration and thus no integrations arebeing calculated, the Euler integration routine (IALG = 3) is adequate. For runs overtime, however, one of the Runge-Kutta routines is preferred. A communicationinterval of 0.1 results in a ragged plot (i.e., not enough data points are being logged),so CINT in reduced to 0.01. Figure A14-8 is the plot resulting from the followingcommands:

SET tstp=4.99,k=1438,r=1,ialg=4,cint=0.01SET TITLE(41)='Time response with K=1438, R=1'

Figure A14-4. Open loop Bode plot Figure A14-5. Open loop root locus plot



Figure A14-6. Closed loop Bode plot Figure A14-7. Bode plot with separate axes

Figure A14-8. Time plot of linear analysis example



15. Tank withBoiling Benzene

This model, as shown in Figure A15-1, represents the dynamics of a boiling liquidwhere the inlet flow rate is controlled through a PI controller and the outlet flow rate isset to oscillate slowly to force the system. In practice, the outlet vapor flow would becontrolled by the requirement of the downstream component or unit operation.

This example demonstrates how the vapor/liquid equilibrium can be modeled as adifferential-algebraic system using the implicit operators IMPLC and IMPVC. Theparameters in the model are taken to represent benzene.

15.1 Equations

The equations describing the behavior inside the tank are derived from conservation ofmass and conservation of enthalpy. The total mass (units of Kg) in the tank is obtainedby integrating the difference between the inlet mass flow rate and the outlet vapormass flow rate.

mTOTAL = ∫ ( fIN − fOUT ) dt

Enthalpy The total enthalpy (units of kJ) is similarly obtained by integrating the differencebetween what is carried in in the liquid stream and what is carried out by the vaporstream and adding what heat is supplied from an external source.

hTOTAL = ∫ ( fIN cL TIN − fOUT ( cL TL + lHEAT ) + q ) dt

Figure A15-1. Boiling vessel

A15. Tank with Boiling Benzene A. ACSL Example Programs


HerecL is the specific heat of both liquid and vapor,TIN (°C) is the inlet liquidtemperature ,TL is the temperature inside the tank,lHEAT (kJ/kg) is the latent heat ofvaporization andq (kJ/sec) is the heat flux from external sources – assumed constanthere. We assume one temperatureTL for both liquid and vapor phases inside the tankand have to evaluate the enthalpy of the liquid and vapor phases separately.

hL = mL cL TL

hV = mV ( cL TL + lHEAT )

Now the total enthalpy can also be written down as the sum of these two separateenthalpies.

hTOTAL = hL + hV

Tank temperature We can use this relationship to solve for the tank temperatureTL. Since thetemperature occurs only linearly, we could solve directly for this:

TL =hTOTAL − mV lHEAT

( mL + mV ) cL

However, we intend to use the ACSL implicit operator to find the tank temperature byexpressing the fact that the difference between total enthalpy and the sum of liquid andvapor enthalpies should be zero.

RESIDUAL = hTOTAL − ( hV + hL ) = 0

Nonlinear functions The real requirement for an equation solver comes when the relationship is nonlinear.In this case the liquid and vapor specific heats should be considered to be different andnonlinear functions of temperature.

Vapor pressure The mass balance equation is a little more complicated and leads to a nonlinearequation due to the exponential variation of vapor pressure with temperature. Thevapor pressure above the liquid can be calculated using the Antoine equation.

pV = exp( a − b ⁄ ( c + TL ) )

Making a somewhat broad assumption about the perfect gas law, we get:

vV pV = mV r ( T0 + TL )

wherevV (m3) is the volume of the vapor phase,mV (kg) is the mass of the vapor,r isthe gas constant in units per kilogram (rather than per mole), andT0 is the 0 degreeCentigrade value in Kelvin (273.16°K).

Constraint Since density (dV) in the vapor is given by:

dV = mV ⁄ vV

we can write the constraint equation:

pV − dV r ( T0 + TL ) = 0

A. ACSL Example Programs A15. Tank with Boiling Benzene


We use this to adjust the mass in the vapormV until the constraint on pressure issatisfied. Note that we can't just solve the above formV sincemV appears in the vaporenthalpy equation that determines temperature andpV depends in a nonlinear fashionon temperature.

Controller The other equations in the model are concerned with the level controller and outletvalve flow. The level controller is implemented as a PI (proportional plus integral)control action as follows:

c1P = cG ( mLIC − mL )

c1I = ∫ c1PtI

dt

fIN = c1P + c1I

The namesC1P andC1I are used because the nameCL is already the specific heat of theliquid. Here we assume thatcG contains the tank area as well as the proportional gainconstant since the error term is developed in terms of the difference between initialliquid mass (mLIC started at a mass such that the liquid occupied half the tank volume)and current liquid mass,mL. The integral action is obtained by integrating theproportional action after dividing by the reset time constant,ti. These two flowcommands are assumed to be met exactly by the inlet flow controller so that we canobtain the inlet flow by summing them. In actual practice, the controller dynamics and,in particular, valve travel limits should be considered in any realistic simulation.

Outlet flow rate The outlet flow rate is considered to be just a valve, the opening of which follows asine wave. The valve position is given by:

xV = xVZ + xVA sin ( xVW t )

The flow through the valve depends on this opening and the square root of thepressure drop from the tank internal pressurepV to the downstream of outlet pressure,pOUT, assumed here to be constant.

fOUT = kV xV √pV |( pV − pOUT )| SGN ( pV − pOUT )

15.2 ACSL program

Figure A15-2 lists the program that contains the equations of the previous section.

Program control At the beginning of the program, ACSL system constants are specified. These set thecommunication interval (CINT) to half a second and the integration algorithm (IALG)to second order Runge-Kutta (4).

Model constants Next comes the physical parameters and initial conditions. We want to establish asteady state condition here by setting an inlet flow rate (17.5 kg/sec) and vesselpressure (pVIC = 4.7 bars). From this we calculate the other initial conditions, leadingup to total mass and total enthalpy.



program boiler (constants represent benzene)

!------------------------ACSL system constantscinterval cint = 0.5 ! communication intervalmaxterval maxt = 0.5 ! maximum step sizealgorithm ialg = 4 ! second order rk algorithmnsteps nstp = 1 ! no influence from cint!------------------------model constantsconstant finic = 17.5 ! inlet flow of liquid (kg/s)constant tin = 75.0 ! inlet temperature (deg C)constant dl = 874.0 ! density of liquid (kg/m**3)constant mwt = 78.0 ! molecular weightconstant lheat = 387 0 ! latent heat of vaporization (constant cl = 1.26 ! specific heat of liquidconstant vol = 10.0 ! vessel size (m**3)constant pout = 2.0 ! pressure (bars)constant a = 9.2807 ! vapor pressure constantsconstant b = 2788.51 !constant c = 220.79 !constant ti = 500.0 ! controller data (sec)constant cg = 0.005 !constant pvic = 4.7 ! initial pressure in vessel (bars)constant tzero = 273.16 ! zero cintigrade in kelvinconstant xvz = 0.7 ! manual valve positionconstant xva = 0.3 ! valve amplitudeconstant xvw = 0.5 ! valve frequency (rad/sec)

initial

!-----------------------gas constant (1/kg)r = 8.314/mwt!-----------------------initial temperature (deg C)tlic = b/(a - log(pvic)) - c!-----------------------heat flux (kJ/sec)q = finic*(cl*(tlic - tin) + lheat)!-----------------------liquid and vapor volumes (m**3)volv = vol/2.0voll = vol - volv!-----------------------liquid and vapor masses (kg)mlic = dl*vollmvic = pvic*volv/(r*(tlic + tzero))!-----------------------internal liquid and vapor enthalpies (kJ)hlic = mlic*cl*tlichvic = mvic*(cl*tlic + lheat)htic = hlic + hvicmtic = mlic + mvic!-----------------------valve datakv = finic/(xvz*sqrt(pvic*(pvic - pout)))

endderivative

!-----------------------valve opening as drive to systemxv = xvz + xva*sin(xvw*t)!-----------------------total mass holdup of vessel contents (kg)mtotal = integ(fin - fout, mtic)!-----------------------total enthalpy of vessel contents (kJ)htotal = integ(fin*cl*tin + q - fout*(cl*tl + lheat), htic)!-----------------------level controller on liquid streamc1p = cg*(mlic - ml)c1i = integ(c1p/ti, finic)fin = c1i + c1p!-----------------------vapor valve - manualfout = kv*xv*sign(sqrt(abs(pv*(pv - pout))), pv - pout)

Figure A15-2. ACSL program of boiler (part 1)



Vessel temperature First we can calculate the vessel temperature, knowing the pressure, by inverting thevapor pressure equation.

TLIC = b ⁄ ( a − log ( pVIC ) ) − c

Heat input Knowing this temperature, we now can calculate how much heat has to be added to theinlet specified flow rate in order to turn it all into vapor.

q = fINIC ( cL ( TLIC − TIN ) + lHEAT )

Initial volumes We divide the tank into two halves for the initial liquid and vapor volumes:

volv = vol ⁄ 2voll = vol − volv

Liquid density The density of the liquid is assumed fixed (dL) so the mass of liquid is:

mLIC = dL volv

Vapor mass Knowing the vapor pressure, volume and the gas law, vapor mass is then given by:

mVIC = pVIC volv ⁄ ( r (TLIC − TZERO) )

!-----------------------liquid and vapor enthalpies (kJ)hl = ml*cl*tlhv = mv*(cl*tl + lheat)!-----------------------liquid mass and vapor volume (m**3)ml = mtotal - mvvolv = vol - ml/dl!-----------------------vapor density (kg/m**3)dv = mv/volv!-----------------------vapor pressure (bars)pv = exp(a - b/(c + tl))!-----------------------equilibrium vapor mass obtained by! adjusting the mass of vapor until the pressure due to the! contained mass matches the liquid vapor pressureresidmv = pv - dv*r*(tl + tzero)mv = implc(residmv, mvic)!-----------------------equilibrium liquid temperature adjusts! the temperature until the sum of the liquid and vapor enthalpies! match the total enthalpy in the systemresidtl = htotal - hl - hvtl = implc(residtl, tlic)!-----------------------stopping conditionconstant tstp = 99.99termt(t .ge. tstp, 'Stopped on time')

end ! of derivativeend ! of program

Figure 2. ACSL program of boiler (part 2)



Enthalpy Knowing the masses and temperatures, enthalpies can be written:

hLIC = mLIC cL tLIC

hVIC = mVIC+ ( cL tLIC + lHEAT )

Remember one kilogram of vapor holds the enthalpy due to its temperature and alsothe latent heat of vaporization (or how it got to be vapor).

Total enthalpy Finally we have the total enthalpy, which is needed for the initial condition on theintegrator:

hTIC = hLIC + hVIC

Total mass The total mass required similarly for the initial condition on the mass integrator.

mTIC = mLIC + mVIC

Outlet valuecoefficient

The last thing in the INITIAL section is the calculation of the outlet valve coefficient,kV. Since we know that the vapor flow rate in steady state must match the inlet flowrate (kg/sec), we calculate a valve coefficient to give us this known flow rate at thepressure inside the vessel.

kV = fINIC ⁄ ( xvz √pVIC |( pVIC − pOUT )| )

In practice, the valve opening should be calculated but since we don't know which sizevalve to use yet, we may as well calculate a nominal valve coefficient desired at thenominal valve opening ofxvz (70%).

DERIVATIVE The code in the DERIVATIVE section follows the equations of the previous section.The only thing of note is the specification of the implicit constraints. We first specifythe residual for the vapor mass adjuster by:

residmv = pv - dv*r*(tl + tzero)

Residual The implicit operator drives this residual to zero.

mv = IMPLC(residmv, mvic)

There is no need to calculate the residual specifically since the first argument of theIMPLC operator can be an expression. The previous two statements could have beencombined into:

mv = IMPLC(pv - dv*r*(tl - tzero), mvic)

In this form, however, there is no variable name for the residual so it is not availablefor plotting. We want the residual to have a name so we can show that it really is keptclose to zero.

Liquid temperature Similarly, the liquid temperature is obtained from:

residtl = htotal - hl - hvtl = IMPLC(residtl, tlic)



Steady state Our problem with calculating a steady state condition is that we don't know whatnumbers to use for total mass and total enthalpy. These are the integrators, but if wesay we want to start with an operating pressure of 4.7 bars and an inlet flow rate of17.4 kg/sec, we don't have much hope of finding the initial conditionsmTIC andhTIC

except by the calculations just outlined in the INITIAL section.

There is another way, though, that uses the ACSL trim (or steady state finder). Theidea is to adjust the state variables until the derivatives go to zero, this being defined assteady state. In this example, we have three integrators: one for total mass, one fortotal enthalpy, and one for the PI controller. Since this controller determines inlet flowrate that we want to fix, we freeze this integrator so it won't be adjusted. The followingruntime command finds the steady state condition.

ACSL> ANALYZE /FREEZE=cli /TRIM

This adjusts the total enthalpy and total mass until the rates go to zero. Unfortunately,in doing this, the liquid mass itself is adjusted so that the PI controller has aproportional component sincemL isn't equal tomLIC.

Controls andobservables

The way around this is to recognize that we also need to adjust the heat flux to achievea steady state. By adding this as a /CONTROL, we make it adjustable. At the sametime we must specify a matching /OBSERVE variable to be driven to zero. This valueshould be the error term in the PI controller or its equivalent,c1P, which isproportional to the difference betweenmL andmLIC. The sequence of runtimecommands now is:

ACSL> ANALYZE /FREEZE=cli /CONTROL=q /OBSERVE=c1pACSL> ANALYZE /TRIM

This finds a steady state operating point of vapor mass 0.53 kg and tank temperature139.8°C.

15.3 Results

Figure A15-3 plots the results of a sample run and Figure A15-4 lists the output.

System symbols First we set the title to identify the simulation. Next we set system variables NPBPRN(no page break) and DCVPRN (display changed value). NPBPRN ensures that nopage headers appear in the log file, making it easier to fit the listing into a document.DCVPRN, set to TRUE, says to display both the original value as well as the newvalue when anything is changed by a runtime SET statement.

Data recording The next two statements establish the data recording conditions during the simulationrun. PREPARE/ALL places all the calculated variables (those on the left hand side ofan equal sign) on the prepare list. For the OUTPUT statement we choose time (T) andall the variables starting with RESID – the wild card specification matches theresiduals for the mass of vapor (RESIDMV) and the liquid temperature (RESIDTL).

Stop time Next we change the stop time from 99.99 seconds to 19.99 seconds. BecauseDCVPRN is set to true, both the old and the new values of TSTP are written out andwe can see clearly the consequences of the SET statement.



Execute run Finally we get to actually run the simulation with a START command. The OUTPUTvariables are listed every communication interval of 0.5 seconds. (To conserve space,part of the listing has been deleted with a text editor.) The output shows that theresiduals are in the range 1.0e-7 to 1.0e-12 (the model has been translated with globaldouble precision) even though the nominal allowable errors are set to the normal1.0e-4 or 0.01%. Remember that the allowed error gives the minimum distance thetwo unknowns MV and TL are from their true solutions, not on the value of theresidual!

Plot After the run, we plot the valve opening XV, pressure PV, and outlet flow rate FOUTas shown in Figure A15-3. As the valve opens, the flow rises but cools off the contentsof the tank, reducing the vapor pressure, so that the flow out starts to turn down beforethe peak valve opening.

Steady state The next section in the log file after the PLOT command demonstrates the use of theTRIM action to find a steady state. Since ANALYZE/TRIM starts by moving theinitial condition vector onto the state vector, the system will automatically be inequilibrium. We went to great trouble in the INITIAL section to calculate these steadystate values and they remain in the initial condition vector. In order to give the TRIMroutine something to work on, we change the initial condition on total enthalpy, HTIC,and also on the total mass MTIC. Total enthalpy for equilibrium was 771939.693 andis changed to 700,000 kJ; total mass was 4370.53388 and is changed to 4000 kg. Weset the condition to hold the control integrator constant (/FREEZE=C1I) and add heatflux Q as a control variable and proportional error as an observable (to be driven tozero) by:

ACSL> ANALYZE /CONTROL=Q /OBSERVE=C1P

Figure A15-3. Valve position, vessel pressure, and vapor flow of boiler



The internal workings of the TRIM action are made visible for this listing by adding/LIST=.T. at the end.

Now with the stage set, the following:

ACSL> ANALYZE /TRIM

starts to adjust the five unfrozen states and controls to drive the derivatives andobservables to zero. Note that the algebraic variables are added to the list of statevariables so that there is one big vector of five quantities to be driven to zero. In this,the residuals act just like derivatives.

After five iterations, the steady state has been found. A DISPLAY/ALL shows thissteady state with the derivatives and residuals between 8.0e-4 and 1.0e-8. Theimportant quantities are the last four states (the first one C1I is frozen) and theproportional error C1P. (The dump has been edited to remove extraneous variables.)

set npbprn=.t. ! no page breakset title='Pressure/flow in boiling vessel'set dcvprn=.t. ! display changed variablesprepare/all ! save all calculated variablesoutput t,resid* ! short output list of time and all residualsset tstp=19.99 ! shorten run time (note old value before change)

TSTP (Old value) 99.9900000 (New value) 19.9900000startJacobian evaluated. Condition number is 0.41422100

T 0. RESIDMV 1.3323D-15 RESIDTL-2.8422D-12T 0.50000000 RESIDMV 6.0075D-08 RESIDTL-1.9393D-08T 1.00000000 RESIDMV 6.7200D-07 RESIDTL-2.3933D-07T 1.50000000 RESIDMV 1.8011D-08 RESIDTL-6.4011D-09T 2.00000000 RESIDMV 5.5301D-09 RESIDTL-1.4060D-09

...T 17.5000000 RESIDMV 1.3378D-12 RESIDTL 5.2580D-12T 18.0000000 RESIDMV-7.1240D-09 RESIDTL 2.0156D-09T 18.5000000 RESIDMV-2.0547D-07 RESIDTL 6.7839D-08T 19.0000000 RESIDMV-1.1178D-06 RESIDTL 3.7453D-07T 19.5000000 RESIDMV 4.0182D-08 RESIDTL-1.4378D-08

Stopped on timeT 20.0000000 RESIDMV 1.6492D-08 RESIDTL-8.1371D-09

plot xv/tag='valve position',pv/tag='vessel pressure (bars)' &,fout/tag='vapor flow out (kg/sec)'

Drawing plot number 1set htic=700000 ! give the trim finder something to

HTIC (Old value) 771939.693 (New value) 700000.000set mtic=4000 ! work on by making ic values nonsteady state

MTIC (Old value) 4370.53388 (New value) 4000.00000analyze/freeze=c1i/control=q/observe=c1p/list=.t.analyze/trim ! find the steady state conditionJacobian evaluated. Condition number is 0.41422400Jacobian evaluated. Condition number is 0.28882100

State vector - iteration number 1HTOTAL 700000.000 MTOTAL 4000.00000 MV 0.56444100

TL 138.455000 Q 69153.9000

Derivative vector - residual is 0.00430496 previous 1.0000E+37Scaled residual is 69735.6000 previous 1.0000E+37

Z99996 2980.55000 Z99998 2.53914000 Z99992 3.8910E-12Z99990-2.3306E-12 C1P 1.85282000

Newton step 71379.6000 steep desc step 1598.72000 mu 0

Figure A15-4. Boiler log file (part 1)




TL 139.815000 Q 69153.0000

Derivative vector - residual is 4.53907000 previous 1.0000E+37Scaled residual is 330.909000 previous 69735.6000

Z99996-27.2037000 Z99998-0.00643281 Z99992-0.00905089Z99990-634.645000 C1P-3.4106E-15



TL 139.802000 Q 69153.9000

Derivative vector - residual is 0.06221710 previous 4.53907000Scaled residual is 4.74315000 previous 330.909000

Z99996 0.62842300 Z99998 1.4860E-04 Z99992 9.1727E-04Z99990 8.69736000 C1P 5.6843E-16



TL 139.802000 Q 69153.9000

Derivative vector - residual is 4.6269E-04 previous 0.06221710Scaled residual is 0.04924880 previous 4.74315000

Z99996-0.00544570 Z99998-1.2877E-06 Z99992-7.1310E-05Z99990-0.06391410 C1P 0.



TL 139.802000 Q 69153.9000

Derivative vector - residual is 8.4072E-06 previous 4.6269E-04Scaled residual is 0.00293479 previous 0.04924880

Z99996 6.9028E-05 Z99998 1.6323E-08 Z99992 6.0603E-06Z99990 8.1466E-04 C1P 0.

display/all ! show the steady state conditionT 0. ZZTICG 0. CINT 0.50000000

...

State Variables Derivatives Initial ConditionsC1I 17.5000000 Z99994 0. FINIC 17.5000000

HTOTAL 771939.691 Z99996 6.9028D-05 HTIC 700000.000MTOTAL 4370.53388 Z99998 1.6323D-08 MTIC 4000.00000

MV 0.53387730 Z99992 6.0603D-06 MVIC 0.53387799TL 139.802321 Z99990 8.1466D-04 TLIC 139.802321

Algebraic Variables

Common Block /ZZCOMP/A 9.28070000 B 2788.51000 C1P 0.C 220.790000 CG 0.00500000 CL 1.26000000

...XV 0.70000000 XVA 0.30000000 XVW 0.50000000

XVZ 0.70000000

Figure A15-4. Boiler log file (part 2)



B. General Purpose Utilities

General purpose subroutines from the system library are described in this appendix.

B.1 AGET–,APUT–

FORM: AGETR(x = 'string') AGETR('string', x)AGETI(n = 'string') AGETI('string', n)AGETL(l = 'string') AGETL('string', l)AGETD(d = 'string') AGETD('string', d)AGETC(c = 'string') AGETC('string', c)

APUTR('string', x)APUTI('string', n)APUTL('string', l)APUTD('string', d)APUTC('string', c)

whereR indicates real (single precision),I integer,L logical,Ddouble precision, andCcharacter. The two forms of each call are equivalent. The equal sign indicates thatthe item on left of it is the output of the routine; the item on the right, the input.

Subroutines AGET– and APUT– obtain the values from or put values into a variablearray in either the user or system dictionary. They are useful in FORTRANsubroutines to obtain or return isolated values not passed through the calling sequenceand are the only way to access values from the system dictionary.

For the AGET– subroutines, the variable to be filled must have sufficient space toreceive the entire array. No check is made that this condition has been fulfilled.

For the APUT– subroutines, the size of the dictionary variable denoted bystring isknown, so the exact amount of data needed to fill this variable is extracted. This maybe more than is intended, however, since the APUT– routine just copies successivewords until the size count is satisfied. The dictionary names placed instring can bein any case since the string is converted to uppercase before looking in the dictionary.Trailing blanks are ignored.

A typical reason for using this procedure is to access the computer system date andtime in the TITLE array for plot titles. Reference the whole 480 characters of TITLEand make the call in the TERMINAL section so it is executed only once per run.

CHARACTER mytitle*480, today*10, now*9CALL AGETC(mytitle = 'TITLE')CALL DATE(today)CALL TIME(now)mytitle(20:40) = today//nowCALL APUTC('TITLE', mytitle)

Note that these functions require a full dictionary search and if placed in a loopexecuted every integration step use an excessive amount of computer time.

ACSL Reference Manual Page B-1

B.2 DEBUG

FORM: CALL DEBUG

A call to this routine produces a debug dump of all variables, excluding arrays greaterthan MALPRN (maximum array limit for print), on the print (PRN) unit. If HVDPRN(high volume display) is set TRUE, the dump also appears on the display (DIS) unit.

The simplest way to get debug dumps is to set NDBUG to a positive integer at runtimeso that a debug list is produced at the end of every DERIVATIVE, DISCRETE, andJacobian evaluation; for example:

ACSL> SET NDBUG=20ACSL> START

While useful as a checkout tool, with large programs this approach can result in anoverwhelming amount of output. A more restricted selection of dumps can be obtainedby using the ACTION command (see Chapter 5) or by including a call to DEBUG atthe end of the DERIVATIVE or DISCRETE sections as follows:

IF(logical condition) CALL DEBUG

Note that sorted sections of a program are not always translated in the order given; alook at the resulting FORTRAN listing will show the order of execution and theplacement of the DEBUG call.

Including the following call in the DYNAMIC section produces the dump at everycommunication interval and is synonymous with OUTPUT /ALL:

CALL DEBUG

Calling DEBUG from the TERMINAL section gives all final values plus initialconditions, a useful set of data. Putting the call on a logical switch as follows allowsyou to suppress the listing when you don't want it, such as during interactive runs.

LOGICAL dumpCONSTANT dump = .TRUE.IF(dump) CALL DEBUG

B.3 DISSTR

FORM: CHARACTER buffer*nnCONSTANT buffer = ' 'WRITE(buffer, label) aCALL DISSTR(buffer)label: FORMAT(format)

In window environments (Microsoft Windows, X windows, etc) it is not possible touse Fortran WRITE and PRINT statements to write to screen, so the DISSTR (displaystring) utility is provided. Three of the examples (ACRFTS, ARESTG, and TESTER)under ACSL for Windows use the utility.

DISSTR writes to both the runtime window and the log file.

To use DISSTR, an internal file is declared as a character buffer with enough space towrite a message (*80 for an 80-column line, for example). The information is writtento the buffer in a WRITE statement, with the buffer name where a logical unit would

B. General Purpose Utilities B.2 DEBUG

Page B-2 ACSL Reference Manual

normally be. A Fortran FORMAT statement follows the usual rules, except for arestriction on using a slash (/ ) for a line feed because it overflows the buffer; generateblanks in the output with further calls to DISSTR. (The format can be incorporatedinto the WRITE statement; see a Fortran programmer's manual for details.) Finally, acall to DISSTR(buffer) prints the buffer.

For further information on writing to internal files, see a Fortran programmer's manualor the ANSI standard reference book.

Following is an example, taken from the ARESTG model, to illustrate the procedure.

!-----------------------write the message to a buffer so that it! can then be displayed as a string. It is given an initial value! to prevent the message about used but not definedCHARACTER buffer*80; CONSTANT buffe r = ' 'WRITE(buffer, 200) speed, ncaseCALL DISSTR(' ') ! write two blank linesCALL DISSTR(' ')CALL DISSTR(buffer) ! write the messageCALL DISSTR(' ') ! write two blank linesCALL DISSTR(' ')

200: FORMAT(20x,'Aircraft speed - ',f6.2,' Run no. ',i3)

B.4 INITD

FORM: CALL INITD

A call to INITD clears the event list. This is useful for parametric runs which loopfrom TERMINAL to INITIAL and contain DISCRETE sections. If the event list is notcleared before looping back, multiple loops add events to the event list and produceerroneous multiple executions of events.

The event list cannot be cleared automatically by ACSL at the end of a run in case theuser next commands a CONTINUE. CONTINUE skips over the INITIAL section andexpects to continue with everything unchanged. The automatic initialization by ACSLin the INITIAL section takes place before the INITIAL section user code in order toallow the use of SCHEDULE within the INITIAL section. The event list is thuscleared automatically when the INITIAL section is executed in response to theSTART command, but not when a program loops back from the TERMINAL section.A call to INITD handles this loop situation. See the program in Appendix A onTemperature Distribution Along a Radiating Fin for an example using this utility.

B.5 INTEG

In order to provide flexibility in trying new and improved integration algorithms, theINTEG subroutine is available for incorporating a user written routine. SettingIALG=7 transfers control to the INTEG routine at the beginning of every integrationstep. In order to write an effective INTEG routine, familiarity with the ACSL runtimeroutines ZZNITS, ZZNITA, ZZINTG, ZZRKIN, and INTEGZ(NST) is essential.

B.5 INTEG B. General Purpose Utilities


B.6 LISTD

FORM: CALL LISTD(unit)

The list dictionary call provides a listing of the user dictionary and current variablevalues along with any explanation of the variables supplied on the named file. Usedmainly for reports, it requires preparing a dictionary file with variable names anddefinitions. The argumentunit is an integer constant or a variable defining aFORTRAN file unit number containing the definitions. The file should be configuredas follows:

column 1-9 variable name, left justifiedcolumn 10 optional continuation indicator in sequence 0, 1, 2, 3, etc.column 11-80 definition

Because column 10 is reserved for continuation characters, only names up to ninecharacters long can be handled by the current version of LISTD.

Invocation of the call is in the INITIAL or TERMINAL section, usually on a switch asfollows:

LOGICAL listINTEGER unitCONSTANT list = .FALSE. , unit = 11IF(list) CALL LISTD(unit)

At the START runtime command, the dictionary is read from unitfile (11 in theexample). On some systems (VAX, IBM mainframe, for example), the unit isassociated with a file prior to entering the runtime session. On VAX systems, theASSIGN command relates the file to a FORTRAN logical unit number as follows:

$ ASSIGN model.DCT FOR011

On other systems (Unix, for example) you are prompted for a file name. In Windows,the Open browser appears. See the documentHow to Run ACSLor ACSL User'sGuideto determine the appropriate method of handling the unit number on yoursystem.

The dictionary is terminated by a blank name field or an end-of file. When a definitionmust be continued beyond column eighty, a non-blank character in column ten resultsin the name field being ignored and just the continued definition being listed out.Repeat the name on each continuation line, numbering the lines 0, 1, 2, 3, etc. incolumn ten. Now a standard sort on columns one through ten produces an alphabeticalorder with the continuation lines in their correct places. Note that zero is used in thefirst line of a continuation sequence and acts just like a blank. The reason for using azero is that in some computer systems blanks collate after numbers rather than before.

ACSL issues a message if a variable name in the dictionary file is not found (if a nameis misspelled, for instance). Duplicate names also result in an error message. If thename is in the program but the value is undefined, asterisks appear in the valuecolumn. For arrays, the type and size of the array is given, rather than all the values inthe array; for example, REAL(3).

The dictionary listing appears on the high volume print unit PRN, the log file of theruntime session. If system symbol HVDPRN has been set TRUE, the listing alsoappears on the screen during an interactive session. The log file can be read and/oraccessed with an editor to update the dictionary file for subsequent runs.

See the Missile Airframe example in Appendix A for an example using LISTD.

B. General Purpose Utilities B.6 LISTD


B.7 RSTART

FORM: CALL RSTART(blockname, newstep)

whereblockname refers to a DERIVATIVE section (which must have been given aname) andnewstep is an integration step size. A call to the RSTART routine restartsthe step size and history of the variable step, variable order integration algorithms(IALG = 1 or 2); it has no effect on the fixed-step Runge-Kutta algorithms (IALG = 3,4, or 5) and also cannot be used with the Runge-Kutta-Fehlberg algorithms (IALG = 8or 9). The call is usually used within a DISCRETE section that may be changingconditions discontinuously, thus invalidating the history data used by the integrationroutine in the continuous section.

It should never actually be necessary to use RSTART since the variable stepalgorithms control the step to satisfy an error criterion, but RSTART can help reducethe amount of work done by the integration routine if a drastic change in step size isknown to be necessary.

B.8 SETI, SETR

FORM: CALL SETI(iv, ia, n)CALL SETR(rv, ra, n)

where the value of expressioniv or rv is set inton locations of arrayia or ra ; n isan integer variable,i indicates type INTEGER, andr indicates floating point (REALor DOUBLEPRECISION depending on the mode chosen at translation).

The SET– subroutines are provided primarily to initialize arrays and set all elements toa given value. A complete array may be set, for example:

CALL SETR(k*a, array, iset)

or only a portion of an array:

CALL SETR(0.0, arr(5), 3)

in which case zeros are placed in the fifth, sixth, and seventh elements of arrayARR.No check is made to see whether these elements actually exist.

B.9 WEM

FORM: CALL WEM('character string')

The WEM (write error message) utility write a message to both the print (PRN) anddisplay (DIS) logical units.

B.9 WEM B. General Purpose Utilities


B.10 XFERBR,XFERBI

FORM: CALL XFERBR(y = x, n)CALL XFERBI(j = i, n)

wherex andy are floating point arrays of the same length,i andj are integer arraysof the same length, andn is an integer specifying the number of elements in the arrays.If n is a variable, it must be declared as an INTEGER.

The XFERB– (transfer block) subroutines move arrays from one place to anotherwithout requiring DO loops. Then elements in arrayx are moved into arrayy . Nocheck is made to see whether these elements actually exist.

XFERBR is single or double precision, depending on its arguments.

XFERB– might be used, for example, to transfer the three elements VM(1), VM(2),and VM(3) into the first three elements of the array RMD as follows:

CALL XFERBR(rmd = vm, 3)

B. General Purpose Utilities B.10 XFERBR, XFERBI


C. ACSL System Symbols

C.1 Introduction

Many system constants can be set at runtime with the SET command to controlprinting, plotting, and integration. In order for a symbol to be accessed at runtime, thename must not have been used in the program code.

Each system symbol is listed below along with its type, default value, and description.The value set by the user must agree with the symbol in type;i.e., integer into integer,logical into logical, floating point or integer into floating point, and character intocharacter. Plot units are either inches or double centimeters.

The first three characters of the symbols describe the action. The last three charactersdescribe the symbol group as follows:

- PLT plots in general- PPL printer plots- CPL continuous plots- SPL strip plots- FPL frequency plots- PRN printed outputs- ITG integration control

The symbols are listed below by group. An additional category describes miscel-laneous symbols (logical units, title, etc.).

C.2 Plots in general

ALCPLT LOGICALTRUE

Automatic line color. Increments through the available colors (1, 2, 3, etc.) for eachcurve on the plot. The mapping of the color numbers to actual colors depends on theplot device. The default on VAX systems is FALSE.

CALPLT LOGICALTRUE

Continuous plots on the PLT unit when TRUE, as opposed to strip format (seeSTRPLT).

DEFPLT LOGICALFALSE

Defer plots. The current plot is not drawn immediately so that subsequent plots can becollected for the same plot. For example, this feature can be used to plot trajectories ofboth missile and target on the same grid with the following commands:

SET DEFPLT=.TRUE.PLOT /XAXIS=rm1, rm3SET DEFPLT=.FALSE.PLOT /XAXIS=rt1, rt3

The first PLOT command plots the missile trajectories with the X axis RM1. Then thedeferred plot restriction is lifted and the second PLOT plots the target trajectory RT2versus RT1 and produces the output. One set of axes is drawn, with scales for thevariables plotted when DEFPLT is returned to FALSE. Be sure that the scales for allthe curves are the same, since it is not possible to tell from the plot if they are not.

ACSL Reference Manual Page C-1

DEVPLT INTEGER1

Select plotting device driver for line or strip plots. The devices available at a particularsite can be specified by the system manager. See the documentACSL Sim User'sGuide for further information. The default list is as follows:

1 Standard graphic device for system2 Neutral plot file (ASCII move/draw format)3 Tektronix4 Hewlett-Packard graphics language (HPGL)5 Postscript6 X-windows XplotDriver7 LaserJet8-9 reserved for future implementations10... machine-specific devices;e.g., Regis for VAX, EGA for PC, etc.

DSCPLT CHARACTER'A'

Default starting character for symbols on plots. Printable characters are specified by aninteger represenation; for example, 49 for'1' , 65 for 'A' , 97 for 'a' . Centeredsymbols are specified by an integer corresponding to the table in section C.4;SETDSCPLT=1results in an octagon for the default symbol.

DPNPLT LOGICALTRUE

Draw plot number. A vertical text string containing a plot number (sequential from thestart of the session) and the date and time at which the session was initiated is drawn atthe right of the plot image when DPNPLT is TRUE.

FTSPLT LOGICALFALSE

Flyback trace suppression. If a number of parametric runs have been made (eitherwhen NRWITG is TRUE or by cycling between the INITIAL and TERMINALsections), they can be plotted on one plot. If FTSPLT is TRUE, plotting is suppressedand the plot symbol incremented on flyback. This eliminates a line running from theend of one curve to the beginning of the next one and increments symbols and/orcolors for each curve (if they have activated).

The flyback is determined from the first variable on the PREPARE list. When thedifference between successive values becomes more negative than its previous value,it is assumed that a new run has started. The independent variable is normallyspecified first on the PREPARE list.

GLTPLT INTEGER000

Grid line type. The type is specified by three integer digitsijk, wherei is the line style(0 solid, 1 dashed, and 2 dotted),j is extra width, andk is the device-specific color.

NPPPLT INTEGER3

Number of plots per page when invoking the PLOT /ALL command.

PPOPLT LOGICALFALSE

Portrait plot orientation. When TRUE, plots are rotated counterclockwise ninetydegrees. This option is normally used only with hardcopy devices such as Postscript orHewlett-Packard pen plotters; it is not appropriate for screen plots. Rotating plotsgenerally results in the X axis being along the longer side of the page.

PRNPLT LOGICALFALSE

Printer (character) plots on high volume print device when TRUE. These plots aregenerated by printing characters for the data points to form the curve. They are not tobe confused with continuous or strip plots being sent to a dot matrix or other printer.

STRPLT LOGICALFALSE

Strip plots on the PLT unit when TRUE. Strip plots are normally drawn with onevariable per axis, and they are stacked from the bottom up in the order given on thePLOT command line.

TBRPLT INTEGER100

Baud rate of the line plot device, normally needed only for old Tektronix plotters.

C. ACSL System Symbols C.2 Plots in general

Page C-2 ACSL Reference Manual

XZPPLT REAL0.0

X axis zero point;i.e., the X coordinate of the plot origin in plot units to the right ofthe lower left corner of the page. This variable is used with YZPPLT to position plotson such applications as pen plotters. It remains in effect until explicitly changed.

YZPPLT REAL0.0

Y axis zero point;i.e., the Y coordinate of the plot origin in plot units from the bottomof the lower left corner of the page. This variable is used with XZPPLT to positionplots on such applications as pen plotters. It remains in effect until explicitly changed.

C.3 Printer plots

NGXPPL INTEGER20

Number of points between grid lines in the X direction for printer plots. The default isa grid every twenty printer lines.

NGYPPL INTEGER10

Number of points between grid lines in the Y direction for printer plots. The default isa grid every ten printer columns.

NPCPPL INTEGER1

Number of points per character plotted on printer plots. This feature can be used forplacing time ticks on a phase plane plot; for example, with the following commands:

SET DEFPLT=.TRUE.PLOT /XAXIS=x, ySET DEFPLT=FALSE, NPCPPL=10PLOT /XAXIS=x, y /CHARACTER='*'

The first PLOT plots Y against X using values recorded every communication inter-val, but the output is deferred. The plot frequency is changed and the second plot isplotted over the first, but with a different character, which thus flags every tenth point.

NPXPPL INTEGER100

Number of points in the X direction for printer plots. The default results in rectangularplots; for square plots, set NPXPPL to six tenths of NPYPPL.

NPYPPL INTEGER100

Number of points in the Y direction for printer plots. For narrow terminals, the defaultis reduced to fifty.

C.4 Continuous plots

CALCPL LOGICALTRUE

Color axis line for continuous plots;i.e., the Y axis is drawn with the color matchingthe curve. The default for VAX systems is FALSE.

GRDCPL LOGICALTRUE

Draw grid lines from each tick mark on the continuous plot axes when TRUE. SeeGLTPLT for options on type of line.

LINCPL LOGICALTRUE

Draw lines between data points on continuous plots when TRUE. If FALSE, only thecharacters at the data points appear. Note that if both SYMCPL and LINCPL areFALSE, no curve is drawn.

LTCCPL INTEGER40

Line length of TITLE in characters for continuous plots. This variable can be set to upto the maximum number of characters for the complete title (480). The number ofcharacters in TITLE (NCTPRN, default 120) should be at least as large as LTCCPL.

C.4 Continuous plots C. ACSL System Symbols


LTFCPL LOGICALFALSE

Line type fragment for continuous plots. When TRUE, a one-inch sample of the plotcurve is drawn, with the same color, width, and style, just to the right of the namestring on the Y axis. If symbols are drawn on the curve, then the symbol is drawn inthe center of this line fragment.

NPCCPL INTEGER10

Number of points per character on continuous plots;i.e., a symbol is written everyNPCCPL points. This is useful for placing time ticks on phase plane plots.

PSFCPL REAL1.0

Plot scale factor for continuous plots. The overall size of the plot, including axes andlettering, can be made smaller or larger by changing this factor.

SATCPL LOGICALFALSE

Suppress axis text on continuous plots. This feature allows the axes and tick marks tobe drawn but suppresses all numbers and labels, which is useful for speeding thedrawing in repetitive (usually draft or diagnostic) plots.

SYMCPL LOGICALFALSE

Plot symbols on the curve for continuous plots. Characters are specified with the/CHARACTER switch. Characters are centered over the data points and correspond tothe normal FORTRAN letters and digits. The default characters start with A and cyclethrough the alphabet and digits and then back through the alphabet, etc. Specialsymbols are available using unquoted integers between 1 and 13 as follows:

The characters cycle through the special symbols when any one of the symbols isspecified. NPCCPL controls the number of data points between symbols.

TTLCPL LOGICALTRUE

Title on continuous plots. The content of the TITLE array is written at the top of eachplot. The default format is three lines of forty characters each. The number ofcharacters in the title is specified by NCTPRN and the line length of the title byLTCCPL. The TITLE array is searched backwards from TITLE(NCTPRN) until anon-blank character is found, thus eliminating blank lines. The title on a plot neverintrudes into the plot area.

XCICPL REAL0.0

X axis cross position (in plot units) on continous plots. This is the position on the Xaxis where an extra Y axis is positioned. Only the axis is drawn in the plot area; thetext remains at the side, outside the plot area. If XCICPL is specified by a negativenumber, the extra Y axis will be placed where X has a value of zero, if possible.

XINCPL REAL5.0

X axis length in plot units for continuous plots.

XTICPL REAL1.0

X axis tick increment (i.e., the distance between tick marks) in plot units forcontinuous plots.

YCICPL REAL0.0

Y axis cross position (in plot units) on continuous plots. This is the position on the Yaxis where an extra X axis is drawn. Normally the X axis is at the bottom of the Yaxis, but an extra axis can be placed in the plot area. The text remains at the bottom,outside the plot area. If YCICPL is specified by a negative number, the extra axis willbe placed where Y has a value of zero, if possible.

YINCPL REAL5.0

Y axis length in plot units for continuous plots.

C. ACSL System Symbols C.4 Continuous plots


YTICPL REAL1.0

Y axis tick increment (i.e., the distance between tick marks) in plot units forcontinuous plots.

C.5 Strip plots

CALSPL LOGICALTRUE

Color axis line for strip plots;i.e., the Y axis is drawn with the color matching thecorresponding curve. The default on VAX systems is FALSE.

GRDSPL LOGICALTRUE

Draw grid lines from each tick mark on the strip plot axes when TRUE. See GLTPLTfor options on type of line.

LINSPL LOGICALTRUE

Draw lines between data points on strip plots when TRUE. If FALSE, only thecharacters at the data points appear. Note that if both SYMSPL and LINSPL areFALSE, no curve is drawn.

LTCSPL INTEGER40

Line length of title in characters for strip plots. This variable can be set to up to themaximum number of characters for the complete title (480). The number of charactersin TITLE (NCTPRN, default 120) should be at least as large as LTCSPL.

LTFSPL LOGICALFALSE

Line type fragment for strip plots. When TRUE, a one-inch sample of the plot curve isdrawn, with the same color, width, and style, just to the right of the name string on theY axis. If symbols are drawn on the curve, then the symbol is drawn in the center ofthis line fragment.

NPCSPL INTEGER10

Number of points per character on strip plots;i.e., a symbol is written every NPCSPLpoints plotted.

PSFSPL REAL1.0

Plot scale factor for the strip plots. The overall size of the plot, including axes andlettering, can be made smaller or larger by changing this factor.

SATSPL LOGICALFALSE

Suppress axis text on strip plots. This feature allows the axes and tick marks to bedrawn but suppresses all numbers and labels, which is useful for speeding the drawingof repetitive (usually draft or diagnostic) plots.

SYMSPL LOGICALFALSE

Plot symbols on the curve on strip plots. The symbols are the same as those listedunder SYMCPL.

TTLSPL LOGICALTRUE

Title on strip plots. The contents of the TITLE array is written at the top of each plot.The default format is three line of forty characters each. The number of characters inthe title is specified by NCTPRN and the line length of the title by LTCSPL. TheTITLE array is searched backwards from TITLE(NCTPRN) until a non-blankcharacter is found, thus eliminating blank lines. The title on a plot never intrudes intothe plot area.

XCISPL REAL0.0

X axis cross position (in plot units) on strip plots. This is the position on the X axiswhere an extra Y axis is positioned. Only the axis is drawn in the plot area; the textremains at the side, outside the plot area. If XCICPL is specified by a negativenumber, the extra Y axis is placed where X has a value of zero, if possible.

XINSPL REAL5.0

X axis length in plot units for strip plots.

XTISPL REAL1.0

X axis tick increment (i.e., the distance between tick marks) in plot units for strip plots.

C.5 Strip plots C. ACSL System Symbols


YASSPL REAL0.5

Y axis separation between successive strip plot axes stacked vertically.

YCISPL REAL1.0

Y axis cross position (in plot units) on strip plots. This is the position on the Y axiswhere an extra X axis is drawn. Normally the X axis is at the bottom of the Y axis, butan extra axis can be placed in the plot area. The text remains at the bottom, outside theplot area. If YCISPL is specified by a negative number, the extra axis will be placedwhere Y has a value of zero, if possible.

YINSPL REAL2.0

Y axis length in plot units for strip plots.

YTISPL REAL1.0

Y axis tick increment (i.e., the distance between tick marks) in plot units for strip plots.

C.6 Frequency plots

DFXFPL REAL0.1

Maximum phase change allowed during frequency sweep.

DTCFPL LOGICALFALSE

Draw two separate curves (i.e., stacked plots) for Bode plots.

DWNFPL REAL1.01

Minimum multiplier to next frequency during frequency sweep. Read asdelta omegaminimum. It must be greater than 1.0.

DWXFPL REAL2.0

Maximum multiplier to next frequency during frequency sweep. Read asdelta omegamaximum. It must be greater than 1.0.

EMNFPL INTEGER-9

Exponent minimum for marking of decade ticks on frequency and root locus plots.

EMXFPL INTEGER9

Exponent maximum for marking of decade ticks on frequency and root locus plots.

EPDFPL REAL0.0

Distance tolerance for root locus curve. Zero signifies use of a tenth of the minimumstep size (SSNFPL). Read asepsilon distance.

EPFFPL REAL0.1

First stage of root locus convergence to this phase error in radians. Read asepsilonphase.

FLTFPL INTEGER000

First line (i.e., phase curve) type can be changed on Bode plots to affect line style,thickness, and color on some plot devices (see GLTPLT). Applies to first curve onBode plots, only line on all other frequency plots.

GRDFPL LOGICALTRUE

Draw grid on plot for frequency plots.

LTCFPL INTEGER40

Line length of title in characters for frequency plots. This variable can be set to up tothe maximum number of characters for the complete title (480). The number ofcharacters in TITLE (NCTPRN, default 120) should at least as large as LTCCPL.

C. ACSL System Symbols C.6 Frequency plots


NEDFPL INTEGER100

Number of edge divisions for test of root locus entry.

NESFPL LOGICALFALSE

No exponent symbols are written to identify decade ticks on frequency or root locusplots. In complex cases, the exponents may interfere with the plot curves.

PSFFPL REAL1.0

Plot scale factor for frequency plots. The overall size of the plot, including axis andlettering, can be made smaller or larger by changing this factor.

SATFPL LOGICALFALSE

Suppress axis text on frequency plots. This feature allows the axes and tick marks tobe drawn but suppresses all numbers and labels, which is useful for speeding thedrawing in repetitive plots.

SLTFPL INTEGER000

Second line (i.e., gain curve) type for Bode plots can affect line type, thickness, andcolor on some plot devices (see GLTPLT).

SSNFPL REAL0.0

Step size minimum for root locus plots. Specifying zero signifies use of 0.4% of themaximum step size (SSXFPL).

SSXFPL REAL0.0

Step size maximum for root locus plots. Specifying zero signifies using 5% of thediagonal distance across the plot in the complex plane.

TKHFPL REAL0.070

Tick height for frequency or root locus plots. Decade points are marked by doubleheight ticks centered about the curve.

TTLFPL LOGICALTRUE

Draw title on frequency plots (see TTLCPL).

XCIFPL REAL-1.0

X axis cross position (in plot units) on frequency plots. The negative default valueforces an extra Y axis to be positioned at the X axis zero, if possible (see XCICPL).

XINFPL REAL5.0

X axis length in plot units for frequency plots.

XTIFPL REAL1.0

X axis tick increment (i.e., the distance between tick marks) in plot units for frequencyplots.

YASFPL REAL0.5

Y axis separation between two Bode plots (phase and gain) when DTCFPL is TRUEso that the phase and gain curves are drawn on two separate stacked plot areas.

YCIFPL REAL-1.0

Y axis cross position (in plot units) on frequency plots. The negative default valueforces an extra X axis to be positioned at the Y axis zero, if possible (see YCICPL).

YINFPL REAL5.0

Y axis length in plot units for frequency plots.

YTIFPL REAL1.0

Y axis tick increment (i.e., the distance between tick marks) in plot units for frequencyplots.

C.6 Frequency plots C. ACSL System Symbols


C.7 Print data

DCVPRN LOGICALFALSE

Display changed variable. When set TRUE, both the old and new values of allvariables are listed as they are changed by a SET command.

HVDPRN LOGICALTRUE

High volume data to display unit. Normally, high volume data is written only to thePRN unit; if HVDPRN is TRUE and the DIS unit is different from the PRN unit, thehigh volume data (e.g., output from PRINT, DEBUG, etc.) is written to both units.

MALPRN INTEGER10

Maximum array length in DEBUG listing. Arrays longer than MALPRN aresuppressed in the DEBUG output. The last element in the array is listed to show thatthe array is present and to indicate the array length.

NCTPRN INTEGER120

Number of characters in TITLE array. The TITLE can be set to up to 480 characters.

NPBPRN LOGICALFALSE

No page break during printout;i.e., no top-of-form headers to print (log) file.

PCWPRN INTEGER132

Printer character width. Controls the width of the output in the print log file. If theprinter available has a narrow carriage, set PCWPRN to 80. PCWPRN is analogous toTCWPRN, which controls terminal character width. When HVDPRN is TRUE,TCWPRN controls the print log file width.

TCWPRN INTEGER80

Terminal character width;i.e., the line width of data written on the display (DIS)logical unit. For batch oriented machines such as CDC, the default is changed to 132.TCWPRN is analogous to PCWPRN, which controls the printer character width.When HVDPRN is TRUE, TCWPRN controls the print log file width.

C.8 Integration control

CIOITG INTEGER...

Current integration order of variable order integration routines (IALG = 1 or 2). Thisvariable is calculated by the program and may be OUTPUT or PREPAREd so that theintegration order can be monitored.

CJVITG LOGICALTRUE

Check Jacobian validity. A report is issued if the Jacobian is considered invalid.

CSSITG REAL...

Current step size taken by the integration routine. This variable is calculated by theprogram and may be OUTPUT or PREPAREd so that the actual integration step sizecan be monitored.

DPSITG LOGICALTRUE

Double precision states;i.e., when TRUE, the state variables are accumulated indouble precision. The default is FALSE on 64 bit computers.

ECSITG LOGICALFALSE

Errors based on current state. Determines whether the allowed errors for the variablestep integration routines are based on current state values TRUE or on the largestvalues of the states so far.

FDEITG LOGICALFALSE

First derivative evaluation ensured to be on state trajectory. This is done automaticallyfor Runge-Kutta algorithms, but requires an extra calculation for the variable orderroutines (IALG = 1 or 2). It is useful when examining debug dumps to know that thestate variable is on the state space trajectory when the first flag (ZZFRFL) is TRUE.

C. ACSL System Symbols C.7 Print data


MXOITG INTEGER6

Maximum order of the integration algorithm may be specified between 1 and 6 whenusing the variable order, variable step integration routines (IALG = 1 or 2).

NRWITG LOGICALFALSE

No rewind. When this flag is TRUE, the RRR (raw run record) data file (i.e., the filecontaining the values logged for all the variables on the PREPARE list) is not rewoundat the beginning of a START or CONTIN command (the normal procedure). Thisfeature enables accumulation of data from sequential runs, which then can be printedand/or plotted at the end of all the runs.

NXEITG LOGICALFALSE

No extra evaluations are calculated before each communication interval when this flagis TRUE. It applies to all integration algorithms.

TJNITG REAL0.2

Threshold for flagging Jacobian nonlinearities; 1.0 effectively turns it off. In order tosee the results, CJVITG should be TRUE.

TSMITG LOGICALFALSE

Two sided matrix evaluation for the stiff integration algorithm (IALG = 2) to evaluatethe linearized state transition matrix. If the state equation isdx ⁄ dt = F(x), then the twosided matrix is obtained fromF(x+dx) andF(x−dx); the single sided matrix fromF(x)andF(x−dx). While the two sided matrix is more accurate than the single sided, itrequires twice as long to evaluate the complete matrix.

WEDITG LOGICALTRUE

Write event description when using the SCHEDULE operator for state events. Thisdata can be suppressed by setting WEDITG to FALSE..

WESITG LOGICALTRUE

Write error summary for variable order, variable step integration routines (IALG = 1or 2). All the states, along with the count of the number of times each state controlledthe integration step size, are listed at the end the run. This data may be suppressed bysetting WESITG to FALSE.

WNDITG LOGICALFALSE

Write normal data during integration;i.e.,basic information about the integrationprocess (slightly different for each integration algorithm) so that it can be followed.

WXDITG LOGICALFALSE

Write extra data during integration;i.e., Jacobian matrix, which is not written outwhen WNDITG is TRUE because it can be very high volume depending on thenumber of state variables.

C.9 Miscellaneous

CMD INTEGER4

Logical unit from which runtime commands are read. The allowed values depend onthe computer system and the installation. Generally, the command file is read fromunit 4, then control switches to the keyboard (unit 5).

DIS INTEGER6

Logical unit on which display data is written, including output from DISPLAY,RANGE, and OUTPUT commands. The allowed values depend on the computersystem and the installation.

NDBUG INTEGER0

Number of debug dumps to be printed out. When NDBUG is greater than zero, adebug dump is listed at each derivative evaluation and NDBUG is decremented by oneuntil NDBUG becomes zero.

PLT INTEGER6

Logical unit for line plot output (when CALPLT or STRPLT is TRUE). The allowedvalues depend on the computer system and the installation.

C.9 Miscellaneous C. ACSL System Symbols


PRN INTEGER9

Logical unit on which high volume data is written. All data written on unit DIS isechoed on unit PRN if DIS and PRN are different. In addition, printer plots, PRINTcommand output, debug dumps, and most ANALYZE output are written only on thisfile unless HVDPRN has been set TRUE. The allowed values depend on the computersystem and the installation.

To prevent data from accumulating on the log file, set PRN=DIS.

RRR INTEGER8

Logical unit on which intermediate data (raw run record) is written. The allowedvalues depend on the computer system and the installation.

SAVE INTEGER3

The ACSL system uses logical unit 3 for SAVE and RESTORE operations. Thislogical unit should be avoided by users.

TITLE CHARACTERblank

The TITLE array is a text string enclosed in quotes. It can be up to 480 characterslong. The title is printed at the top of each plot and each page of printout.

SET TITLE='Missile Longitudinal Dynamics'

The default layout for the title on plots is three lines of 40 characters per line. On anyplot header, the TITLE array is searched backwards from TITLE(NCTPRN) until anon-blank character is found; thus, blank lines are eliminated. System symbolsNCTPRN (number of characters in TITLE), LTCCPL, LTCSPL, and LTCFPL (lengthof TITLE in characters for continuous, strip, and frequency plots, respectively) areused to control the title format.

It is not necessary to always start at the beginning of the TITLE array. Any characterin the array can be specified as the starting point; for example, to specify data startingon the second and third lines on a plot title:

SET TITLE(41)='Step in Fin'SET TITLE(81)='Nominal CG'

This is useful when some parts of the title remain the same from run to run whileothers change with varying parameters.

The entire array can be cleared by using two single quotation marks enclosing a blank(theremustbe blank between the quotes) as follows:

SET TITLE=120*' '

C. ACSL System Symbols C.9 Miscellaneous


D. ACSL Error Messages

The ACSL error messages (from both translator and runtime executive) are givenbelow in alphabetical order.

See also Chapter 7 for explanations of ACSL debug dumps and of messages fromvariable step integration algorithms and Jacobian evaluations.

.... NAMEalready defined

This error occurs in using the LISTD function to process a set of dictionarydefinitions. It results when the same variable name has appeared previously and isoften caused by omitting continuation digits from column ten (10) in long definitions.

.... NAME(ddd) is an array and must be accessed by specific element

An X axis variable was specified that was an array. The X axis must be a singlevariable and so should be specified as an array element using parentheses –/XAXIS=va(2,3) rather than /XAXIS=va, for example.

.... NAME is a scalar, not an array

An array reference was used although the variable NAME is a scalar.

" NAME" passed to AGETC is of wrong type" NAME" passed to AGETD is of wrong type" NAME" passed to AGETI is of wrong type" NAME" passed to AGETL is of wrong type" NAME" passed to AGETR is of wrong type" NAME" passed to APUTC is of wrong type" NAME" passed to APUTD is of wrong type" NAME" passed to APUTI is of wrong type" NAME" passed to APUTL is of wrong type" NAME" passed to APUTR is of wrong type

After AGETi or APUTi looked up"NAME" in the dictionary, it determined that itwas not of the correct type and so refused to perform the copy operation.

AGET has been replaced at level 10 with separate routines as followsAGETR - realAGETI - integerAGETL - logicalAGETD - doubleAGETC - character

The use of AGET from an ACSL Level 9 model should be changed to use one of theroutines with a specific type. The reason for this is the different lengths of thearguments. Real, integer, and logical are normally the same size, but double is twice aslong and character may be any length.

ACSL Reference Manual Page D-1

AGETC can-t find " NAME".AGETD can-t find " NAME".AGETI can-t find " NAME".AGETL can-t find " NAME".AGETR can-t find " NAME".

The argument to AGETi identified by"NAME" is not in either the user programdictionary or in the ACSL system dictionary.

APUT has been replaced at level 10 with separate routines as followsAPUTR - realAPUTI - integerAPUTL - logicalAPUTD - doubleAPUTF - character

The use of APUT from an ACSL Level 9 model should be changed to use one of theroutines with a specific type. The reason for this is the different lengths of thearguments. Real, integer, and logical are normally the same size, but double is twice aslong and character may be any length.

APUTC can-t find " NAME".APUTD can-t find " NAME".APUTI can-t find " NAME".APUTL can-t find " NAME".APUTR can-t find " NAME".

The argument to APUTi identified by"NAME" is not in either the user modeldictionary or in the ACSL system dictionary.

Argument NAMEdoesn-t match any keyword

The argumentNAMEthat is to be used as a substitutable parameter in thePROCEDURE invocation at runtime doesn't match any keyword used in thedefinition. To list the valid keywords, type:

DISPLAY/PROCEDURE=procedname

Argument NAMEis given no value and has no default value

The argumentNAMEin the PROCEDURAL definition has no default value and is notspecified in the PROCEDURE invocation. To list argument keywords and defaultvalues, type:


Argument NAMEis not defined in procedure definition header.Replaced by null string

The variableNAMEhas been marked by an ampersand (&) for substitution but doesnot appear in the PROCEDURE header. Check the variable names in the header.

Argument number N cannot be positional after a keyword has been used

Once a keyword substitution argument has been given, all the following arguments inthe PROCEDURE invocation must be by keyword substitution, not position.

D. ACSL Error Messages AGETC can-t find " NAME".

Page D-2 ACSL Reference Manual

Argument number N doesn-t match the procedure definition

The PROCEDURE definition has fewer arguments than are used in the invocation. Tocheck the PROCEDURE definition, type:


Array element NAMEmust be a scalar

A symbolic array element name corresponds to a dimensional array. Array elementsmust be either integer literal constants (1, 3, 12, for example) or scalar variable namesthat contain an integer. For the following statement:

SET A(I,J,3) = 12.5

I andJ must have been declared as integers in the program since the default is forevery variable to be of floating point type.

Array element NAMEmust be integer type

The array elementNAMEmust be declared as a INTEGER within the program If avariable is not specifically typed, it will be the default REAL or DOUBLEPRECISION, depending on the global translation mode.

At least two output variables are needed in order to plot during run

When plotting during a run, at least two variables must be specified in the OUTPUTlist. The first variable on the list is the X axis variable; all other variables areconsidered Y axis variables.

Attempt to close standard output (or logical unit number N) ignored

The PLOT/CLOSE command closes the unit associated with the ACSL system symbolPLT. If this is six (or equal to DIS), the request is ignored.

Attempt to free an already free block in call to "ZZHDIS"

An internal system error. Please report to your systems staff with documentation.

Axis scales incorrect for log plots on NAME

This error occurs when logarithmic scale values are specified to be either negative orzero. Logarithmic scales must all be positive. ACSL's automatic scaling chooses a lowvalue for logarithmic scales which is the power of ten below the lowest value of thevariable being plotted;e.g., if the variable to be plotted has a lowest value of 0.07,automatic scaling chooses a low value of 0.01. If a negative or zero scale is forcedbecause of the data, you can override the automatic scale with /LO to force a positive(greater than zero) scale.

Bad break data count

The number of arguments specified in the TABLE statement is not 1, 2, or 3, or elsethe number of breakpoint integers given does not correspond with the number ofarguments.

Bad break data count D. ACSL Error Messages


Bad function data count

The number of data items (i.e., items between slashes) in the TABLE statement doesnot add up to the total length expected; the total should be the product of thedimensions plus the sum of the dimensions.

Buffer is not empty on call to zzrcsb: system error

Please report to systems staff with documentation.

Buffer overflow from "ZZGRXM". System error

This error occurs when the line buffer used for transmitting graphics commandsoverflows. Report to systems staff with documentation.

Can only release state. Variable is NAME

The variable specified to be released byNAMEis not a state variable. Only statevariables can be specified in the ANALYZE/RELEASE subcommand.

Cannot interface to MATLAB

An error ocurred when attempting to start MATLAB. Test that MATLAB can bestarted from the command line from your current directory and the currentenvironment. The current directory must be writeable since a file acsl_matlab.tmp iswritten with all the simulation data to be passed.

Can-t find array element in NAME

A reference has been made to a particular array element that does not exist or hasalready been deleted by a preceding ANALYZE /FREEZE command.

Can-t define a procedure within another procedure

Within a PROCEDURE definition, anotherdefinition(i.e., PROCEDURE keyword) isillegal. PROCEDUREs can containinvocationsof other PROCEDUREs to anunlimited nesting level.

Can-t find breakaway angle

The iteration to find the angle of the locus leaving the breakaway point has failed. Tryreducing the step size. If the ANALYZE /LIST flag is TRUE, the breakaway point isidentified on the high volume output unit prior to this message.

Can-t find data block name NAME

The /DATA blockNAMEmust be defined in a DATA statement before being invokedfor plotting.

Can-t find NAME

TheNAMEdoes not appear in the dictionary. The message may be in response to SET,DISPLAY, OUTPUT, PREPARE or various other runtime commands. WithRESTORE, a name was given to restore but could not be found on the file. Check thestate of the model when the SAVE file was made and whether the SAVE commandhad a reduced set of names. If no names are given on the save command,all variablesin the model are saved.

D. ACSL Error Messages Bad function data count


Can-t find the ACSL_ROOT path in order to pick up the ACSL help file

The ACSL home directory is needed in order to pick up the location of help files (andother support routines). When invoked via the executable file name, it is difficult on aUnix system to find the home directory. We look for a specific name'acsl'command on the $PATH, but sometimes the command has been changed (acsl10versus acsl11 for instance). If this message occurs, use the-r switch on theacslcommand – or whatever is in use as an equivalent – to run the model. Another way isto define an environment variable ACSL_ROOT that specifies the home acsl tree.

Can-t group poles correctly. System error

The algorithm for grouping the poles to define a multiple effective pole has failed.Report to systems staff with documentation.

Can-t satisfy error criterion for state number N in block N

The integration algorithm has decided it needs to take a step smaller then MINT tokeep the largest error within bound. The run terminates unless ERRTAG has beenspecified. If you have specified the name of an error flag with the ERRTAGcommand, the value of this flag is changed to TRUE (from its preset of FALSE) andthe run continues.

Can-t use a character variable NAMEin list

It is not possible to PREPARE character variables. The file can only hold floatingpoint, integer, or logical variable values.

Can-t use a character variable NAMEin list

In defining a data command a variable was use which was CHARACTER type.CHARACTER type variables cannot be added to the PREPARE list and so cannot beplotted.

Communication interval negative or zero

The communication interval (default name CINT) can not be either negative or zero.The value of the variable is tested immediately after leaving the DYNAMIC sectioncode, when control is first transferred to the integration control subroutine ZZINTG.

Condition of Jacobian too low to proceed

A condition number is evaluated for the matrix when inverting the Jacobian during theTRIM process; the message is produced if this condition number when added to unitystill gives unity. The results depend on machine precision; for example, on a VAX thecondition is approximately 1.0E-7, and on a CDC about 1.0E-13.

Conflicting data types

The variable indicated in the error message is being used in a way that conflicts withan earlier usage. This error sometimes results from neglecting to specify the variabletype (e.g., LOGICAL). Some examples of common incorrect usage include:

1) A label as a variable2) A variable in two different type declarations3) State or initial condition variables in logical or integer type statements4) Duplicate initial condition variable names in separate INTEG statements5) Duplicate name for derivative and state in separate INTVC statements

Conflicting data types D. ACSL Error Messages


Conflicting label NAME

The item indicated in the error message is either a variable being used as a statementlabel or else a previously defined label.

Control index of N is outside control vector size of N

The /CINDEX parameter value is pointing to a position outside the list of controlvariables. Either define a control variable (if none exists) or reset the control index towithin range (default is 1).

Control list length of N is not equal to observable list length of NOverall state matrix must be square

In attempting to trim, the number of adjustable variables (i.e., unfrozen states) plus thenumber of controls must equal the number of variables to be driven to zero (i.e., thederivatives of the unfrozen states plus the number of observables).

Convergence to local minima. Residual is N

This error occurs during TRIM when the incremental state movements are all less thanthe allowable errors per state and the derivatives have still not been forced to zero. Thesituation can result if MU becomes large. One solution is to reduce /FRACPM (default1.0) or remove the test entirely by setting /FRACPM to zero.

CTRL-C linkage not implemented

On some sytems there is no linkage to the CTRL-C program.

Data definition not terminated prior to end

Data definitions must be terminated with an END statement. The end-of-file wasencountered in reading in a data definition without seeing the terminating END.

Data item missing on command line

A data item is expected and the command line ends. This message would be produced,for example, if the data items 5 or 20 were left off the following input lines:

SET a = 5OUTPUT/NCIOUT = 20

Data list has N items and must be an integer multiple of argument count N

The data values given in a DATA block definition must be an integer multiplier of thenumber of names in the block. These are usually time histories and every namedvariable must have the same number of data points.

Data list must terminate with "END"

An end-of-file was found on the command input file before the END statement thatmust terminate a DATA definition.

D. ACSL Error Messages Conflicting label NAME


Data values restored into scalar model variable

Too many values have been RESTOREd into the named program variable, either toomany array elements or a file variable that is an array with the same name as a pro-gram variable that is a scalar. This message implies that the program may have beenchanged since the file was SAVEd and the RESTORE operation may not be valid.

Derivative function evaluation not repeatable for row number N

The state was changed, probably by direct assignment, during the evaluation of theJacobian for the Gear's stiff integration algorithm. Each state is perturbed in turn, firstplus, then minus, then plus again. If the perturbed state value is not identical at bothderivative evaluations with the positive perturbation, this message is produced.

Derivative no. N not calculated

Thenthderivative in the state vector is not calculated in the initial evaluation of theDERIVATIVE section. This is determined by setting all derivatives to a particularnumber before the evaluation, then checking to see if they have changed during theevaluation. This message generally indicates that a derivative calculation is beingskipped over. The derivatives are listed in order in DEBUG and DISPLAY/ALLlistings.

Dimension list exceeds 128 integers: System error


Dimension number N shouldn-t exceed N

The dimension numberN in a array reference is larger than the definition. Forexample, ifA is declared by:

DIMENSION a(5, 6, 7)

and the reference is:

SET a(4, 12, 1) = 5

then this message is produced since the 12 exceeds the second dimension size of 6.

Dimensions already set

The statement indicated attempts to define the dimensions of a previouslydimensioned array.

End of command file encountered

An end-of-file has been sensed on the file identified by logical unit CMD. The file isclosed and control reverts to the previous file in use.

End of input. No file to return to, stopping

An end-of-file was encountered on the input stream and no file was available to switchto. It could be a batch mode run so there is no interactive terminal to which control canbe transferred.

End of input. No file to return to, stopping D. ACSL Error Messages


Equivalence error

This error is usually caused by not realizing the special place occupied by the firstvariable in the EQUIVALENCE list, which is used, in the ACSL sense, as a primaryvariable. This variable must always appear first on the list for any subsequentEQUIVALENCE statements into the same array. Another cause is equivalencing thesame secondary variable to two different primary variables. System variables such asCINT or MAXT, and state, derivative, and initial condition variables must be given asprimary variables.

Error after NAME

Some sort of syntax error has been determined afterNAMEappears in the commandstatement. Trying to specify variables with the incorrect type (integer NCIOUT by areal number, /CHARACTER as a logical, for instance) is a common cause of this error.

Error assigning SYS$OUTPUT

This error occurs when assigning a channel for SYS$OUTPUT inside subroutineZZGRXM, which transmits graphics characters for plots.

Error during plot data output

This error occurs inside subroutine ZZGRXM when transmitting graphics commandsto the plotter.

Error in data following file variable NAME

Check the value corresponding to the variableNAMEin the text file the RESTORE isreading.

Error in dimension after file variable NAME

Check the dimension used for variableNAMEin the text file the RESTORE is reading.

Error in dimension following NAME

The dimension is incorrect for variableNAME.

Error in eigen analysis routine. Error number is N

An error was made in trying to determine the eigenvalues of the Jacobian matrix. Thenumber gives the eigenvalue at which the QR iteration in the EISPACK routine HQRor HQR2 fails.

Error in using or specifying increment after NAME

The actual increment value is valid only after a name defined as a /CONTROLvariable and it must be a floating point (or integer) variable. Specifying /INC after/OBSERVE produces this message.

Error in zero finder routine. Error number is N

The QZ algorithm failed to converge in evaluating the numerator polynomial roots.Generate the elements of the A, B, C, D matrices with the /JACOBIAN subcommandand check the results for reasonableness.

D. ACSL Error Messages Equivalence error


Error listing variable NAMEThe dimension is not compatible with model dimensions of NAME(i,j,...)

The list routine has been passed a dimension value that is incompatible with thedimensions of the variable specified in the program.

Error number N in eigen analysis routine

The eigenvalue finder has reported an error at thentheigenvalue. This is normally afailure to converge in the EISPACK routines HQRZ or HQR2 (SeeMatrix Eigensys-tem Routines - EISPACK Guideby B.T.Smithet al, Springer-Verlag, New York 1976)

Error reading from binary file number N

The read of the RRR file has failed. he RRR file is the file written to during asimulation run of all the values of the variables in the prepare list and then this data isread back with any subsequent PLOT, PRINT, and RANGE commands.

Error reading line from file FILENAME (IOSTAT = nnn) *****

In attempting to restore data, an error was encountered. Consult the local Fortrandocumentation for the meaning of the IOSTAT integer listed. It is at the targetstatement label for the error jump that the IOSTAT value (ios) is listed. The readstatement is of the form:

read(lunscr, end=530, err=995, iostat=ios) (b(j) , j = jpmn, jpmx)

Error reading line from file NAME

The RESTORE command fails in reading the next (which may be the first) line of thefile although the OPEN was successful.

Error return from DASSL integrator: idid = aaaa

The following list the possible values for the parameter:

idid= 1 -- the step was completed successfullyidid=-6 -- the error test failed repeatedlyidid=-7 -- the corrector could not convergeidid=-8 -- the iteration matrix is singularidid=-9 -- the corrector could not converge.

There were repeated error test failures on this step.idid=-10-- the corrector could not converge because ires was equal

to minus oneidid=-11-- ires equal to -2 was encountered, and control is being

returned to the calling program

Error writing to binary file number I

An error has shown up in writing out the RRR file that is recording all the simulationas the model continues. Check that there is sufficient disk space to accomodate thefile. Check the current size of the file (default name model.rrr).

Errors after NAME

An error occurred after the stringNAME. Check for correct switch value (e.g./XHI=3.0) or data type. This message comes after the complete line has been analyzedfor correct syntax and is a semantic error.

Errors after NAME D. ACSL Error Messages


Event list can only be written on a binary file./NOBINARY changed to /BINARY

A request was made to write the event list (i.e., SAVE/EVENTS) which requires thatthe SAVE file be written in binary mode.

Event restoration requested but but no event list saved on file FILENAME

The restore command was requested via /EVENTS but there were no events recordedin the save file. Go back to the save command and add the /EVENTS switch to ensurethat the current event list is added to the file data.

Event vanished. Last value assumed to be zero crossing time

A zero crossing event has been signalled, but all three points evaluated are now on thesame side of zero. This error can occur if the derivatives are not pure functions (i.e.,not repeatable) of the state variables.

File name must be quoted now

The file name for the Jacobian matrices must be a quoted string. At previous levels(9B and below), the file name had to be an unquoted string. Now use, for example:

ANALYZE/JACOBIAN='jacobfile1'

The number of characters allowed for the file name is machine-dependant.

File name should be quoted

This error occurs when using the SAVE/RESTORE commands. The argument for theSAVE/RESTORE commands should be a valid file name in quotes;e.g.,

SAVE/FILE='file1.sav'

Valid file names start with a letter and follow with letters or digits. The number ofcharacters in a file name is machine-dependent.

File not found NAME

The named INCLUDE file does not exist.

File variable NAMEexceeds dimension of model variable

The variableNAMEin the RESTORE file has larger dimensions or more dimensionsthan the same variable name defined in the model. This usually results from saving amodel condition and then trying to load back a data file from a previous version of theprogram. Note that any change to the program code usually changes all the ACSLinternal variable assignments (those with the form Znnnnn).

Function evaluation not repeatable, row N

See Chapter 7 for discussion of this informational message.

Help not available

On some systems, the ACSL help system is not available.

D. ACSL Error Messages Event list can only be written on a binary file.


HP Laser plot driver not available. Change DEVPLT

On some machines, the HP laser driver is impossible to implement.

IGET has been replaced at level 10 with separate routines as follows:AGETR - realAGETI - integerAGETL - logicalAGETD - doubleAGETF - character

See AGET.

Illegal algorithm number I . Algorithm changed back to default

The integration algorithm (default name IALG) number of valueI is not allowed. Thealgorithm is changed back to the default of Runge-Kutta fourth order (IALG=5).

Illegal block combination

An ACSL block delimiter (PROGRAM, INITIAL, END, etc.) was encountered out ofsequence.

Illegal command word

This error occurs when the command word starting the statement is neither a standardACSL runtime command nor a PROCEDURE name established by the user. Checkthe spelling and any abbreviation used. Try spelling out the command completely.

Illegal data in discrete

The specification of algorithm (IALG), maximum step size (MAXT), or number ofsteps per communication interval (NSTP) within a DISCRETE section is illegal.

Illegal data type following NAME

This error occurs when the characters followingNAMEdo not agree with the type ofname;i.e., REAL, DOUBLEPRECISION, LOGICAL, INTEGER, CHARACTER.

Illegal derivative definition

Derivative arrays are allowed only in INTVC statements (i.e., not in INTEGstatements).

Illegal handle value of N in call to "ZZCHDM". System errorIllegal handle value of N in call to "ZZHDIS". System errorIllegal handle value of N in call to "ZZSHE". System errorIllegal handle value of N in call to "ZZVHE". System error

This message results from a system error in the ACSL translator. Report to systemsstaff with documentation.

Illegal ic dimension

Initial conditions may not be dimensioned when they are used in INTEG statements.When they are used in INTVC statements, the dimensions must match the dimensionsof the state and derivative variables.

Illegal ic dimension D. ACSL Error Messages


Illegal integration statement

The syntax of the INTEG statement does not match the required syntax. INTEG hastwo arguments (derivative and initial condition). The following statement, forexample, would produce this message:

Y = INTEG(A, B, C)

The initial condition may be an expression only if it is entirely enclosed inparentheses. The derivative in an INTVC statement must be a variable name; it cannotbe an expression.

Illegal use of STANDVAL

Attempt to specify STANDVAL for a name that is not a macro parameter.

Incompatible "PREPARE" list sizeData file written with N variables. Current list has N

The PREPARE list has been changed between the previous START or CONTINUEthat wrote the RRR file and the current list that is being used to read the RRR file now.Either respecify the PREPARE list (PREPARE/CLEAR removes the previous list) orissue a START command, which writes over the old RRR file and makes a new oneconsistent with the current PREPARE list.

Incorrect dimensions for MATLAB variable NAME

On returning to an ACSL run from a MATLAB sequence, the variableNAMEto berestored into ACSL was found to have different dimensions. This error is usuallyproduced by a recalculation ofNAMEwithin MATLAB in such a way that it given adifferent dimension. It had the correct dimension on entry to MATLAB since this wasset from the ACSL model dictionary.

Independent variable changed in Jacobian evaluation NAME

This error occurs when a state has been modified in the DERIVATIVE section used tocalculate the Jacobian. Since the Jacobian evaluator uses numerical perturbation of theunfrozen states, any other modification invalidates the calculation.

Independent variable value N changed in Jacobian evaluation

The unfrozen states and control variables are considered one long vector. Thismessage points to thenth element in the vector as having its value calculated. Usedummy inputs to summing junctions that can be defined in CONSTANT statements asnamed /CONTROL variables.

Index of N is outside dimension of M for variable NAME

An array element from the RESTOREd file is outside the current dimension of theprogram variable. This message implies that the program may have been changedsince the file was SAVEd and the RESTORE operation may not be valid.

D. ACSL Error Messages Illegal integration statement


Index of I is outside limits of scalar variable NAME

In restoring data from a file, a variable has been found defined on the file as an array,but in the current model it is a scalar. Check changes that have been made to the modelbetween the time when the data was SAVEd and the current attempt to RESTORE.

Input dimension to "ZZOFST" is undefined: System error


Insufficient area for DELAY function

This error occurs when the array length specified in a DELAY function is too small toaccommodate all the data points needed, usually when the run goes through a regionrequiring a very small step size. Each integration step saves a data point, so memoryrequirements can become quite large.

Insufficient characters given to identify NAME

The ACSL runtime command or switch cannot be identified uniquely by the stringNAME. Provide more characters.

Insufficient data

This error occurs when a statement terminates while still awaiting data.

Insufficient region for translation

This error is caused by insufficient available memory for ACSL to attempt translation.It is always fatal. Consult the documentACSL Sim User's Guidefor the procedure toincrease memory size.

INTEG not in sort block

Integration statements must be in a sorted block (i.e., an implicit program or else aDERIVATIVE section of an explicit program) rather than the INITIAL, DYNAMIC,or TERMINAL section. See Chapter 3 further details on program structure. The erroris usually caused by an END mismatch that terminates a block inadvertently, but mayalso be caused by an integration statement inside a PROCEDURAL block nested tolevel two or higher. Derivative values can be calculated inside PROCEDURALblocks, but then should be integrated outside the blocks.

Integer is too big for machine. Using N

This error occurs when a literal integer exceeds the value of the machine register. OnCDC machines this, is 281474976710655; on VAX machines, it is 2147483647.

Integration step size negative or zero

The actual step size used by the integration routine has become negative or zero. Thestep size is obtained by taking the minimum of the time left to an event, the maximumstep (MAXT), and the communication interval (CINT) divided by NSTP.

Integration step size negative or zero D. ACSL Error Messages


Invalid DISCRETE block N referred to in event no. I

The variable name identifying the DISCRETE section has been changed in some wayso that its value in memory, which should be an integer between one and the numberof DERIVATIVE and DISCRETE sections, is outside this range or else is associatedwith a block that is not a DISCRETE section (e.g., may be a DERIVATIVE section).DISCRETE sections are identified by an ALGORITHM of zero.

Jacobian determinant zero, can-t trim

This error occurs when the /TRIM subcommand of ANALYZE finds that the Jacobianhas a zero determinant and so the Newton-Raphson iteration cannot proceed. Thesolution is to FREEZE appropriate states prior to invoking /TRIM.

Jacobian evaluated. Condition number is N

The condition of the Jacobian is effectively null; i.e., almost singular and so cannot beinverted. The condition is calculated where 1+ε/50 is just distinguishable from 1.0.

Jacobian nonlinear measure for row M and column N is X

See Chapter 7 for discussion of this informational message.

License manager failure

An attempt was made to communicate with the license manager checkout processwhich is run as a child of the model. This message is produced if the process is killedaccidentally.

Line plot library not loaded

This error occurs when line (continuous) plots (PLOT with CALPLT=.TRUE. orSTRPLT=.TRUE.) are requested without instructing the loader or link-edit program toattach the appropriate device driver. See theACSL Sim User's Guidedocument for alist of devices available and the system commands required.

Linear analysis routine not included

This error occurs when the runtime command ANALYZE is invoked without ensuringthat the appropriate routines are present. On some machines, the default is to omit theroutines that handle the ANALYZE command in order to save memory and load time.See theACSL Sim User's Guidedocument for the systems commands required toinstruct the loader or link-editor to link in the appropriate modules.

Linkage not implemented

Linkage to the control analysis program is not implemented on this computer.

List doesn-t contain NAME

This error occurs with ANALYZE, when one of the subcommands is searching for avariable on a list. Some of the subcommands search only selected lists; for instance,FREEZE applies only to state variables and so cannot locate any variable not a state.

Logical unit n is not open

An attempt was made to close a file that was not open.

D. ACSL Error Messages Invalid DISCRETE block N referred to in event no. I


Logical unit number must be greater than zero less than I

A logical unit number was used that is outside the range of logical unit numbers forthis particular system. Try the FILE command, which eliminates the need for logicalunit numbers to be specified.

Macro argument error

This error occurs when attempting to invoke a macro, as the result of an error in themacro definition of the arguments, such as there being no computed argument or morecomputed arguments than listed in the macro definition header.

Macro not defined

This error occurs when attempting to use a macro that has not been defined. Thesyntax of the statement indicates a macro is being called, but the macro is not found inthe macro file.

Macro statement order error

This error occurs during macro expansion. No standard value has been set for anunspecified macro argument, or else an attempt has been made to use the dimensionsof an undimensioned argument.

Macro termination error

The MACRO END statement is missing from the macro definition.

MATLAB variable NAMEhas imaginary part

In reading variables in from MATLAB, it has been found that one of the ACSLvariables now has an imaginary part. This error can occur only by recalculating thevariable within MATLAB.

Merror/Xerror on non-state variable

XERROR and MERROR apply only to state variables. For your variable name in amacro operator such as REALPL to be considered a state, the operator must beinvoked in the standalone form; for example:

REALPL(st = p, x, ic)

Missing derivative statement

An INTEG statement is missing for some element of a state array.

Model variable NAMEhas no dimensions

A variableNAMErestored from a file has dimensions, whereas the program variabledoes not. This error is usually caused by a change in program code after the previousSAVE command.

Multiply defined symbol

The error occurs in a sorted program or section. The named variable has previouslybeen assigned a value. The problem is often with an array, since the sorting proceduredoes not distinguish between different elements of an array. A PROCEDURAL blockmay be used to handle different elements of an array in different statements.

Multiply defined symbol D. ACSL Error Messages


Name NAMEalready in dictionary

This error occurs in using utility BLDDCT to extend to the ACSL dictionary, when anattempt is made to add a name already present in the dictionary.

Name for PROCEDURE not given or illegal

This error occurs in a runtime PROCEDURE definition if the name of thePROCEDURE has been omitted or is not of the correct form (i.e., alphanumericcharacters starting with a letter).

Name or element NAMEnot on OUTPUT list

One of the commands accessing the OUTPUT list (START, CONTINUE) contains avariable name not included in the original OUTPUT command. This error usuallyoccurs when specifying plot scales and line styles.

Name or element NAMEnot on PREPARE list

One of the commands accessing data on the PREPARE list (PLOT, PRINT, RANGE,etc.) contains a variable name or array element not included in the original PREPARElist; the following sequence, for example, produces this error message.

PREPARE Y(2), Y(3)PLOT Y(1)

Need a name first

This error occurs when modifiers to plot variables precede the name of the variable.Since Y axis plot modifiers apply to the variable name immediately to the left on thecommand line, the name must appear first. The following, for example, is incorrect:

PLOT /LO=0, /HI=5, Y1

This message also appears if modifiers apply to a variable that has been left off thePREPARE list.

Negative delay value of R

The DELAY operator has been asked to provide a negative delay time, a physicalimpossibility. Check the program; there could be flow reversal in a pipe model.

No active block to modify with NAME

The qualifiers /LO, /HI, /TYPE, and /CHARACTER need to have a name or activeblock defined first since they qualify variable names to their left.

No assigned variable defined

Attempt to perform arithmetic operation (MACRO INCREMENT, DECREMENT,etc.) on an assigned variable before specifying the assigned variable with MACROASSIGN.

No equation depends on variable N

A state or control variableN (considering unfrozen states and controls as onecontiguous vector) has no influence on any state derivative or observable, resulting ina zero column in the A, B, C, D matrix group. The name of the state or control

D. ACSL Error Messages Name NAME already in dictionary


variable can be found from the ANALYZE/JACOBIAN operation, which lists thestates and control vectors by name separately.

No free logical unit available between N and N

The file command has run out of logical unit numbers to open. The remedy is to closesome of the open files.

No match for ACSL_PLT plot device NAMEPermissible devices are the following:

1 Standard graphic device for system2 Neutral plot file (ASCII move/draw format)3 Tektronix4 Hewlett-Packard graphics language (HPGL)5 Postscript6 X-windows, XplotDriver7 LaserJet

The enviroment variable ACSL_PLOT has been set to an unknown plot device.Change the value to one on the list. (See subroutine zzdraw.f for the origin of this list)

No match in file for model variable NAME

A variable appears in the model that does not appear in the file from which theRESTORE is reading. This is a warning since the program may have changed sincethe file was created. This error is normally the result of restoring a file that was madeby selectively saving only a limited number of variables.

No match in model for file variable NAME

A variable appears in the RESTORE file that does not exist in the current program.This usually indicates an old model, and the RESTORE operation may not be valid.

No more table space, max length used is I

The runtime table space manager has run out of space and the run must be aborted.This error is frequently associated with using the stiff integration algorithm orinvoking /EIGEN analysis or /TRIM, all of which require 2N**2 words, where N isthe number of the state variables. See the documentACSL Sim User's Guidefor themechanism to increase runtime table space.

No residual depends on variable NAME

In attempting to iterate to solve the for the algebraic variables defined by IMPLC andIMPVC statements, a singular Jacobian has been found and in analyzing the Jacobian,the simple problem has surfaced that a complete column is zero. This means that thecorresponding algebraic variable cannot influence the residual and so the algebraicconstraint cannot be solved.

No right sibling

This is an internal ACSL system error during syntax analysis. Report to systems staffwith documentation.

No right sibling D. ACSL Error Messages


No space in character dictionary for adding NAMENo space in dimension dictionary for adding NAMENo space in integer dictionary for adding NAME

These errors occurs in attempting to extend the user dictionary with BLDDCT. Thecommon block space designated for the dictionary has been filled and no more namescan be added.

No table space left

This error occurs when there is insufficient field length for ACSL to continue running,and it is always fatal. It is usually caused by the use of a large number of variables in alarge program, but can also be caused by arithmetic loops encountered in statementsorting. Any such arithmetic loop should be eliminated. An increase in field length of10K should be more than sufficient in most cases where the cause is simply a largenumber of variables. See the documentACSL Sim User's Guidefor instructions onincreasing table space. On most systems, a switch on the ACSL invocation is used toincrease table space; on the PC, it can be changed under an Options menu.

No user supplied integration routine

This error occurs when an attempt is made to use the integration algorithm seven(IALG=7) without supplying a user subroutine INTEG to handle the integration.

No value item follows NAME

In the invocation of a PROCEDURE, a keyword has been used but no value item hasbeen specified to substitute for the keyword. To list the keywords, type:


No variable affects residual NAME

Similar to theNo residual depends on variableabove, but corresponds to a zero rowin the Jacobian whereby the residual value is not affected by any of the algebraicvariables.

No variables printed. Use "PRINT/ALL" for everything

PRINT needs at least one name to produce a listing. Use PRINT/ALL to list everyvariable on the RRR file (i.e., specified on the PREPARE list).

Not allowed in common block

System variables (CINT, IALG, MAXT, etc.) cannot be named in a user-definedcommon block.

Not enough table space in blank common

The scratch table manager has run out of space. In some machines (PCs for example)this space is fixed because of machine architecture; in others (VAX, CDC, SUN, IBMmainframe) it can be changed by an option to the ACSL invocation (seeACSL SimUser's Guide); and in still others (Apollo, SEL) it can be changed only by systemspersonnel.

D. ACSL Error Messages No space in character dictionary for adding NAME


Not in PROCEDURE definition - use QUIT to finish

The END statement at runtime terminates only PROCEDURE definitions, while QUITterminates the ACSL runtime session. The message is produced if END is used inplace of QUIT or if there is a syntax error in the preceding PROCEDURE statement.

Numerator greater than denominator

This message refers to the TRAN (transfer function) operator, in which the order ofthe numerator must not be greater than that of the denominator.

Observable index of I is outside observable vector size of I

The /OINDEX parameter value is pointing to a position outside the list of observablevariables. Either define an observable variable (if none exists) or reset the observableindex to within range (default is 1).

Out of sequence setup for common block ZZCOMa

The number of common blocks has changed, which implies is mismatch of ACSLlevels between the translated model and the current library.

Outside table limit


Outside table limit in "ZZGETD": System errorOutside table limit in "ZZSTE": System errorOutside table limit in "ZZVTE": System errorOutside table limit in "ZZVTER": System error


Parameter already defined NAME

The listedNAMEhas appeared in the program prior to this PARAMETER statement. Avariable must be defined in a PARAMETER statementbeforeit is used in theprogram. The translator does not sort PARAMETER statements.

Parameter not found

This error occurs when attempting to assign a standard value (MACRO STANDVAL)to a variable other than one of the main arguments in a MACRO definition.

Premature end of file

An end-of-file was encountered on the translator input file before the logical end of theprogram was found. This implies an incomplete program or a missing END statement.

Procedure NAMEis called recursively - ignored

The PROCEDURENAMEcontains a reference to itself and resulted in an illegalrecursive expansion on invocation.

Procedure NAME is called recursively - ignored D. ACSL Error Messages


Procedure definition not terminated prior to end of information on inputstream

In collecting the PROCEDURE definition text, an end-of-file was encountered insteadof a terminating END statement.

Procedure ended incorrectly

An ACSL delimiter other than END has been found inside a PROCEDURAL block.

Procedure name NAMEmust be simple identifier

The request to list a PROCEDURE text must have the PROCEDURE name defined asa simple identifier (i.e.no parentheses following).

Re-computing a constant

See: Warning: Re-computing a constant .

Re-computing state variable NAME

(1) A state variable previously defined in an INTEG or INTVC statement has beenassigned a value in another statement in the same DERIVATIVE section, which isillegal. Defining a new value for a state variable is valid only in a DISCRETE section.

(2) The message may be produced if a state is set with a CONSTANT statement aswell as in INTEG or INTVC, sometimes done to initialize states for calculations in theINITIAL section. Recommended alternatives are to use the initial conditions (usuallyproperly set with CONSTANT statements) or the RESET operator (see Chapter 4).From level 10F,RESET('NOEVAL') is done automatically;i.e., the initial conditiontable is moved to the state table before the INITIAL section is executed.

Reference made to non-state variable NAME

This error occurs when an attempt is made to specify error tolerances with XERRORor MERROR for a variable that is not a state. The names of all the state variables arelisted in the debug output.

Reference out of limit of array NAME

This error occurs when an array element outside the declared size of the array isreferenced. In the runtime SET command, sequential data items are set into succeedingslots of an array, and each item is checked to make sure the array bound is notexceeded. For example, if A is an array of size 5, the following command will producethe error message since the last value is to be stored in A(6):

SET A(3) = 1.5, 2.5, 5.0, 6.0

Reference outside heap block N. Reference is N


Restoring entire array for NAME

The array element followingNAMEis in error in some way, so the entire array isRESTOREd instead of possible individual elements.

D. ACSL Error Messages Procedure definition not terminated prior to end of information on input stream


RGET has been replaced at level 10 with separate routines as followsAGETR - realAGETI - integerAGETL - logicalAGETD - doubleAGETC - character

See AGET.

RSTART can-t find block no. I

The RSTART utility (see Appendix B) was called with an invalid block number;i.e., anumber that does not correspond to a DERIVATIVE section number.

Saving entire array for NAME

The array element followingNAMEis in error in some way, so the entire array isSAVEd instead of any individual elements.

Scales incorrect for log plots on NAME

This error occurs when logarithmic scale values are specified to be either negative orzero. Logarithmic scales must all be positive. ACSL's automatic scaling chooses a lowvalue for logarithmic scales that is the power of ten below the lowest value of thevariable being plotted;e.g., if the variable to be plotted has a lowest value of 0.07,automatic scaling chooses a low value of 0.01. If a negative or zero scale is forcedbecause of the data, you can override the automatic scale with /LO to force a positive(greater than zero) scale.

Scratch logical unit I already in use. Restore aborted

An INQUIRE showed the scratch logical unit to be already open. As a general rule,use file logical unit numbers of only ten or higher to avoid conflict with ACSL logicalunit numbers.

SET has been replaced at level 10 with separate routines as followsSETR - real or doubleSETI - integer

The SET operator in program code must now specify either floating point or integertype.

Singular matrix for algebraic states

The variables defined using the implicit algebraic operators IMPLC and IMPVC areconnected via a Jacobian that is singular and so it is impossible to iterate to solve forthe condition that will drive the residual to zero.

Skipping array NAME(i, j, ...) with more than two dimensions

MATLAB can only handle arrays of up to two dimensions. If in the transfer of data, asimulation model variable is encountered with three or more dimensions, then thisvariable is skipped and will not be visible in MATLAB.

SORT not permitted here

SORT cannot be specified in a PROCEDURAL or IF-THEN-ELSE block.

SORT not permitted here D. ACSL Error Messages


"START" must follow a "REINIT" operation. Stopped

After a REINIT, a START rather than a CONTINUE must follow so thatreinitialization can occur for non-integration state variables.

State changed in Jacobian evaluation, state VAR

The state was changed, probably by a direct assignment, during the evaluation of theJacobian. Each state is perturbed in turn, first plus, then minus, then plus again. If theperturbed state value is not identical at both derivative evaluations with the positiveperturbation, this message is produced.

Statement is in between sections

The statement appears after the END of one section (INITIAL, DYNAMIC,DERIVATIVE, etc.) but before the beginning of another.

Step size too large. State - N

This error occurs when a zero determinant is found in trying to invert the matrix (I +hA) in the stiff integration algorithm. This should never happen, but if it does, it can befixed by reducing the allowable step size (through MAXTERVAL).

Stuck at breakaway point X, Y

The iteration to find a breakaway point within the root locus has failed. Reduce themaximum step with system symbol SSXFPL.

Stuck in middle of step at X, Y

The root locus finder is unable to complete a step with the current value of minimumstep. Reduce the value of SSNFPL and/or SSXFPL and/or modify the phase errorcondition EPFFPL and the step tolerance EPDFPL.

Symbol used but not defined NAME

The listed variableNAMEnever appears on the left side of an equal sign. See thesection on "Externally defined variables" in Chapter 8 for a way of suppressing thesemessages when variables are defined in Fortran subroutines.

Syntax error ....

The statement containing the syntax error is listed in the error message, then repeatedwith a line of asterisks underneath it. The asterisks stop where the first syntax erroroccurs. Note that only thefirst error in a line is pointed out, so a careful check of theremainder of the statement is advisable. Syntax error messages may be produced bothat translation and at runtime. Following is an example of a syntax error with itsasterisk indicator:

X = Y ++ Y*******

D. ACSL Error Messages "START" must follow a "REINIT" operation. Stopped


Syntax error in input line

The RESTORE file in text (ASCII) mode has a line in error. Each line should containa name followed by an equal sign followed by a value. The incorrect line is printedafter the error message.

Table already defined

The table name has already been used in another context prior to the current tabledefinition, as either a simple variable, another TABLE definition, or in an assignmentstatement. TABLE functions must be defined before their first use since otherwise thetranslator cannot distinguish them as TABLE functions rather than normal Fortranfunctions.

Table definition error

The number of breakpoints specified for the table does not correspond to the numberactually listed.

Tag too long after NAME

This error occurs when a /TAG string on a PLOT command has more characters thancan be drawn on the plot. The actual number allowed depends on machine type, but allmachines accept 20-character strings.

Terminated by zero gain

The gain through the ANALYZE transfer function must be non-zero for the frequencyresponse and root locus finder to work. Generate the A, B, C, D matrices with the/JACOBIAN subcommand and check them for the source of the zero gain.

The /CLOSE switch must be alone on the PLOT command

The /CLOSE switch closes the PLT unit number so that it can be spooled to a file. If aY axis variable is listed, this could cause a plot to be written to the same file therebyerasing the data before it can be moved. On VAX/VMS systems with versionnumbers, this doesn't happen, but all other systems write over any existing plot file,thereby destroying the old version.

The array NAMEmust have a specific element selected

In the definition of a DATA block, each channel must be associated with a specificvariable name and dimension. For example, ifA is an array, useA(3,5,7)as a specificelement, not the genericA that normally stands for all its elements.

The command length of N exceeds the length allowed for the system buffer of Ncharacters

The SYSTEM command can take only a limited number of characters in a buffer. UseSYSTEM with no operating system command argument in order to spawn off asubprocess so you can enter an unlimited number of commands.

The dimension N is not compatible with max model dimension(s) of N

An array reference is not compatible with that defined in the program. For example, ifan array is dimensioned (3,7,2) in the program, a reference to (2,3,4) would producethe error message since the last dimension of 4 exceeds the specified value of 2.

The dimension N is not compatible with max model dimension(s) of N D. ACSL Error Messages


The dimension is not compatible with model dimension(s) of N

An array reference is not compatible with that defined in the program. For example, ifan array is dimensioned (3,7,2) in the program, a reference to (2,3,4) would producethe error message since the last dimension of 4 exceeds the specified value of 2.

The /FILE switch must be followed by a character string

File names must be given in single quotes. If a name is given unquoted, ACSL tries tolook in the model dictionary or the system dictionary for the name as a variable.

The input variable has N dimensions and should have N

The array reference has a different number of dimensions than that specified in theprogram. For example, if variableA(3,4,5)is defined in the program, the followingruntime command results in this message:

SET A(2,2) = 3.0

The model translated as double precision cannot be used with the singleprecision runtime system. Use ".../DOUBLE" switch

A program has been translated as double precision, but the double precision library hasnot been specified at link time. Computer systems differ in the specification oftranslation mode on the command line. VAX/VMS systems use/DOUBLE_PRECISION; Unix systems use -x (extended precision). SeeACSL SimUser's Guide.

The model translated as single precision cannot be used with the doubleprecision runtime system. Use ".../NODOUBLE" switch

A program has been translated as single precision, but the double precision library hasbeen specified at link time. Computer systems differ in the specification of translationmode on the command line. The default is single precision. VAX/VMS systemsspecify double precision with /DOUBLE_PRECISION; Unix systems use -x(extended precision). See theACSL Sim User's Guide.

The model variable is a scalar

A reference has been made to an array, but the variable has been defined as a scalar inthe program.

The type of file to close must be defined first

The /CLOSE switch must be applied to a specific type of file as in :

FILE/RRRFILE='myrrr'/CLOSE

The variable NAMEmust have the same type as the state vector

Since the control variable is adjoined to the state vector, it must have the same type(i.e., single or double precision). This error message is usually produced whenspecifying a single precision control or observable when the model had been translatedin global double precision (forcing the type of the state variables) or vice versa.

The variable should have a dimension

A reference has been made to a scalar, but the variable has been defined as an array inthe program. Check the variable name in a DEBUG list.

D. ACSL Error Messages The dimension is not compatible with model dimension(s) of N


The wild card NAMEis illegal in plot command

Wild card names (X??, for example) cannot be used to access variables for plotting.

Time schedule error. Block number N is not discrete

The block pointed to by a SCHEDULE .AT. is not a DISCRETE block. OnlyDISCRETE blocks can handle SCHEDULEd events. Blocks (i.e., DERIVATIVE andDISCRETE sections) are numbered in their order of appearance in the program code.

Too close to pole at X, Y

The locus has come within a minimum step of a pole when it is travelling towards azero. Reduce the maximum step with system symbol SSXFPL.

Too many characters

The name indicated contains more than 32 characters and has been truncated by thetranslator. Translation continues with the truncated version of the name.

Too many deriv/discrete sections

The number of DERIVATIVE and DISCRETE section in any given program islimited to approximately the number of bits in a computer word, usually about 30.

Too many digits

The number being processed has too many digits for the accuracy of the machine.

Too many ENDs

This error occurs when statements remain on the input file after the final END of theACSL program. The remaining statements are listed but not processed. This impliesthat too many END statements were included in the program, statements weremisplaced, or Fortran routines are included incorrectly. If Fortran routines are includedat the end of the ACSL program, the very next statement after the last ACSL ENDstatement must start with SUBROUTINE, FUNCTION, INTEGER FUNCTION, etc.,as explained in Section 1.5. No blank or comment lines are allowed between theACSL END and the first Fortran function statement, and no tabs are allowed in thefirst Fortran line.

Too many iterations, can-t converge

This error occurs when ANALYZE /TRIM fails to converge within the specifiednumber of iterations. Possible solutions are to increase the number of iterations(NITRMX), reduce the convergence criterion (RMSEMX), or decrease the step(FRACDL). REINIT can be used to retain any gains obtained with the current iteration.

Type conflict on store into NAME

This error occurs when data does not agree with the predetermined type (i.e., REAL,DOUBLEPRECISION, INTEGER, LOGICAL, or CHARACTER) ofNAME. Logicaldata can be only .TRUE. (.T.) or .FALSE. (.F.). Integers may be stored into floatingpoint, but all other combinations are illegal.

Type conflict on store into NAME D. ACSL Error Messages


Unable to open file NAME

The named file is not present or is busy. The message implies that the OPEN failed ona SAVE or RESTORE command.

Unknown operation at switch / SWITCH

This message usually means that the switch is followed by a data item when it is notneeded; for example:

PLOT/ALL=5

or else it is a switch that takes a data item but one is not provided; for example:

PRINT/NCIPRN

Unknown record structure on "RRR" file

The record structure on the RRR (raw run record) file is not recognized, usuallybecause some other type of file has been referenced. The first record must contain afour-integer group written via the runtime START command using a PREPARE listset prior to the START. This message can results from a call to LOGD in an INITIALsection because the RRR file is not set up until the end of the INITIAL section.

Unsortable statement block

An arithmetic loop has been encountered during sorting and is listed below themessage. The loop may be the result of a simple spelling or PROCEDURAL headererror or a missing state equation, or the program may contain an algebraic loop whichcan be broken by the use of mathematics, PROCEDURAL blocks, or (in certaincircumstances) the IMPL operator. See Chapter 3.

Use write extra information flag to replace the call to WRITG

The use of CALL WRITG to list integration data has been superseded by setting writeflags to switch on different levels of data (see WNDITG and WXDITG)

Value of "DEVPLT" is N and corresponds to no device.Permissible devices are the following:

You have specified a plot device driver with ACSL system symbol DEVPLT (devicefor plots) that is not defined at your installation. An installation can have its own set ofplot devices. See your systems manager. The message is generated in librarysubroutine ZZDRAW.

Variable already released. Name is NAME

The state variable name is not frozen at the time an ANALYZE /RELEASE commandis issued.

Variable not dimensioned

The variable indicated in the error message is being used as an array without beingdeclared as such by a DIMENSION or other such typing statement.

D. ACSL Error Messages Unable to open file NAME


VPUT has been replaced at level 10 with separate routines as followsAPUTR - realAPUTI - integerAPUTL - logicalAPUTD - doubleAPUTF - character

See APUT.

Warning: Re-computing a constant

A variable defined in a CONSTANT statement is also calculated in an assignmentstatement. Although some situations may warrant use of this practice (see theRadiating Fin example in Appendix A), in general it is an error and so a warningmessage is produced and translation continues. The message can be suppressed by the/NOWARNING (VAX) or -w (Unix) switch at the ACSL invocation, or from theOptions/Translator dialog box on the PC.

If a variable is to be initialized, an assignment statement in the INITIAL section(rather than a CONSTANT statement) should be used. Two runs, one after the other inthe same runtime session, show if all variables are initialized correctly.

In some situations involving equivalencing of elements of arrays, the XFERBa utilities(see Appendix B) can be used instead of EQUIVALENCE to avoid this message.

Wrong dimensions

This error occurs when attempting to use an array with more than six subscripts (themaximum allowed in ACSL).

X-axis variable NAMEis not in data block NAME

In order for any points to be plotted with the PLOT/DATA command, one of channelsin the DATA block must correspond to the X axis variable name. Check the definitionof the DATA block.

XFERB has been replaced at level 10 with separate routines as followsXFERBR - real or doubleXFERBI - integer

The transfer block routine now must specify either floating point or integer type.

Xwindows plot driver not available. Change DEVPLT

On PC systems, the X Windows plot system is not available.

Y-axis variable NAMEis not in data block

When a /DATA switch is attached to a particular Y axis variable, then this variablemust be one of the channels defined in the DATA block. Check the definition on theDATA block.

You must define at least one control variable

At least one control variable must be defined for the ANALYZE transfer functionevaluation.

You must define at least one control variable D. ACSL Error Messages


You must define at least one observable variable

At least one observable variable must be defined for the ANALYZE transfer functionevaluation.

Zero determinant for stiff algorithm, block N

A zero determinant was found for the iterator for the Gear integrator. This shouldnever happen since as the step size decreases, the iterator matrix becomes closer andcloser to a unit diagonal matrix – a long way from being singular.

Zero row for equation number N

A derivative or observable is not affected by any state or control, which results in azero row in the A,B,C,D matrix group. The derivative or observable variable can benoted in the listing obtained from the ANALYZE/JACOBIAN command, which liststhe derivative and observable vectors by name separately.

D. ACSL Error Messages You must define at least one observable variable


E. References

1. Akima, Hiroshi, "A method of univariate interpolation that has the accuracy of athird-degree polynomial", ACSM transations on Mathematical Software, Volume 17Number 3, September 1991, pp. 341-366.

2. Brenan, E.E., Campbell, S.L., and Petzold, L.R.,Numerical Solution of Initial ValueProblems in Differential Algebraic Equations, North-Holland, 1989.

3. Gear, C. William,Numerical Initial Value Problems in Ordinary DifferentialEquations, c1971, Prentice-Hall, New Jersey, pp. 150 et seq.

4. Gear, C. William, "The Simultaneous Numerical Solution of Differential Equations,"IEEE Transactions, Circuit Theory CT-19, 1971, pp. 89-95.

5. McLeod, J., "PHYSBE: A Physiological Simulation Benchmark Experiment",Simulation7 (1966), pp. 324-329

6. Nordsieck, A., "On the Numerical Integration of Ordinary Differential Equations",Math. Comp. 16 (1962), pp. 22-49.

7. Park, Stephen K. and Miller, Keith W., "Random Number Generators: Good ones arehard to find",Communications of the ACM, Volume 31 Number 10, October 1988.

8. Technical Committee on Continuous System Simulation Languages, SimulationCouncils, Inc. (SCi), "The SCi Continuous System Simulation Language",Simulation9 (December 1967), pp. 281-303.

9. Truxal, John G.,Automatic Feedback Control System Synthesis, McGraw-Hill, 1955,pp. 259-266.

ACSL Reference Manual Page E-1

E. References

Page E-2 ACSL Reference Manual

Index

Special characters

! commentprogram 4-16runtime 5-20

; separatorprogram 4-80runtime 5-52

$ common blocks 1-6$ environment variables 4-45& concatenation in macros 6-2& continuation

program 4-19runtime 5-20

* format 4-51* multiplication 2-5* wild card 5-56** exponentiation 2-5+ addition 2-5- subtraction 2-5/ division 2-5/ switch on runtime commands 5-1: label separator 2-4, 4-20= equal sign 4-1? wild card 5-56

A

abbreviating runtime commands 5-1ABS 4-4absolute value 4-4accuracy

loss with large bias 7-19 - 7-20ACOS 4-4ACSL Math 4-88, 5-29ACTION 5-2 - 5-3, A-19

debugging 7-3AGET B-1AINT 4-4aircraft arresting gear example A-34 - A-40aircraft example A-41 - A-51ALCPLT C-1algebraic loops

breaking with PROCEDURAL 4-65determined during sorting 3-5diagnosing 3-6one-line 3-4

algebraic variables 7-6ALGORITHM 4-5 - 4-9

See also integration algorithmsmultiple DERIVATIVE sections 4-26with ACTION 5-3

ALLDISPLAY switch 5-24OUTPUT switch 5-31PLOT switch 5-38PREPARE switch 5-43PRINT switch 5-43RANGE switch 5-48

ALOG 4-10ANALYZE 5-4 - 5-19, A-51, A-69, A-129AND 2-6ANINT 4-10application techniques 8-1 - 8-14APUT B-1arguments

literal constants 4-94macro 6-2PROCEDURAL 4-65PROCEDURE 5-46RESET 4-70single or double precision 4-94

arithmetic macro directives 6-7arithmetic operators 2-5arrays

debug dumps 7-2in sorted sections 4-65integrating 4-50names to avoid 4-29order 2-3plotting 5-38PRINT 5-43program control variables 4-26, 4-32, 4-58, 7-6runtime display 5-24runtime references 5-56runtime SET 5-52subscripts 2-3transferring data B-6

ASIN 4-11aspirin dosage example A-97 - A-101assignment statements 4-11

arithmetic 4-11character 4-11logical 4-11

ATAN 4-12ATAN2 4-12

ACSL Reference Manual Page I-1

B

backlash 4-13band-limited white noise 4-62batch mode A-2BCKLSH 4-12beating 4-49BINARY 5-51blank lines 1-4

with continuations (&) 4-19block IF 4-41block on a rough surface example A-102 - A-115BODE A-120Bode plots

linear analysis 5-12nonlinear systems 8-2

BODE, ANALYZE switch 5-12BOUND 4-13

comparison with LIMINT 4-53boundary value example A-23breakpoints in TABLE 4-86

C

C subroutines 8-11 - 8-12CALCPL C-3CALL 4-13CALPLT C-1CALSPL C-5Cartesian coordinates 4-66, 4-71case sensitivity A-1CHARACTER 4-93

default for plots C-2in COMMON blocks 4-17OUTPUT switch 5-32PLOT switch 5-36START switch 5-55with SET 5-2

character constants 2-2character expressions 2-7CINDEX 5-14CINTERVAL 4-14 - 4-15, 4-33, A-36

calculating in program 4-14integration step size calculation 4-6strobe effect 4-49

CIOITG C-8CJVITG C-8CLEAR

ACTION switch 5-3ANALYZE switch 5-7OUTPUT switch 5-31PREPARE switch 5-42

CLOSEPLOT switch 5-38program statement 4-16

CMD 5-26, C-9specifying new file 5-27

CMDFILE FILE switch 5-26CMPXPL 4-16coding procedure 1-4COLOR 5-36command file A-2commands, runtime 5-1 - 5-56comment (!)

program 4-16runtime 5-20with continuation (&) 4-19with separator (;) 4-80

COMMON 4-17, A-76common blocks 4-17

DEBUG printout 7-6Fortran subroutines 1-6

common logarithm 4-55communication interval

See CINTERVALconcatenation (&) 6-2, 6-12CONSTANT 4-18

comparison with assignment statement 4-18placement in program 3-5

constants 2-1 - 2-2DISPLAY switch 5-24in PROCEDURAL header 4-65

continuation (&)program 4-19runtime 5-20with comment 4-17

CONTINUElabeled statements 2-4, 4-20MACRO 6-7runtime command 5-21with DO loop 4-32with REINIT 5-50

continuoussystem symbols C-3 - C-4

controlruntime executive 5-1transfer with IF 4-40

control loop example A-9 - A-12CONTROL, ANALYZE switch 5-5, A-129controls

linear analysis 5-5, 7-17, A-91, A-117COS 4-20Coulomb friction A-103counters 3-4cpu time 5-54, A-61CSSITG C-8

Index B - C

Page I-2 ACSL Reference Manual

D

DASSL 4-8DATA

PLOT switch 5-38runtime definition 5-22 - 5-23SMOOTH 4-81USEDBV 4-96

data logging 4-14, 4-33, 5-42forcing 4-55, 5-31

data typeruntime commands 5-2, 5-52

DBLE 4-20DBLINT 4-21DCVPRN 5-53, A-129, C-8DEAD zone operator 4-22DEBUG A-17, B-2debugging 7-1 - 7-20

summary output 8-3system symbols 7-5with LOGD 4-56without system debugger 7-3

defaultMACRO 6-10

DEFPLT C-1DEGREE 5-14DELAY

ANALYZE switch 5-14DELSC 4-24DELVC 4-25HISTORY 4-39program operator 4-22 - 4-23scalar 4-24vectors 4-25

delay, computational A-95DELSC 4-24DELVC 4-25DERIVATIVE 3-1, 4-25 - 4-27

in place of PROGRAM statement 4-66derivatives 4-47, 4-50, 7-6

calculation with RESET 4-70DERIVT 4-28DEVPLT C-2DFXFPL C-6dictionary

AGET, APUT B-1system 5-24, B-1user A-88, B-4

differential algebraic system solver 4-8digital controller A-90DIM 4-28, A-36DIMENSION 4-29, 4-93, A-74direction cosine matrix A-76DIS 5-26, C-9

high volume data C-8discontinuities

handling with DISCRETE 4-78handling with Runge-Kutta-Fehlberg 4-8handling with SCHEDULE 4-73resulting from approximations A-97

DISCRETE 3-2, 4-30 - 4-31, A-91data logging 4-56executed by SCHEDULE 4-72INTERVAL 4-49synchronizing 8-13 - 8-14

discrete sampled compensator example A-90 - A-96DISFILE FILE switch 5-26DISPLAY

ANALYZE switch 5-16runtime command 5-24 - 5-25

DISSTR B-2DO loop 4-32

operators not allowed 4-2sorted sections 4-33

documentation 8-3dot product A-74

macro 6-11double precision A-70

constants 2-2conversion to 4-20selecting global 4-3

DOUBLEPRECISION 4-93DPNPLT C-2DPSITG C-8DSCPLT C-2DTCFPL 5-13, C-6dummy variables 2-1

derivatives 7-6with TABLE 4-88

DWNFPL 5-12, C-6DWXFPL 5-12, C-6DYNAMIC 3-2, 4-33, 4-45

E

ECSITG C-8EIGEN 5-8eigenvalues 5-8, A-86, A-116eignevectors 5-8EMNFPL 5-13, 5-15, C-6EMXFPL 5-13, 5-15, C-6END

DATA definition 5-22DERIVATIVE definition 4-25DISCRETE definition 4-30DYNAMIC definition 4-33INITIAL definition 4-45PROCEDURAL definition 4-64PROGRAM definition 4-66program statement 4-34runtime command 5-26TERMINAL definition 4-89

environment variables 4-45EPDFPL 5-12, 5-15, C-6EPFFPL 5-15, C-6EQ 2-6equal sign (=) 4-1

subroutine calls 4-14

D - E Index


EQUIVALENCE 4-34EQV 2-6ERR CONTROL 7-7error

absolute 4-59absolute vs. relative 7-7allowable 4-59allowable during integration 5-30allowable in trim 5-10predicted 4-59relative 4-59, 5-30summary for variable step integration 4-9

error messages D-1 - D-28Jacobian evaluation 5-6, 7-16 - 7-18

errorscompilation 7-2DO loops 4-33link 7-2translation 7-1

ERRTAG 4-35, 4-59event description 4-73event list 4-27, 4-76

clearing A-32, B-3DISCRETE sections 4-30restoring 5-50saving 5-52

eventscomparison of state and time 4-74RESTORE switch 5-50SAVE switch 5-52

examplediscontinuity with event finder 4-79PID controller 4-28

examples A-1 - A-132aircraft A-41aircraft arresting gear A-34aspirin dosage A-97block on a rough surface (friction) A-102bouncing ball 4-77concatenation 6-12control loop A-9discrete sampled compensator A-90frequency response 5-19limit cycle A-1linear analysis 5-17, A-116missile A-70nonlinear frequency response A-62physiological benchmark A-52pilot ejection A-13plotting 5-39plotting measured data 5-22spring damper A-5state events A-102steady state A-20tank with boiling benzene A-123temperature along radiating fin A-20

EXITMACRO 6-8runtime command 5-26

EXP exponential 4-36EXPF exponential function 4-36

explicit program structure 3-1 - 3-6explicit structure A-13expressions

character 2-7definition 2-5 - 2-8logical 2-6relational 2-6

extrapolation in tables 4-86

F

FCNSW 4-36FDEITG C-8feedback

control example A-116DELAY operator 4-23

FILEPRINT switch 5-44

file handlingCLOSE PLOT switch 5-38CLOSE program statement 4-16FILE runtime command 5-26 - 5-27INQUIRE 4-46macro file 4-71OPEN 4-62runtime command file 5-1

flagfirst step during integration 7-6SCHEDULE 4-72stop A-15terminating run 3-2

floating point numberdefinition 2-2

FLOGSC 5-14flow square root 4-83FLTFPL 5-13, C-6FORMAT 4-37

FORTRAN I/O 4-51SAVE file 5-50

FORTRANcommon blocks 4-17, A-76comparison with ACSL 2-1, 4-94FORMAT 4-37functions 4-1 - 4-98generic vs. non-generic 4-1input/output 4-51, A-36logical unit 4-16, 4-62subroutine library A-70

FRACDL 5-9FRACPM 5-10FREEZE 5-6, A-129FREQMN 5-12FREQMX 5-12frequency plots

system symbols C-6 - C-7frequency response 5-11, 5-19, A-62frequency sweep 5-11 - 5-12, A-65friction example A-102 - A-115

Index F - F


FSQRT 4-83FTSPLT 5-38, C-2function switch operator 4-36

G

GAINDB 5-14GAINMN 5-14GAINMX 5-14GAUSI 4-37GAUSS 4-38GE 2-6GLOGSC 5-14GLTPLT C-2GO TO 4-38

MACRO 6-8Graphic Modeller 1-1GRDCPL C-3GRDFPL C-6GRDSPL C-5GT 2-6

H

HARM harmonic drive function 4-39HELP 5-28HERTZ 5-12, 5-14HI

PLOT switch 5-35HISTORY 4-39HVDPRN A-106, C-8hysteresis 4-13

I

I (infinity) 7-7I/O 4-51IALG

See ALGORITHMICS 5-51IF 4-40 - 4-41

MACRO 6-8with SCHEDULE 4-75

IF-THEN-ELSE 4-40 - 4-41, A-16, A-55IHI

PRINT switch 5-44RANGE switch 5-48

ILOPRINT switch 5-44RANGE switch 5-48

IMAGMN 5-14IMAGMX 5-14IMPLC 4-42 - 4-43, A-123implicit integration 4-42implicit structure 3-1impulse 8-4IMPVC 4-44, A-123INC 5-7INCLUDE 4-17, 4-45independent variable 4-97, A-20

DATA definition 5-22driving PULSE 4-67OUTPUT list 5-30plotting 5-33, A-8PREPARE list 5-42TABLE definition 4-85

infinity 7-7INITD 8-1, B-3INITIAL 3-2, 4-45

in macro 6-2INCLUDE 4-45multiple sections 3-6, 4-46, A-62

initial conditions 4-50, 7-6CONTINUE 5-21debugging 7-2independent variable 4-97INTEG 4-47negative value 4-97reinitialize 5-49trim 5-11

initializationDISCRETE section 4-49of controls 4-31of counters 4-18of states 3-2, 5-4of variables in block IF 4-41

INQUIRE 4-46INT integerization function 4-46INTEG 4-47 - 4-48integer 4-93

definition 2-1dividing by 2-5switch 4-57

G - I Index


integrationbasis of simulation 1-2control 4-6data during process C-9description of procedure 4-6, 4-47DISCRETE sections 4-31double limited operator 4-21error summary C-9first evaluation each step 7-6implicit 4-42limiting 4-53system symbols C-8vector 4-50, A-70

integration algorithms 4-5 - 4-9Adams-Moulton 4-7, A-50change during run 4-6comparison of efficiency 4-10, A-51fixed step 4-6, 4-58Gear's stiff 4-8Runge-Kutta 4-6, A-50Runge-Kutta-Fehlberg 4-8user-supplied routine B-3variable step 4-7variable step summary message 7-7, A-50

integration step sizeadjusting to CINT 4-14affected by events 4-27calculated by ACSL 4-6, 4-58choosing 4-9, 4-27, 4-92, 7-4, A-36limiting 4-58restarting B-5variable step 4-27with PULSE 4-67

interactive runtime A-2interpolation

LINEAR 4-54plot boundaries A-8SMOOTH 4-81 - 4-82TABLE 4-86

INTERVAL 4-49, A-91strobe effect 4-49

INTVC 4-50, A-80INVNYQ 5-13iterating for solution A-33IVAR

PRINT switch 5-44RANGE switch 5-48

J

Jacobian matrix 5-8, A-86dimensions 5-5during integration C-9formation 5-5

JACOBIAN, ANALYZE switch 5-8, A-51job processing 1-2

K

Kirchoff's Law 4-42

L

labels 4-38definition 2-4with macro expansions 2-4with TABLE references 4-88

language elements 2-1 - 2-8LE 2-6lead-lag compensator 4-51LEDLAG 4-51LIMINT 4-52 - 4-53limit

integrator 4-53number of sections 4-32second integral 4-21variables 4-13

limit cycle example A-1 - A-4, A-102LINCPL C-3LINEAR 4-54linear analysis 5-4 - 5-19

See also ANALYZElinear analysis example A-116 - A-122LINES 4-54LINPACK 4-95LINSPL C-5LIST

ANALYZE switch A-117LIST, ANALYZE switch 5-16LISTD A-88, B-4lists

ANALYZE 5-5LO

PLOT switch 5-35LOCATION 5-3LOG

natural logarithm function 4-55PLOT switch 5-35

LOG10 4-55LOGD 4-55, 5-31, A-32, A-91, A-106LOGICAL 4-93logical constants 2-2logical expressions 2-6logical IF 4-40logical operators 2-6logical switch 4-57

Index J - L


logical unitCLOSE program statement 4-16CMD C-9DIS C-9FORTRAN I/O 4-51INQUIRE 4-46OPEN 4-62PLT 5-38, C-9PRN 5-43, A-106, C-10RRR C-10

loop from TERMINAL to INITIAL 8-1, A-20LSW 4-57LT 2-6LTCCPL C-3LTCFPL C-6LTCSPL C-5LTFCPL C-4LTFSPL C-5LU decomposition 4-95lump mass A-53

M

macros 6-1 - 6-18CMPXPL 4-16comparison with subroutines 6-1concatenation 6-12, A-53DBLINT 4-21definition header 6-4 - 6-5definitions 6-4directive statements 6-6 - 6-10GAUSS, GAUSI 4-37HISTORY 4-40invocation 6-17 - 6-18operators 4-3placement of definitions 6-1PTR 4-66REALPL 4-69saving definitions 4-71TABLE 4-86TRAN 4-91

MALPRN C-8matrix operations 8-7 - 8-8

See also Jacobian matrixmacro definitions 6-13

MAX 4-57MAXTERVAL 4-6, 4-58, A-36mean

GAUSS 4-38OU 4-62

memory operatorsin block IF 4-41not allowed in PROCEDURAL 4-2, 4-65

MERRORprogram statement 4-59runtime command 5-30

MIN 4-60MINC 5-7

MINTERVAL 4-35, 4-58 - 4-59containing INTERVAL 4-49

missile airframe example A-70 - A-89missile example

terminating at intercept 8-6MOD modulus function 4-60Monte Carlo 8-9multiple DERIVATIVE 4-25multiply defined symbol 4-65MUMAX 5-9MXOITG C-9

N

names 2-1conflict 4-33generated 2-1, 4-47reserved 1-5, 4-29underscore 2-3

NaN (not a number) 7-7NCIOUT 5-31, A-17NCIPRN 5-44NCTPRN C-8NDBUG 7-2, A-87, C-9NE 2-6nearest integer 4-60nearest whole number 4-10NEDFPL 5-15, C-7NEQV 2-6NESFPL 5-13, C-7nesting

INCLUDE 4-45PROCEDURE 5-45sections 3-6

Newton step 5-9NGXPPL C-3NGYPPL C-3NICHOLS 5-13NINT 4-60NITRMX 5-10NOBINARY 5-51NOHEADER

PRINT switch 5-45noise 4-62nonlinearity 7-17nonrepeatability 7-16NOT 2-6NOXLOG 5-34NPBPLT C-2NPBPRN A-129NPCCPL C-4NPCPPL C-3NPCSPL C-5NPXPPL C-3NPYPPL C-3NRWITG C-9

M - N Index


NSTEPS 4-61array 4-61fixed step algorithms 4-6, 4-61variable step algorithms 4-9, 4-61

NXEITG 4-27, C-9NYQUIST 5-13

O

obserables A-117observables

Jacobian matrix 7-17OBSERVE 5-5, A-129OINDEX 5-15OPEN 4-62operating system commands 5-55operators

arithmetic 2-5logical 2-6precision 4-3relational 2-6standalone form 4-3

OR 2-6OU Ornstein-Uhlenbeck function 4-62OUTPUT 5-30 - 5-31, A-3

with LOGD 4-56OVER 5-39, A-99

P

PAGE 4-63PARAMETER 4-64, A-65, A-97

with DIMENSION 4-29parameter sweep

plotting averages 8-9procedure 8-1

parentheses 2-5paths 4-45PAUSE 5-32PC

PLOT specifications 5-37SYSTEM 5-56

PC FAIL 7-7PCWPRN C-8perturbation

controls 5-7states 7-16

phase and gain example A-62 - A-69phase plane plots

See plots, phase planePHASMN 5-15PHASMX 5-15physiological benchmark example A-52 - A-61PI controller A-123 - A-132

PID controller 4-28pilot ejection example A-13 - A-19PLOT 5-33 - 5-41

START switch 5-55X axis switches 5-34, A-8Y axis switches 5-35

plot drivers C-2plots

arrays 8-10automatic scaling 5-33continuous (line) A-36, C-3 - C-4deferred C-1during run 5-32frequency C-6 - C-7logarithmic A-62logarithmic scales 5-42pause between 5-32phase plane 5-34, A-4, A-8scales A-8spooling 5-38strip A-36, C-5system symbols C-1 - C-10title C-10trajectory A-17

PLT 5-26, C-9PLTFILE FILE switch 5-26polar coordinates 4-66, 4-71positive difference function 4-28PPOPLT C-2precision

operators 4-3selecting global 4-3specifying in program 4-3

PREPARE 5-42, A-4plots 5-33

presetderivatives 3-6variables 3-6, 7-2variables in user common blocks 4-17

PRINT 4-51, A-43MACRO 6-9runtime command 5-43 - 5-44system symbols C-8window 5-44

printer plots C-3PRN 5-26, C-10PRNFILE FILE switch 5-26PRNPLT C-2PROCEDURAL 4-64 - 4-65, A-78

comparison with block IF 4-41equal sign in definition 4-2operators not allowed 4-2sorting 4-65variables defined in subroutine 8-5

PROCEDURE 5-45 - 5-46DISPLAY switch 5-25example A-9

PROGRAM 4-66program control

transfer between sections 3-2program flow 3-1 - 3-3

Index O - P


program statements 4-1 - 4-98promotion of integers 2-2, 2-5PSFCPL C-4PSFFPL C-8PSFSPL C-5PTR 4-66PULSE 4-67

Q

QNTZR quantizer function 4-67QUIT 5-47quotation marks 5-1

R

R (NaN) 7-7RAMP 4-68random number generator 4-96

GAUSS 4-38OU 4-62seed 4-37

RANGE 5-48, A-6READ 4-51REAL 4-69, 4-93real switch 4-57REALMN 5-15REALMX 5-15REALPL 4-69rectangular coordinates 4-66, 4-71REDEFINE (MACRO) 6-9REINIT 5-49, A-87

trim initial conditions 5-11RELABEL (MACRO) 6-9relational expressions 2-6relational operators 2-6RELEASE 5-6RESCALE

CONTINUE 5-21START switch 5-55

RESET 4-70, A-106residual 4-42resolution of quantizer 4-67response

closed loop 5-20, A-121open loop 5-19, A-116

RESTORE 5-50CONTINUE 5-21

RMSEMX 5-10RMX 5-14, 5-44root locus 5-15, A-120

RRR 5-26, C-10multiple files 5-27

RRRFILE FILE switch 5-26RSTART B-5RSW 4-57, A-103RTP 4-71RUN

PLOT switch 5-39PRINT switch 5-44RANGE switch 5-49

runtime commands 5-1 - 5-56abbreviating 5-1user-supplied subroutine A-3

S

SAME 5-39, A-99sampled data

macro 6-11SATCPL C-4SATFPL C-7SATSPL C-5SAVE 5-51

program statement 4-71SCALE 4-72SCHEDULE 4-72 - 4-79

activation of DISCRETE 4-49finding limit 4-21, 4-53finding missile intercept 8-7state events 4-76time events 4-75

sectionsDERIVATIVE 3-2, 4-25 - 4-27DISCRETE 3-2, 4-30 - 4-31DYNAMIC 3-2, 4-33INITIAL 3-2, 4-45nesting 3-6TERMINAL 3-2, 4-89

seed for random number generators 4-37separator (;)

program 4-80runtime 5-52with block IF 4-41

SETfilling TABLE data 4-88runtime command 5-52 - 5-53, C-8

SETI, SETR utilities B-5SGN 4-80SIGN 4-80SIN 4-81single precision

conversion to 4-69SLTFPL 5-13, C-7SMOOTH 4-81 - 4-82SORT program statement 4-83

Q - S Index


sorting 3-4 - 3-5, 4-49, 4-64multiple sections 3-6non-sorted sections 4-83

SPARE 5-54, A-3spring

mass-spring-damper A-5 - A-8SQRT 4-83SSNFPL 5-15, C-7SSQRT 4-83SSXFPL 5-15standalone form 4-3, A-9standard deviation

GAUSS 4-38OU 4-62

STANDVAL (MACRO) 6-10START 5-54state events 4-76

implementation 4-77state variables 4-47, 7-6

access during run 4-31, A-105in common blocks 4-17in PROCEDURAL header 4-65initialize 3-2initialized 4-70

STATESRESTORE switch 5-50SAVE switch 5-51

STATUS, ANALYZE switch 5-16steady state

See TRIMsteepest descent step 5-9STEP program statement 4-84step response 8-4STOP flag 3-2strip plots

system symbols C-5strobe effect 4-30, 4-49STRPLT C-2structure

explicit 3-1 - 3-6implicit 3-1See also sections

STYLE 5-37subcommands

See switchessubroutines

C 8-11 - 8-12calling from ACSL 4-13calls requiring PROCEDURAL 4-65common blocks 4-17filling TABLE data 4-87Fortran 1-6user-supplied runtime 5-54, A-3

subscriptsdefinition 2-3

substitutionmacro 6-3

switchesevaluation in DISCRETE 4-78integer 4-57logical 4-57real 4-57runtime command 5-1

symbolson plot curve (CHARACTER) 5-36, C-2runtime data 5-2

SYMCPL C-4SYMSPL C-5SYSTEM 5-55system symbols C-1 - C-10

continuous plots C-3 - C-4debug printout 7-5equivalencing 4-34frequency plots C-6 - C-7integration control C-8logical units C-9 - C-10plots in general C-1 - C-2print data C-8printer plots C-3program control 1-5strip plots C-5typing 4-94

T

TABLE 4-85 - 4-87accessing function 4-85definition 4-85

tabs 1-6TAG 5-36TAN 4-88tank with boiling benzene example A-123 - A-132TBRPLT C-2TCWPRN C-8temperature distribution example A-20 - A-33TERMINAL 3-2, 4-89

in macros 6-2INCLUDE 4-45multiple sections 3-6

terminating a run 3-2, A-2missile intercept 8-6several conditions A-65

terminating condition 4-89, A-15finding with SCHEDULE 4-80

TERMT 3-2, 4-89time

backwards 8-8time constant

complex pole transfer function 4-16first order lag 4-69lead-lag compensator 4-52OU 4-62

time events 4-75TIMES 5-48TITLE 5-46, 5-53, C-10

Index T - T


TJNITG C-9TKHFPL 5-15, C-7TRAN 4-90 - 4-91transfer function A-90

example A-9first order lag 4-69higher order 4-91lead-lag 4-51second order 4-16Z polynomials 4-92

transfer operator A-64translation process 4-48TRANZ 4-92TRIM A-42, A-86, A-129

ANALYZE switch 5-8truncation 4-4TSMITG C-9TTLCPL C-4TTLFPL C-7TTLSPL C-5type 4-93 - 4-95

common blocks 4-17definition in ACSL 2-3OUTPUT switch 5-32PLOT switch 5-36runtime data 5-2START switch 5-55

U

undefined numbers 7-7underscore 2-3UNIF 4-96UNIFI 4-37unit conversions 4-33USEDBV 4-96utilities B-1 - B-6

V

VALUE 5-3valves A-52, A-90VARIABLE

ACTION switch 5-3DISPLAY switch 5-24program statement 4-97

variablesdefinition 2-3See also names

vector integration 4-50vector rotation A-76VECTORS 5-8VERSION

DISPLAY switch 5-26

W

warning message 4-19, A-32WEDITG A-106, C-9WESITG C-9white noise 4-62width

output to terminal A-1print file 5-43, A-1

WIDTH PLOT switch 5-37wild cards

DISPLAY 5-24OUTPUT list 5-31PREPARE list 5-42PRINT list 5-43RANGE list 5-48RESTORE list 5-50runtime 5-56runtime commands 5-20

windowfinding state event 4-78

WNDITG C-9WRITE 4-51

to screen B-2WRITEPREPARE 5-29WXDITG C-9

X

XAXIS 5-34XCICPL C-4XCIFPL C-7XCISPL C-5XERROR

program statement 4-59runtime command 5-30

XFERBI B-6XFERBR 4-50, A-80, B-6XHI 5-34XINC 5-7XINCPL C-4XINFPL C-7XINSPL C-5XLO 5-34XLOG 5-34XTAG 5-35XTICPL C-4XTIFPL C-7XTISPL C-5XZPPLT C-3

U - X Index


Y

YASFPL C-7YASSPL C-6YCICPL C-4YCIFPL C-7YCISPL C-6YINCPL C-4YINFPL C-7YINSPL C-6YTICPL C-5YTIFPL C-7YTISPL C-6YZPPLT C-3

Z

zero crossing function A-103ZEROS 5-16, A-117ZZFRFL 7-6

Index Y - Z


acsl reference manual

Documents