OOF: Finite Element Analysis of Microstructures
Table of Contents
All of the commands in the ppm2oof Menus and many of the operations in the Dashboards can be executed from a text interface. Executing text commands is very handy if you want to automate a process, or run ppm2oof logged in from home over a slow telephone line. The format for the text commands is the same, whether commands are being typed interactively, are being read from a log file or command file, or being executed as macros.
If you've read about the text interface in oof, you can probably skip much of this section, since oof and ppm2oof share the same command parser.
The text interface is invoked in two different types of situations:
Running in Text Mode: Starting ppm2oof with the -text start up option puts it into text mode. No graphics windows will be created.
Running Scripts in Graphics Mode: When -text is not specified, ppm2oof is in graphics mode. The text mode command parser is still used, though, when processing -start command line options and running scripts with the /commandfile function.
As far as the command parser is concerned, the only differences between the two modes are that operations that rely on a mouse click on the image are naturally not available in text mode. Graphics operations in log files all begin with graphics xxx, where xxx is a number indicating the graphics drawer where the command was issued. [36]
Menu Commands: In text mode, the commands are simply the names of the submenus, functions, and variables from the menus. For example, typing select enters the /select menu, typing quit executes the /quit function, and typing width prints the value of the /width variable. Section Variables below explains how to set variables, and Section Combining Commands shows that you can combine submenu names and function names in the intuitive way.
Graphics commands: The easiest way to learn the text mode equivalent of a graphics window command is to execute the command and use the use the /log menu functions to save it to a file. For example, the following sequence
Run /log/start with file=mylog.
Switch to the Select dashboard.
Press the Clear button.
Run /log/stop.
graphics 0 dashboardnumber = 2 graphics 0 dashboard Select select_noneThe first line sets the dashboard, and the second line is the equivalent of the Clear button.
To run ppm2oof with the text interface, start it up with the -text option. You will be presented with a prompt like this:
ppm2oof >>All of the Menus, Functions, and Variables in the graphical interface are available in the text interface. In general, to invoke any one of them you just type its name at the prompt. All names can be abbreviated, as long as enough of the name is provided to distinguish it from all other legal options.
To see a list of the available options, type a question mark:
ppm2oof >> ? === Type "?? xxx" to get help on option "xxx". === Choices are (command* menu/ variable=) : width= seed= ppmfile* commandfile* pause* quit* graphics/ select/ active_area/ firewalls/ pixelgroups/ materials/ simple_mesh/ adaptive_mesh/ macros/ log/ configuration/ ppm2oof >>A name followed by an equals sign (=) is a Variable, a name followed by an asterisk (*) is a Function, and a name followed by a slash (/) is a Menu. Typing two question marks followed by a Menu, Function, or Variable name will give more information about that specific object:
ppm2oof >> ?? width width = 1: width in physical units ppm2oof >> ?? adaptive_mesh anneal anneal: optimize mesh by simulated annealing
Typing the name of a Submenu transfers control to that Submenu, and the next command typed must be an item from the new menu. Normally, after executing a Function or Variable within a Submenu control is returned to the main ppm2oof menu. To suppress this, use parentheses to group submenu commands (see Section Combining Commands). To escape from a Submenu without executing any other commands, type <.
When in a Submenu, the prompt changes to the name of the Submenu:
ppm2oof >> adaptive_mesh adaptive mesh >> refine refine >>
Typing the name of a Function executes that function. If the function has arguments, they should be provided on the command line after the function name. Each argument must have the form name=value. The order of the arguments doesn't matter. Commas may be used to separate arguments, but they're optional. Here is an example from the /adaptive_mesh/refine menu:
refine >> depth min=2 max=7 iterations=3If the command is being executed interactively (i.e, at the keyboard, not from a command file or macro), then ppm2oof will ask for any omitted arguments. The default value of each argument is printed in brackets; type a new value or just hit return to accept the default.
refine >> depth *Enter iterations [3]: return *Enter min [2]: 4 *Enter max [7]: 5The default values for the arguments are the values used the last time the command was executed.
Typing the name of a variable prints its current value. Typing name = value sets the current value. Typing name =, omitting the value, makes ppm2oof prompt you for a new value. As with Function arguments, hitting return without entering a value retains the old value.
ppm2oof >> width width = 1 ppm2oof >> width = 1.e-6 ppm2oof >> width = *Enter width [1e-06]: 1.e-7
Multiple commands can be typed on one line. We've already seen a special case of this, namely, you can execute Functions from Submenus like this:
ppm2oof >>adaptive_mesh refine all iterations=1instead of like this:
ppm2oof >> adaptive_mesh adaptive mesh >> refine refine >> all iterations=1Semicolons can be used to delimit commands. They are optional unless you're omitting arguments, in which case the semicolon is required so that ppm2oof doesn't try to interpret the second command as an argument of the first one. This is ok:
ppm2oof >> adaptive_mesh refine all; select none *Enter iterations [1]:This isn't:
ppm2oof >> adaptive_mesh refine all select none === "select" is not a recognizable argument! === Command "all" not executed.It's a good idea to use semicolons after all Functions and Variables when combining commands on one line.
When executing multiple commands from a single Submenu, parentheses can be used to keep ppm2oof from popping back to the main menu after each Function or Variable. Parentheses can be nested. For example,
ppm2oof >> adaptive_mesh select all ppm2oof >> adaptive_mesh refine selectedcan be written as
ppm2oof >> adaptive_mesh (select all; refine selected)
Macros are defined by typing a series of commands enclosed in braces {}, followed by the name of the macro. If the name isn't supplied and you're running ppm2oof interactively, ppm2oof will ask you for a name. The macro will be installed as a Function in the Menu where you began the definition.
This example installs a macro named "run" in the main menu:
ppm2oof >> {commandfile filename=mylog} run
This example installs a macro called
"twogroups" in the /select menu, assuming that groups A and B
are already defined:
ppm2oof >> select {select group (A; B)} twogroups
Notice that the commands within the braces are interpreted
as commands in the Main Menu, not the /select menu.
The text interface can read macro files generated by the graphical interface, and vice versa.
ppm2oof's text interface is used when running interactively in text mode, and when loading command file scripts in either text mode or graphics mode. The only difference between interactive and scripted operations is that in scripts you must be careful not to do anything interactive. :-) In particular, you can't omit arguments to functions, because ppm2oof will try to ask you for the missing arguments. You also can't use the variable= format for querying and setting variables. You can still use variable=value to set values, of course.
The following characters have special meaning to the text command parser and therefore should not be used in anything that might become a command (such as an element or pixel group name) or a function argument.
| (space) | delimits words | |
| ; | (semicolon) | delimits commands, ends argument lists |
| % | (percent) | begins comments in command files |
| () | (parentheses) | group commands within a submenu |
| " | (quotation mark) | delimits string Function arguments containing spaces |
| ? | (question mark) | lists Menu options, or, when doubled, gets help on a specific option |
| = | (equals) | separates Variables and Function arguments from their values |
| , | (comma) | delimits Function arguments (optional) |
| < | (less than) | exits a Submenu |
| {} | (braces) | surround macro definitions |
Depending on how it was compiled, ppm2oof either uses the GNU readline package or version 1.11 of the editline library by Simmule Turner and Rich Salz. editline is distributed with the OOF source code for systems without readline installed. The two systems are meant to be compatible. Here are the relevant parts of the editline manual:
A program that uses this library provides a simple emacs-like editing interface to its users. A line may be edited before it is sent to the calling program by typing either control characters or escape sequences. A control character, shown as a caret followed by a letter, is typed by holding down the control key while the letter is typed. For example, ^A is a control-A. An escape sequence is entered by typing the escape key followed by one or more characters. The escape key is abbreviated as ESC. Note that unlike control keys, case matters in escape sequences; ESC F is not the same as ESC f.
An editing command may be typed anywhere on the line, not just at the beginning. In addition, a return may also be typed anywhere on the line, not just at the end.
Most editing commands may be given a repeat count, n, where n is a number. To enter a repeat count, type the escape key, the number, and then the command to execute. For example, ESC 4 ^f moves forward four characters. If a command may be given a repeat count then the text [n] is given at the end of its description.
The following control characters are accepted:
| ^A | Move to the beginning of the line |
| ^B or left-arrow | Move left (backwards) [n] |
| ^D | Delete character [n] |
| ^E | Move to end of line |
| ^F or right-arrow | Move right (forwards) [n] |
| ^G | Ring the bell |
| ^H | Delete character before cursor (backspace key) [n] |
| ^J | Done with line (return key) |
| ^K | Kill to end of line (or column [n]) |
| ^L | Redisplay line |
| ^M | Done with line (alternate return key) |
| ^N or up-arrow | Get next line from history [n] |
| ^P or down-arrow | Get previous line from history [n] |
| ^R | Search backward (forward if [n]) through history for text; prefixing the string with a caret (^) forces it to match only at the beginning of a history line |
| ^T | Transpose characters |
| ^V | Insert next character, even if it is an edit command |
| ^W | Wipe to the mark |
| ^X^X | Exchange current location and mark |
| ^Y | Yank back last killed text |
| ^? | Delete character before cursor (delete key) [n] |
When typing in any input box in the graphical interface, the input can be edited with the following control characters. This section is taken from the XForms manual:
| delete previous char | Delete |
| delete next char | Ctrl-D |
| delete previous word | Meta-Delete, Ctrl-W |
| delete next word | Meta-d |
| delete to end of line | Ctrl-K |
| backspace | Ctrl-H |
| to beginning of line | Ctrl-A, Shift-Left-arrow |
| to end of line | Ctrl-E, Shift-Right-arrow |
| char backward | Ctrl-B, Left-arrow |
| char forward | Ctrl-F, Right-arrow |
| next line | ^N Ctrl-N, Down-arrow |
| previous line | Ctrl-P, Up-arrow |
| next page | PageDown |
| previous page | PageUp |
| word backward | Meta-b |
| word forward | Meta-f |
| beginning of field | Meta-Home, Shift-Up-arrow |
| end of field | Meta-End, Shift-Down-arrow |
| clear input field | Ctrl-U |
| paste | Ctrl-Y |
You can use the mouse or the right and left arrow keys to position the cursor within the text. Double clicking on a word in the text will select that word; triple clicking will select all the text. Typed characters are inserted at the cursor, or replace the selected text.
[36] In text mode, ppm2oof creates an invisible dummy graphics window, graphics 0, which can do everything that a regular graphics drawer can do, except draw and receive mouse clicks. All graphics commands in log files can be processed by the text parser if they begin with graphics 0, and don't begin with graphics 0 mouse.
