Preprocessing with ScriptIt.

1. Introduction to ScriptIt
2. Commands for Main Interpreter Loop
3. Commands for Geometry Definition
4. Commands for Flow Definition
5. Commands for Simulation Control
6. Sample Script

Introduction to ScriptIt

ScriptIt is intended to make the building and maintaining of a simulation case relatively easy by generating the Input Parameter File and the Bezier Boundary File. These files are plain text files but much of their input data is in reasonably cryptic format. The particular format allows the main program mb_cns.c could be kept fairly simple but setting up and modifying the input files is a pain.

There are now two versions of ScriptIt: the older C program which is invoked as the binary executable scriptit.exe and the newer Tcl program scriptit.tcl. The Tcl program has some significant advantages, such as the full Tcl programming language being available from within your set-up file. It is also the program upon which development will continue. The C program will continue to be be available to run (old-style) scripts when a Tcl interpreter is unavailable.

ScriptIt(C) accepts input from the standard input stream and writes some messages to the standard output stream. You may type commands directly or you may redirect input from a text file. I recommend that you use an editor to build your script file in stages and then use redirection to input your commands and catch the console output from ScriptIt.

   % scriptit.exe < sample.sit > sample.log

ScriptIt(Tcl) can be run as a command with a set of command-line arguments to modify its behaviour.

Usage: 
       scriptit.tcl ?-f sit-file? ?-tcl-comments? ?-help? ?-debug? ?-do-mpost? ?> log-file?
Where the command-line options are:
       -f sit-file : take further input from sit-file
       -tcl-comments : use Tcl-style comments rather than the
                       old scriptit-style comments.
       -debug        : prints debugging information as we go.
       -do-mpost     : write the Metapost file as well as .p and .bez files.
       -help : prints the usage message

Commands and their arguments are space-delimited and comments are indicated by a # at the beginning of the comment. Comments may occupy a whole line or the trailing part of a command line. In the Tcl-version of scriptit, you may use the Tcl comment conventions to make use of trailing comments. In this convention, you should terminate the command with a semicolon before using a # to start the comment. Unless you specify otherwise, Scriptit(Tcl) deals with old-style comments in a preprocessing phase where it strips all comments from the input file and writes the resulting text to an intermediate file before further processing. ScriptIt should not be case sensitive; most strings are converted to uppercase within the program.

The old (C) program begins in the main interpreter loop and may switch to a secondary interpreter loop depending on the command. The secondary interpreters include one for geometry generation and another for input-parameter specification. The newer Tcl program defines each of the commands as a Tcl procedure and the one-and-only interpreter that reads your input file is actually the Tcl interpreter.

Construction of a geometry begins by jumping to the geometry interpreter loop (with the BEGIN_GEOMETRY command) and doing the following. The Tcl program uses the BEGIN_GEOMETRY command just to change the help context.

1. Add nodes (points) to the database.
2. Build lines, arcs and Bezier curves through the nodes.
3. Put the curve segments into polylines (even if there is only one segment).
4. Return to the main interpreter loop with END_GEOMETRY.

1. Specify the set of flow states that will be used for initial and boundary conditions.
2. Attach the boundary conditions to the relevant polylines using BOUNDARY_SPEC. Note that (by default) each boundary is a SLIP_WALL unless connected to an adjoining block or explicitly specified as another type of condition. Each of the four boundaries of a block is later copied from the specified polyline data. Also at this point, define how the boundary will be discretised via the DISCRETISE command.
3. Define each block as a set of 4 polylines (one each for the North, East, South and West boundaries). For multiple block geometries, neighbours need to be defined.
4. Set the other flow-specific parameters as required and return to the main interpreter with END_FLOW.

After setting up all of the parameters, the relevant information should now be written to the Bezier and Input Parameter files with the command BUILD. That's it. Have a look at the sample script sod2.sit below. For further information on the meanings of the parameter values, see the section on the use of MB_CNS.

Presently, there is little error checking. If you make a mistake, ScriptIt won't often care and the results will be unpredictable. However, this situation is improving...

Commands for Main Interpreter Loop.

BEGIN_GEOMETRY

Enter the Geometry Interpreter loop.

BEGIN_FLOW

Enter the Flow-Definition Interpreter loop.

