Acumen User Guide

Release Notes: Version 1.0, based on Acumen alpha_2007_11_01.

Authors: The Acumen Development Team at Rice.

Acumen is a simulation environment for continous-time physical systems containing event-driven controllers. This document is aimed at mechanical engineers interested in modeling and simulating such systems. The document familiarizes the user with the layout and functionality of graphical user interface, and explains how to write physical descriptions in the PhyDL component of Acumen, as well as how to write reactive controllers using the RIDL component. The document also defines the syntax for the primitive operations provided by Acumen, and explain how to control a simulation.

Acknowledgements: This work was funded by the National Science Foundation and Schlumberger.

Preliminaries. Acumen = PhyDL + RIDL

When the Acumen environment is started, the language for modeling physical part is located on the left-hand column of the screen, which is called PhyDL (Physical Description Language). The language for modeling controller part is located on the upper right-hand area of the screen, which is called RIDL (Reactive Interrupt Driven Language). Following is a snapshot of Acumen user interface.

Comments in Acumen are enclosed in (* *). So the text within these starred parentheses will be ignored by Acumen and will serve solely as a comment for the user:

(* This is just comment of the program. *)

Important Note on Syntax: Throughout this guide, when example syntax is given for a code, the semi-colons found at the end of some lines of code are necessary for the code to run properly.

PhyDL

A PhyDL program is organized into several modules, namely:

• System,
• Boundary,
• Simulation,
• Interaction with Control Description (External Module for RIDL code), and
• Interaction with MATLAB (External Module for MATLAB).

To model a given system in Acumen, we need to give PhyDL certain information for each module. Each module starts with a heading. This is followed by specific information about either the system or how to simulate or visualize it falls. For example, boundary conditions should be listed in the Boundary Module. In the rest of this section, we explain each of these modules in more detail.

System Module (Inputting System Equations and Constants)

A dynamical system can be described by a set of differential equations together with definitions of the variables in these equations. For example, a simple pendulum can be described by a differential equation with some boundary conditions:

