- 3.9.1 Loading commands from a file
- 3.9.2 Changing the seed of random number generation
- 3.9.3 Changing the current directory
- 3.9.4 Dynamically linking new stars
- 3.9.5 Top-level blocks
- 3.9.6 Examining states
- 3.9.7 Giving up
- 3.9.8 Getting help
- 3.9.9 Registering actions
- 3.9.10 The Interface to Matlab and Mathematica

This section describes the remaining interpreter commands.

`s`

using the `set`

`state`

command and running and continuing the simulation using `run`

and `cont`

-this is normally done interactively with the interpreter.
The `source`

command reads interpreter commands from the named file, until the end of the file or a syntax error occurs. The "#" character indicates that the rest of the line is a comment. By convention, files meant to be read by the load command end in ".pt". Example:

source "testfile.pt"The tilde notation for users' home directories is allowed; for example, if your installation of Ptolemy was made by creating a user

`ptolemy`

(see
"Setup" on page 2-1), trysource "$PTOLEMY/demo/ptcl/sdf/basic/butterfly.pt"It is also possible to specify a file to be loaded by the interpreter on the command line. If, when you start the interpreter you type

ptcl myCommands.ptthe interpreter will load the named file, execute its commands, and then quit. No command prompt will appear. The

`source`

command is actually built into Tcl itself, but it is described here nevertheless, for convenience.`seed`

command changes the seed of the random number generation. The default value is 1. The syntax isseed nwhere n is an unsigned integer.

`cd`

command changes the current directory. For example,cd "$PTOLEMY/demo/ptcl/sdf/basic"

source "butterfly.pt"will load the same file as the example in the previous section. Again, we have assumed that your installation contains a user

`ptolemy`

(see
"Setup" on page 2-1). To see what the interpreter's current directory is, you can typepwd

`pigi`

, the graphical interface, the interpreter will not automatically run the preprocessor and compiler; it expects to be given object files that have already been compiled. The syntax islink object-file-nameAny star object files that are linked in this way must only call routines that are already statically or permanently linked into the interpreter. For that reason, it is possible that a star that can be linked into

`pigi`

might not be linkable into the interpreter, although this is rare. Specifically, `pigi`

contains Tk, an X window toolkit based on Tcl, while `ptcl`

does not. Hence, any star that uses Tk is excluded from `ptcl`

.
Building object files for linking into Ptolemy can be tricky since the command line arguments to produce the object file depend on the operating system, the compiler and whether or not shared libraries are used. `$PTOLEMY/mk/userstars.mk`

includes rules to build the proper object file for a star.
See "Dynamic linking fails" on page A-30. for hints about fixing incremental linking problems.

multilink opt1 opt2 opt3 ...where the options may be the names of object files, linker options such as "-L" or "-l" switches, etc. These arguments are supplied to the Unix linker along with whatever options are needed to completely specify the incremental link.

When the above linker commands are used, the linked code has temporary status; symbols for it are not entered into the symbol table (meaning that the code cannot be linked against by future incremental links), and it can be replaced; for example, an error in the loaded modules could be corrected and the `link`

or `multilink`

command could be repeated. There is an alternative linking command that specifies that the new code is to be considered "permanent"; it causes a new symbol table to be produced for use in future links (See the ptlang `derivedFrom`

item in the Ptolemy Programmers Manual for more information). Such code cannot be replaced, but it can be linked against by future incremental link commands. The syntax is

permlink opt1 opt2 opt3 ...where the options are the same as for the

`multilink`

command.topblocksreturns the list of top-level blocks in the current galaxy or universe. With an argument,

topblocks blockit returns the list of top-level blocks in the named block.

`statevalue`

command takes the formstatevalue block stateand returns the current value of the state state within the block block. The command takes an optional third argument, which may be either

`"c`

`urrent"`

to specify that the current value should be returned (the default), or `"`

`initial`

`"`

to specify that the initial value (the parameter value) should be returned.`exit`

command exits the interpreter. The syntax isexit

`help`