BEGIN_CONTROL

Enter the Control Interpreter loop.

PARAM_FILE param_file_name

Change the Input Parameter filename to that given. Default is "temp.p".

BEZIER_FILE bezier_file_name

Change the Bezier filename to that given. Default is "temp.bez".

BUILD

Go ahead and build the Bezier file and the Input Parameter files with the currently-known data. Parameters that have not been specified will have default values.

EXIT

Causes ScriptIt to finish. Use QUIT instead.

QUIT

Causes ScriptIt to finish. Preferred over EXIT.

HELP

Provide some hints.

INTERACTIVE

Puts scriptit into the interactive processing mode. Errors in a command will result in the command not being completed. The command may then be re-entered.

BATCH

Puts scriptit into the batch processing mode. An error in a command will result in termination of the interpreter. This is the default processing mode for the C program as the input will usually be coming from a file of prepared commands.

MPOST_FILE mpost_file_name

Change the MetaPost output file to mpost_file_name. Default is "temp.mpost". After writing the parameter and Bezier files, a separate file containing Metapost commands describing the geometry is also written. This file may be further processed to obtain a postscript representation of the constructed geometry. For example:
mpost temp.mpost
will produce a postscript file temp.1.

MPOST_SCALES xscale yscale

Remember that mb_cns lengths are in metres and that images in reports are typically limited to 16cm width. Although postscript can handle all scales, it may be convenient to alter the size of the MetaPost figure to make the text easy to read. Coordinates are multiplied by these scales when written to the MetaPost file.

MPOST_XAXIS x0 x1 xtic y

Add an x-axis (length scale) to the Metapost drawing. It may be convenient to locate the axis scale away from y=0 so that other lines and labels are not cluttered.

MPOST_YAXIS y0 y1 ytic x

Add an x-axis (length scale) to the Metapost drawing.

MPOST subcommand args...

An alternative form for Metapost-related commands.

Commands for Geometry Definition.

NODE label x y

Set the label and coordinates for a node.

LIST_NODES

List the labels and coordinates of all the entered nodes. You will need to press ENTER to continue.

LINE label nodeA nodeB

Define a line from nodeA to nodeB. Use labels to specify the nodes. Upon definition the segment is described as a Bezier segment witht the intermediate nodes being 1/3 and 2/3 along the straight line between the end points.

ARC label nodeA nodeB centre_node

Define a circular arc from nodeA to nodeB with its centre at centre_node. Use labels to specify the nodes. Note that the included angle is assumed to be less than 180 degrees. Upon definition, the arc is defined as a third-order Bezier segment as per the description in workbook 2/97 page 26.

BEZIER label node0 node1 node2 node3

Define a third-order Bezier curve segment from node0 to node3. Use labels to specify the nodes. The Bezier curve is defined as
p(t) = (1-t)**3 p0 + 3 (1-t)**2 t p1 + 3 (1-t) t**2 p2 + t**3 p3;
This third-order Bezier polynomial is the basic form of curve segment implemented in the package; all boundary curves are constructed from sets of these segments.

SPLINE label m node0 node1 ... nodem

Define a Bezier spline (with m segments) that interpolates nodes 0,1, ... m. Use labels to specify the nodes. When building polylines (see below), the spline is considered to be a single curve segment.

LIST_CURVES

List the set of defined curve segments.

POLYLINE label ncurve +/- c_0 +/- c_1 ... +/- c_nc-1

Build a polyline from a series of curve segments. ncurve is the number of curves to be included in the polyline. For each curve, the preceding plus (or minus) indicates if the curve is added in the forward (or reverse) direction.

LIST_POLYLINES

List the set of defined polylines.

HELP

Provide some hints.

END_GEOMETRY or END

Return to the previous interpreter loop (main).

Commands for Flow Definition.

GAS_TYPE gas_index

Select the gas model from the list given in mb_cns.h. The selection can be given as either the mnemonic or integer. For example "GAS_TYPE perf_air_14" is equivalent to "GAS_TYPE 0".

GAS_STATE label p u v T f[0] ... f[nsp-1]