theta''=-1/I* (m*l*sin(theta) + F*l*cos(theta);
theta(0) = 0.1;
theta'(0)=0;

The first equation above describes the dynamics of this system, that is, the second derivative of theta. The next two equations give the initial conditions of the system, in this case, the initial position and initial velocity of the pendulum (theta and the first derivative of theta.) The following is a picture of a simple pendulum.

Differential equations and constants for a system are listed under the System Module in Acumen. First let us explain how to code differential equations:

PhyDL allows you to write differential equations directly. However, some restrictions apply:

• The left hand side (LHS) of an equation must be a single variable or some derivative of a variable. (Derivatives are represented by an apostrophe. ex: x'(t) is the first derivative of x(t).)
• For each variable, the highest order derivative that appears on the right hand side (RHS) of an equation must be less than the order of the derivative on the left hand side. (ex: you cannot have an equation such as: x'(t) = x''(t) - x(t), because the highest order on the LHS is 1 which is less than the highest order on the RHS which is 2. The proper way to express this equation is: x''(t) = x'(t) + x(t).) The prescribed syntax the System Module:

system
    <var>^(n) = exp;

where ^(n) denotes n-times derivative (in other words, the nth derivative of a variable.) An example of a correct System Module code is:

system
    theta''= -1/I* (m*l*sin(theta) + F*l*cos(theta);

Now, we will cover how to code variables. In a PhyDL program, no free variables are allowed. In other words, if a variable appears in any equation, then it must be defined within the program. For example, the differential equation we have been working with has variables which represent mass (m), length (l), etc. So in order to describe the system these variables must be defined. In Acumen, this should be done in the System Module. The following code for the System Module is an example of how to code both variables and the differential equation of the system:

system
    m = 0.5;  (* mass *)
    l = 0.3;  (* length *)
    I = m * l * l;  (* moment of inertia *)
    theta''= -1/I* (m*l*sin(theta) + F*l*cos(theta);  (*differential equation of system*)

Boundary Module (Inputting Boundary Conditions)

To describe a system in PhyDL, we must list boundary conditions in the Boundary Module. Keep in mind that if the highest order of derivative of a variable is n, then the boundary conditions listed must include the value of this variable for each derivative from the (n-1)th derivative to the 0th derivative. The syntax for listing boundary conditions is as follows:

boundary
    <var> with <var>(0) = <number>, <var>'(0)=<number>;

For example:

boundary
    theta with theta(0) = 0.1, theta'(0)=0;

Simulation Module

The first module listed in PhyDL, the Simulation Module, gives PhyDL information about the simulation. With representing any number, the syntax for the commands that are used to specify the conditions of starting time, ending time and step size at which the system should be evaluated are:

simulation
    starting_time = <number>;
    ending_time = <number>;
    step_size = <number>;

Here, the unit of time is second. The value of the starting time must be less than or equal to the value of the ending time. The step size value is used for numerical computation, it is the mesh of partition to discretize the continuous time. An example of correct simulation code is:

simulation
    starting_time = 0;
    ending_time = 30;
    step_size = 0.001;

External Module for RIDL Code (Interaction with Control Description)

A RIDL program describes the control information of the system. A PhyDL program can interact with a RIDL program in the External Module. However, the External Module is not simply for RIDL functions. (We shall see soon how PhyDL can interact with MATLAB as well in the following section.) The control input is taken from an external program written in RIDL. The syntax for calling an external RIDL controller is:

external ridl "filename.ridl" 
   reads     <var>, <var>, ... ;
   writes    <var>, <var>, ... ;
   observes  event <var> rate t = <number>,
             event <var> when t = <number>;

Each var above is a string which represents a variable name in the specified RIDL program. During simulation, PhyDL needs to get control information from RIDL, while RIDL needs to "observe" some system state from PhyDL. The sections reads and writes provide a mechanism to communicate between the PhyDL program (the physical system) and a RIDL program (that system's controller.) Variables specified in reads are those whose value is "read" by a RIDL program and are generally used to calculate the new controller input. Variables specified in writes are those whose value is calculated by the RIDL program.

In the observes section, "event", "rate" and "when" are keywords which cannot be changed. Since RIDL models event-driven discrete-time controllers, we need to specify when the controller will "read" a variable's value at an instantaneous state of the system, possibly determine whether some interesting event has occurred, compute ("write") a new control value based on the system's instantaneous state which was "read," and communicate this control information back to the PhyDL program. If observes event ... rate t= n is coded, the "reading" of the instantaneous state of the system and computation ("writing") of the control values for that particular state happens at rate of once every n seconds. If observes event ... when t= n is coded, the observation and computation happens just once when t is equal to the specified time n. An example of syntax for the External Module calling a RIDL program is:

external ridl "simple_pendulum_control.ridl" 
   reads     theta ;
   writes    F ;
   observes  event clock rate t = 0.1;

External Module for MATLAB (Interaction with MATLAB)

The External Module in PhyDL links the PhyDL program to an external program. One commonly used external program is MATLAB. In order to plot simulation results of a function to produce a program visualization, you use the following syntax:

external matlab  
   reads     <variable>, <variable>, ... ;

Here we have "reads" which specifies that MATLAB will read the system data for the listed variables and plot it. These variables are the dependent variables of a system and MATLAB plots them with respect to time. If a variable is defined as a constant in system equations, Acumen will choose not to display it and throw an error message.

RIDL

RIDL programs are coded separately from PhyDL programs and are meant to act as interchangable controllers for a given PhyDL program. As stated before, while simulation takes place, the PhyDL program needs to acquire control information from a given RIDL program, while this RIDL programs must "observe" the system state from the PhyDL program. In order to understand how to code a RIDL program, it is best to study examples. Let us first take a look at the following simple RIDL program:

theta = 0.1;
F = init 0 in 
   { clock => -4.9 * theta }

We suppose here that we have a global event named "clock". The frequency of this event is not determined in the RIDL program, but is specified in the PhyDL code that calls the RIDL program. The first line in this example program states "theta" is simply a variable with value 0.1. The second and third lines in this program define a variable "F". In this case, F is a "reactive behavior," which means that the value of F will be updated when some event happens (in this case, the event is called "clock".) The syntax "init 0" means that the initial value of F is 0, that is, at time t=0 or just after the system is reset F = 0. The information within the curly brackets is the event handler, clock => -4.9 * theta states that when the event called "clock" happens, RIDL should compute F, using the formula F=-4.9 * theta.

Now let's examine a more complex RIDL example:

theta = init y=0.1 in 
   { clock => -1 * y }

We now have re-defined "theta" to be a "reactive behavior" as well. The first line of code states that at time t = 0, theta = 0.1. The variable y is a temporary variable name for theta. Temporary variables are used when the new value of a variable is dependent on the former value. The second line specifies that when the event "clock" occurs, RIDL should compute theta using the formula theta=-1*y. We see here that the temporary variable y was needed so that a new theta value could be assigned based on the old one. So, this example code states that at time t = 0, theta = 0.1. After the event "clock" occurs once, theta = -0.1. When the event "clock" occurs a second time, theta = 0.1. Etc.

A Complete Example

In Acumen, PhyDL and RIDL work together through the External RIDL Module in PhyDL. (Please see "External Module for RIDL Code" above.) Thus, it is possible to use a variable in RIDL whose value is only defined in PhyDL or vice versa. For example, the following RIDL program uses theta in order to compute F but only defines theta in PhyDL.

(* RIDL program *)
F = init 0 in 
   { clock => -4.9 * theta }

(* PhyDL program *)
simulation
   starting_time = 0; ending_time = 30; step_size = 0.001; 

external ridl "pendulum_control.ridl"
   reads     theta;              
   writes    F;            
   observes  event clock rate t = 0.1;   

external matlab
   reads theta, F;

boundary
   theta with theta(0)= 0.1, theta'(0)= 0;         

system
   m = 0.5;
   g = 9.8;
   l = 0.3;
   I = m * l * l;
   theta'' = - 1/I * (m*g*l*sin(theta) + F*l*cos(theta));

The following picture illustrates the result.

Primitive Values and Functions in PhyDL

In PhyDL, We support following primitive functions:

Name	Symbol	Syntax	Examples
pi	pi		pi, sin(pi/3), cos(pi/5)
array	[ , ]	[<exp>, <exp>, ...]	[1,2,3], [x, y], [[1,2],[3,4]]
add	+	<exp>+<exp>	1+2, 3.4+1, x+y, [1,2]+[3,4]
substract	-	<exp>-<exp>	1-2, 3.4-1, x-y, [1,2]-[3,4]
multiplication	*	<exp>*<exp>	1*2, 3.4*1, x*y, 1.1*[2,3], [2,3]*1.1, [1,1]*[2, 3]
cross	cross(,)	cross([<exp>, <exp>, <exp>], [<exp>, <exp>, <exp>])	cross([1,2,3], [1,0,1]), cross([x,y,z],[2,3,4]), proj([x1,y1,z1], [x2, y2, z2])
division	/	<exp>/<exp>
exponential		<exp>^<exp>	1^2, 3.4^1, x^y, [2,3]^1.1
square root	sqrt()	sqrt(<exp>)	sqrt(1.1), sqrt(x), sqrt([2,3])
sin	sin()	sin(<exp>)	sin(1.1), sin(x)
cos	cos()	cos(<exp>)	cos(1.1), cos(x)
tan	tan()	tan(<exp>)	tan(1.1), tan(x)
atan	atan()	atan(<exp>)	atan(1.1), atan(x)
square root	sqrt()	sqrt(<exp>)	sqrt(1.1), sqrt(x), sqrt([2,3])
unit vector	unit()	unit(<exp>)	unit(1.1), unit(x), unit([2,3])
absolute value	abs()	abs(<exp>)	abs(1.1), abs(x), abs([2,3])
project	proj(,)	proj([<exp>, <exp>], [<exp>, <exp>])	proj([2,3], [1,0]), proj([x,y],[2,3]), proj([x1,y1], [x2, y2])
rotation	rotate(,)	rotate([<exp>, <exp>], <exp>)	rotate([2,3], 1.1), rotate([x,y],1.1), rotate([x1,y1], x)
comparison	<, >, ≤, ≥, =	<exp><exp>	1>2, 4<2, 4≥5, ...
if.then.else	if...then...else...	if <exp> then <exp> else <exp>	if (x>1) then x+1 else x-1

Running an Acumen Program

In the Simulation Controls section located in the middle of the right hand portion of the screen, there are two buttons which control the running of a simulation. One is "reset" and the other is "step". The "reset" button resets the system settings and state to the initial conditions. This button should be clicked on before performing any new simulation in order to ensure that the simulation begins from the initial conditions. In order to actually run a simulation, one must simply click on the "step" button which triggers the simulation. Acumen will generate information on the final state of the system that can be found within the Simulation Controls box under the tab "Final State" as well as run this information through MATLAB (assuming the External Module for MATLAB is included in the PhyDL code) which will return the desired plot. The "Trace" in the Simulation Controls box displays information about the system at intervals from the initial state to the final state.

As far as plotting the results of a simulation, whenever "reset" is clicked Acumen clears the picture of the last trace. Then, when "step" is clicked, Acumen updates the current plot with the newest simulation results. In the current Acumen package, "trace_matlab" is the file that keeps the trace after simulation. If the External Module for MATLAB is used in a code, MATLAB is triggered when we click on "step". When the simulation results are updated the file "trigger_matlab" holds these results. Thus, when an action happens in PhyDL, we write some information into this file. This is monitored by Acumen and when the file has some new information, MATLAB will be triggered again and make modifications according to the information in the file "trigger_matlab".

References

• Acumen_talk.pdf
• examples.zip

Access Permissions

• Set ALLOWTOPICCHANGE = Main.SlbGroup, Main.AcumenGroup