command implements a simple help system describing the commands available and their syntax. It does not provide help with the standard Tcl functions. The syntax ishelp topicor

help ?for a list of topics. If the argument is omitted, a short "help on help" is printed.

`registerAction`

command does this. The syntax isregisterAction pre tcl_command

registerAction post tcl_commandThe first argument specifies whether the action should occur before or after the firing of a star. The second argument is a string giving the first part of a tcl command. Before this command is invoked, the name of the star that triggered the action will be appended as an argument. For example:

registerAction pre putswill result in the name of a star being printed on the standard output before it is fired. A typical "action" resulting from this command would be

puts universe_name.galaxy_name.star_nameThe value returned by

`registerAction`

is an "action_handle", which must be used to cancel the action using `cancelAction`

. The syntax isset action_handle [registerAction pre tcl_command]

cancelAction action_handle

`matlab`

and `mathematica`

commands. The commands have a similar syntax:matlab command ?arg1? ?arg2?The

mathematica command ?arg1? ?arg2?

`matlab`

command controls the interaction with a shared Matlab process. The possible commands and arguments are:
The `mathematica`

command controls the interaction with a shared Mathematica process. The possible commands and arguments are

To initiate a connection to a Matlab and Mathematica process, use

matlab start

mathematica startTo generate a simple plot of a straight line in Matlab and Mathematica, use

matlab send { plot([0 1 2 3])}

mathematica send { Plot[x, {x, 0, 3} ] }The

`send`

command suppresses the output normally returned by interacting with the program using the command interface. The `eval`

command, on the other hand, returns the dialog with the console interface:mathematica eval { Plot[x, {x, 0, 3}] }

-Graphics-To terminate the connection, use

matlab end

mathematica endOne can work with matrices as Tcl lists or in Matlab format. To create a new Matlab matrix x that has two rows and three columns:

matlab set x 2 3 "1 2 3 4 5 6" "1 1 1 1 1 1"We can retrieve this Matlab matrix in the same format:

matlab get xWe can also retrieve the matrix elements as a Tcl list of complex numbers in an ordered-pair format:

2 3 {1.0 2.0 3.0 4.0 5.0 6.0} {1.0 1.0 1.0 1.0 1.0 1.0}

matlab getpairs xNow, matrices can be manipulated in both Tcl and Matlab.

(1.0,1.0) (2.0,1.0) (3.0,1.0) (4.0,1.0) (5.0,1.0) (6.0,1.0)

Javier Contreras contributed the following example that creates a Tcl list, sends it to MATLAB as a 2x2 matrix, calculates the inverse in MATLAB and retrieves it back to Tcl as list and/or pairs.

ptcl> matlab startFor other examples of the use of the matlab and mathematica Ptcl commands, see "Using Matlab and Mathematica to Compute Parameters" on page 2-18. These commands support the Matlab and Mathematica consoles in Tycho.

ptcl> set a 1

1

ptcl> set b 2

2

ptcl> set c 3

3

ptcl> set d 4

4

ptcl> set e [expr "{$a $b $c $d}"]

1 2 3 4

ptcl> set f [expr "{$a $b $c $d}"]

1 2 3 4

ptcl> matlab set matrix $b $b $e $f

ptcl> matlab eval {matrix(1,1)}

>>

ans =

1.0000 + 1.0000i

ptcl> set inv_matrix [matlab get inverse {inverse = inv(matrix)}]

2 2 {-1.0 0.5 0.75 -0.25} {1.0 -0.5 -0.75 0.25}

ptcl> set inv_matrix [matlab getpairs inverse {inverse = inv(matrix)}]

(-1.0,1.0) (0.5,-0.5) (0.75,-0.75) (-0.25,0.25)

ptcl> set new $inv_matrix

(-1.0,1.0) (0.5,-0.5) (0.75,-0.75) (-0.25,0.25)

ptcl> lindex $new 0

(-1.0,1.0)

ptcl> matlab unset matrix

ptcl> matlab eval {matrix(1,1)}

ptcl> matlab end