Define a flow state that can be used for initial conditions (within a block) or for boundary conditions (attached to a polyline).
p: pressure in Pa
u: x-velocity in m/s
v: y-velocity in m/s
T: temperature in degrees K.
f[0] ... f[nsp-1] species mass fractions.
For SUBSONIC_IN boundaries, the pressure and temperatures are stagnation values, while the velocities (as given on this line) are ignored.

LIST_GAS_STATES

List the gas states.

BOUNDARY_SPEC polyline_label BC_type argument3

Attaches a boundary condition type (SPECIAL, COMMON, SUP_IN, SUP_OUT, SLIP_WALL, ADIABATIC, FIXED_T, SUBSONIC_IN, SUBSONIC_OUT, TRANSIENT_UNI, TRANSIENT_PROF, STATIC_PROF) to the specified boundary (polyline).
For BC_type=SUP_IN or SUBSONIC_IN, argument3 specifies which gas_state to use as the inflow condition.
For BC_type=FIXED_T, argument3 specifies the (fixed) wall temperature.
For some case identifier values, the SPECIAL boundary condition can be used to activate specific, hard-coded boundary conditions such as Mirel's boundary-layer model in a shock tube.
The STATIC_PROF looks for the flow data in a file "profile.dat". Check the function init_profile_data() for details of the file format.
The TRANSIENT_UNI condition looks for flow data in the file "transient_uniform.dat". Look in the function init_transient_free_stream() for format details.
By default, each boundary is a SLIP_WALL unless connected to an adjoining block (using CONNECT_BLOCKS) or explicitly specified as another type of condition.

DISCRETISE polyline_label n end1 end2 beta

Indicate how the cells will be distributed along polyline_label.
n is the number of cells. A default value of n=10 was set when the polyline was created.
end1=1 to get clustering at left-hand end (default=0).
end2=1 to get clustering at right-hand end (default=0).
beta is Roberts' stretching parameter. Values greater than but close to 1.0 provide strong clustering. Values much larger than 1.0 provide weak clustering.

BLOCK label +/- pl_North +/- pl_East +/- pl_South +/- pl_West

Build a block by defining which polylines form the North, East, South and West boundaries (in that order). The positive direction for the North and South boundaries is from West-to-East while the positive direction for the West and East boundaries is from South-to-North. Select the sign (+/-) before each polyline label to indicate the order in which the Bezier segment nodes will be copied to the block data structure. A plus sign will preserve the order in which they were stored in the polyline while a minus sign will reverse the order. This ability to reverse the node order may be useful in situations where a polyline is common to more than one block.
NOTE: Blocks should be defined after all of the attributes as set for the polylines. This is because the boundary attributes are simply copied from the specified polylines; there is no update if the attributes of a particular polyline are subsequently altered.

CONNECT_BLOCKS block_label_1 bndy_1 block_label_2 bndy_2

Make a connection between the specified blocks and boundaries. The block_labels are the string labels of blocks that have already been defined. The bndy_1 and bndy_2 are selected from "North", "East", "South" and "West".

GRID_TYPE block_label grid_type

Set the grid_type for the specified block. Options include:
COONS Coons patch (the default)
TFI Transfinite Interpolation (same as Coons patch)
AO Area-Orthogonality grid generator of Knupp (1992)
RULED Ruled-grid, in which all grid lines are straight.

FILL_BLOCK block_label gas_state_label

Specify that the block is to be filled with uniform conditions as specified by gas_state_label

FILL_VARIABLE block_label gas_state_label_NE gs_label_SE gs_label_SW gs_label_NW

Specify that the block is to be filled with variable conditions as specified by the four corner states. These work clockwise around the block, starting with the North-East corner. The code implements a bi-linear interpolation in logical space (i.e. based on grid index, not x,y-coordinates). The same gas_state label may be specified multiple times.

FILL_WITH_PROFILE block_label

Specify that the block is to be filled from west-to-east with conditions read from the static profile file "profile.dat".

END_FLOW or END

Return to the previous interpreter loop (main).

Commands for Simulation Control.

TITLE title_string

Sets the title to title_string.

CASE_ID integer_case_id

Sets the case_id variable for activating special code within MB_CNS. Defaults to 0 which indicates that there is no special code within MB_CNS for this case. Look in mb_cns.h. to get a list of the available special cases. Set to 0 by default.

VISCOUS

Turn on the viscous terms.

INVISCID

Turn off the viscous terms (default).

VISCOUS_DELAY vtdelay

Suppress the viscous effects until this time.

TURBULENT block_label

Activate the turbulence model for the specified block. The model, which is presently the Baldwin-Lomax eddy-viscosity model, assumes that the boundary layer is attached to the North boundary.

AXISYMMETRIC

Turn on the axisymmetric terms.

PLANAR

Turn off the axisymmetric terms (default).

HIGH_ORDER

Use high-order reconstruction and predictor-corrector time stepping (default).

LOW_ORDER

Use low-order spatial reconstruction and Euler time-stepping.

LOW_ORDER_X

Use low-order spatial reconstruction.

LOW_ORDER_T

Use low-order (Euler) time-stepping.

FLUX_CALC option

Select the flux calculator from RIEMANN, AUSM, EFM, AUSMDV and ADAPTIVE.
AUSMDV is the default.

TIME_STEP magnitude

Set dt_global to the specified magnitude. Set to 1.0e-6 by default.

CFL magnitude

Set cfl_target to the specified magnitude. Set to 0.5 by default.

DT_PLOT magnitude

Set dt_plot to the specified magnitude. Set to 1.0 by default.

DT_HISTORY magnitude

Set dt_his to the specified magnitude. Set to 1.0 by default.

MAX_TIME magnitude

Set max_time to the specified magnitude. Set to 1.0e-3 by default.

MAX_STEP integer magnitude

Set max_step. Default value is 100.

HISTORY_CELL block_label ix iy

Add a history cell to the specified block. The valid ranges for the indices are 1<=ix<=nnx and 1<=iy<=nny.

LIST_H_CELLS

List all of the history cells.

END_CONTROL or END

Return to the previous interpreter loop (main).

Sample Script

# sod2.sit
# This will be like the Sod shock tube case.

# Set up two rectangles in the (x,y)-plane.
BEGIN_GEOMETRY
   NODE a 0.5 0.0
   NODE b 0.5 0.1
   NODE c 0.0 0.1
   NODE d 0.0 0.0
   NODE e 1.0 0.0
   NODE f 1.0 0.1

   LINE ab a b
   LINE bc b c
   LINE cd c d
   LINE da d a
   LINE ae a e
   LINE ef e f
   LINE bf b f

   # Define the boundaries
   POLYLINE north0 1 - bc
   POLYLINE east0  1 + ab
   POLYLINE south0 1 + da
   POLYLINE west0  1 - cd
   POLYLINE south1 1 + ae
   POLYLINE east1  1 + ef
   POLYLINE north1 1 + bf
END_GEOMETRY

BEGIN_FLOW
   # Gas and flow properties
   GAS_TYPE perf_he_air
   GAS_STATE high_p_air  1.0e5  0.0 0.0 348.4 1.0
   GAS_STATE low_p_air   1.0e4  0.0 0.0 278.7 1.0

   # Set the boundary discretisation before building the blocks
   DISCRETISE north0 50 0 0 0.0
   DISCRETISE east0   2 0 0 0.0
   DISCRETISE south0 50 0 0 0.0
   DISCRETISE west0   2 0 0 0.0
   DISCRETISE north1 50 0 0 0.0
   DISCRETISE south1 50 0 0 0.0
   DISCRETISE east1   2 0 0 0.0

   # Define two blocks with a common boundary
   BLOCK left_block  + north0 + east0 + south0 + west0
   BLOCK right_block + north1 + east1 + south1 + east0
   CONNECT_BLOCKS left_block east right_block west

   # Assign the initial gas states
   FILL_BLOCK left_block  high_p
   FILL_BLOCK right_block low_p
END_FLOW

BEGIN_CONTROL
   TITLE Sod shock tube with helium driving air.
   CASE_ID 42

   FLUX_CALC ausmdv
   MAX_TIME  0.4e-3
   MAX_STEP  300
   TIME_STEP 1.0e-6

   DT_HISTORY 1.0e-5
   HISTORY_CELL right_block 20 1
   HISTORY_CELL right_block 40 1
END_CONTROL

# Name the output files and build them.
BEZIER_FILE sod2.bez
PARAM_FILE sod2.p
BUILD

EXIT