Manual for Scripts

Steven M. Nash, Stuart E. Rogers

Introduction
Philosophy
Structure
Description of the Tools
Method of Operation
To Customize for Your Problem
Input Variables
Misc. Info

Introduction

This document describes how to use the various scripts and tools included in Chimera Grid Tools to complete a CFD analysis. These scripts are meant to be used in combination with the tools within the Chimera Grid Tools package. It will be explained how these scripts can be used to automate the CFD process. An example of their use is provided in the chimera/examples/scripts directory.

Philosophy

In a typical CFD analysis, many different tools are used to proceed through the analysis. Most of these tools require similar information about the grid system regarding where solid walls exist, boundary condition information, and groupings of surfaces to form families. The script system described here requires this information upon completion of the surface grids, and then ensures that this information will be consistantly passed 'downstream' in a standardized database. Thus, all updates to boundary conditions and families need only be altered in one location, and will be automatically be updated where required. Another problem encountered when analyzing very complex problems is the need for modularity throughout the system to allow for easy partitioning of the problem for debugging and build-up purposes. This problem is approached here by using a master configuration file (default=config.tcl) that defines a list of the components to include in a particular analysis. Components can be easily added or subtracted from this list, and the user can be assured that the influences of those changes will be reflected properly. In order to achieve this functionality, the following assumptions have been made:

The user can enter the script system from two starting points.
(1) For surface grids with complex topologies, most grids need to be custom made and are difficult to automate their creation. In such cases, the user provides a script or program that will generate the surface grid and OVERFLOW input file for each grid. Work is being conducted to try and automate this step, but in the meantime there are tools available to assist the user with this step (e.g. see the scripts example).
(2) A complex configuration may also be decomposed into a larger number of surface grids with simple topologies (e.g. free floating or constant plane at the boundaries). Such systems may be created from a user interface such as OVERGRID or from a single run of a hyperbolic/TFI grid generator such as SURGRD. In these cases, the user enters the script system with a surface grid file in PLOT3D multiple grid format. The PreVol script is run which automatically determines the surface topology (assuming all solid walls are located at L=1) and generates the OVERFLOW input files, config.tcl and inputs.tcl files. The user has the option to further edit these files if special inputs are needed beyond the defaults.
All grids, and inputs provided by the user conform to the naming convention adopted by this system. See the Naming Convention
The user must have Chimera Grid Tools compiled and installed. You will not need OVERGRID (except if you want to use it to create the scripts for surface grid generation), but you will need to have the Tcl/Tk shells installed (which are also necessary for installing OVERGRID).
Set the environment variable SCRIPTLIB to point at the chimera/scriptlib directory in order to have seamless access to the library of Tcl routines included with CGT. The easiest way to do this is to add the following to your .cshrc file if you are using C-Shell:
setenv SCRIPTLIB $HOME/chimera/scriptlib
where the above path matches the location of your chimera directory. Use "echo $SCRIPTLIB" to test for the correct assignment. This is necessary for seamless access to the library of routines in this directory.
Set your path to include the chimera/bin directory. Again, using C-Shell, this might look like:
set path = ( $path $HOME/chimera/bin )
in your .cshrc file. Use "which BuildSurf" to verify your path is correct. This allows access to the executable scripts in this directory.

Structure

A master configuration file resides in the main grid directory, the default name for this file is config.tcl. This file defines which components will be included in the current configuration (and ultimately the order of the grids in composite grid files). Through control of the contents of this file, the user can easily add or remove components. A master input file, called inputs.tcl, must resid in the same directory as the configuration file. The inputs.tcl file contains some global parameters, default values for some input parameters, and any grid-specific input parameters used to override the default values. These inputs are those primarily used to generate volume grids for the given surface grids, and for input parameters used to generate box grids and wake grids.

For starting option (1), a number of subdirectories can exist where each subdirectory should contain a Makefile that defines the process for creating one or more surface grid files, and an accompanying boundary condition file. This process maybe nothing more than reformatting an input grid, or it might be a complex script system which generates the surface grids using the tools found in the Chimera Grid Tools package. For each grid, a rootname is used to identify the grid, and filenames for that grid consist of the rootname followed by a suffix that defines the contents of the file. See the Naming Convention for definitions of the file suffixes. More than one component or grid can reside in any subdirectory, as long as there is a rule in the Makefile for creating all the necessary surface grids and boundary condition files.

For starting option (2), just one subdirectory is needed which should contain the surface grid file. Since this option usually involves a larger number of grids that are similar in topology, the root names are automatically generated by the PreVol script. Note that PreVol assumes that all solid walls are located at L=1.

The boundary condition file is merely the set of NAMELISTS for an OVERFLOW input file that are associated with one grid. Each grid must have its own boundary condition input file; these input files are identified with the file suffix of .ovfi. In addition to the standard OVERFLOW NAMELISTs for a grid, the .ovfi file should contain a comment line which defines the family name for each boundary surface that covers a wall, if the particular grid contains a wall. For starting option (1), the user-provided surface grid creation scripts should generate the .ovfi files. For starting option (2), these files are automatically created by PreVol.

Naming Convention

The naming convention adopted for these scripts is as follows. The config.tcl directive file defines a list of the directory path and rootname (name of the grid without the suffix) for each individual grid to be included in a configuration.

The following suffix convention is then used for each grid:


          .fmt    initial surface grid in a formatted file type
          .def    surface grid definition from CAD or other data
          .srf    surface grid in final form
          .vol    volume grid
          .hypi   HYPGEN input file
          .ovfi   OVERFLOW input file
          .legi   LEGRID input file
          .pwk    surface grid with a wake cut added on
          .com    PLOT3D command file
          .tcl    Tcl language scripts or input files
          .mvlog  Log file from makevol (for diagnostics)
          .bvinp  history file to record parameter settings.  Used
                  when re-running BuildVol to see if a grid needs updating.

The scripts in chimera/bin are named such that all scripts beginning with a capital letter are meant for use in this configuraton building procedure, whereas there are other miscellaneous scripts (e.g. makevol, intersect, etc.) that will probably not be accessed directly by the user at this level.

Description of the Tools

BuildMixsuri creates the MIXSUR/OVERINT input file for the composite system defined by config.tcl. Reads the OVERFLOW input files for each grid, using their Family definitions for segregating surfaces. It accepts some command-line inputs to specify reference information.
BuildOveri creates the OVERFLOW input file by concatenating all the component OVERFLOW input files.
BuildPegi creates the PEGSUS version 4.1 input template for the composite system defined by config.tcl. This file contains the $MESH definitions with a guess at the link lists by using bounding box information, and also includes the outer-boundary definitions by reading the OVERFLOW input files. The user still is required to provide the hole cutting definitions.
BuildPeg5i creates the PEGASUS version 5.0 input file for the composite system defined by config.tcl. This file should be complete for the PEGASUS 5.0 program. Modifications by the user may be required for fine-tuning the inputs for the automated hole-cutting procedures in PEGASUS 5.0.
BuildProgrdi creates the PROGRD input file using the OVERFLOW input files, and uses their Family definitions for segregating surfaces. This program projects grids that overlap on a solid wall, and eliminates ORPHANS encountered with PEGSUS 4.1 hole cuts in these regions.
BuildIngrid creates the PEGSUS/PEGASUS INGRID input file from the volume grids defined in config.tcl. Used by RunPeg/RunPeg5.
BuildPlot creates a PLOT3D command file to visualize the composite grid system defined by config.tcl to show various things like Family groupings, boundary condition assignments, etc.
BuildSurf executes the Makefile for all component grids to update the surface grid and OVERFLOW input file for each grid defined in config.tcl.
BuildVol creates the volume grid for all component grids defined in config.tcl by either: running makevol with the parameters defined in inputs.tcl, or running BOXGR to create a cartesian box grid around the grids defined in inputs.tcl.
makevol creates a single volume grid given the surface grid and OVERFLOW input file. Accepts various command-line flags to control the grid generator used (HYPGEN or LEGRID); the inputs controlling how the volume grid generator runs; and if and how smoothing is performed by SMOGRD.
PreVol creates OVERFLOW input files, config.tcl and inputs.tcl automatically from a given PLOT3D multiple surface grid file.
RunPeg runs PEGSUS 4.1 using input file(s) provided by the user (see BuildPegi). See the output from RunPeg -help for the options available. This script will automatically call BuildIngrid,progrd, and pegsus41.
RunPeg5 is similar to RunPeg, except it runs PEGASUS version 5.0.
ScriptClean will clean up all the directories defined in config.tcl by removing output files for each rootname in config.tcl, using the suffix convention defined above (see Naming Convention.

Method of Operation

Once everything is set up, the following tools can be used to alleviate a lot of the burden of getting to the composite grid with a matching OVERFLOW input file. The following steps can be performed:

BuildSurf or PreVol
BuildVol
BuildProgrdi
BuildMixsuri
BuildOveri
BuildPegi (for PEGSUS 4.1)

Once a PEGSUS/PEGASUS input file is complete the user can start PEGSUS/PEGASUS via RunPeg/RunPeg5. See the output from 'RunPeg -help' for the options available for using this script. After successful completion, there will exist a grid.in, XINTOUT, and OVERFLOW input files. The user may want to first run MIXSUR (using the above-mentioned mixsur.i), and then can start the OVERFLOW run. This is meant as just a brief overview of how these tools can be run, and how a user might best go about utilizing some of the tools in CGT.

To Customize for Your Problem

You will invariably want to adapt this information to the configuration you want to study. This could be accomplished as follows:

Set up a directory structure that best represents your configuration. There is no limitation regarding how many grids per directory.
Provide a script or program that can be executed in batch to create the surface grid and OVERFLOW input file for each grid. Create a Makefile in each directory that will update define the rules for creating the surface grids.
Create a config.tcl that defines the rootnames for each grid. The order of the rootnames will be used throughout the process whenever grids are combined into a multiple grid file (e.g. grid.in).
Create an inputs.tcl that defines the rules for volume grid generation via HYPGEN/LEGRID/BOXGR, and any phantom grid specifications. You can just use default rules, or if you need to override the default for specific grids, that can also be specified in the inputs.tcl file.
Run BuildSurf.
Use BuildVol, BuildProgrdi, BuildOveri, BuildPegi and RunPeg to proceed through the analysis.

Put the multiple surface grid file in a directory.
Run PreVol.
Use BuildVol, BuildProgrdi, BuildOveri, BuildPegi and RunPeg to proceed through the analysis.

Input Variables in inputs.tcl

The following is a list of the possible parameters which can be defined for individual grids in the inputs.tcl file. The following table lists each parameter and its description. In the inputs.tcl file, entries are to be entered either of the two forms:

set default(xxxx) "value1 [value2 ... valueN]"

set MESH(xxxx) "value1 [value2 ... valueN]"

The first form changes the default value of the parameter which will be used by all grids. The second form is used by substituting the word MESH with the root name of the individual grid for which the parameter is to be changed.

Parameter Description Default Value

set MESH(zreg) z Wall-spacing used in volume grid generation. 0.5

set MESH(izstrt ) i HYPGEN input variable izstr: selects stretching, 1 for exponential, 2 for hyperbolic 2

set MESH(npzreg ) n HYPGEN input variable npzreg: number of points in l-direction 49

set MESH(dz0 ) z HYPGEN input variable dz0: initial spacing 0.001

set MESH(dz1 ) z HYPGEN input variable dz1: final spacing 0.1

set MESH(ibcja ) i HYPGEN input variable ibcja: boundary condition for j=1 -1

set MESH(ibcjb ) i HYPGEN input variable ibcjb: boundary condition for j=jmax -1

set MESH(ibcka ) i HYPGEN input variable ibcka: boundary condition for k=1 -1

set MESH(ibckb) i HYPGEN input variable ibckb: boundary condition for k=kmax -1

set MESH(imeth ) i HYPGEN input variable imeth: selects dissipation method 2

set MESH(smu2 ) s HYPGEN input variable smu2: second-order dissipation coefficient 1.0

set MESH(itsvol) i HYPGEN input variable itsvol: number of times volumes are averaged 100

set MESH(timj ) tj HYPGEN input variable timj: Barth implicitness factor for j 0.0

set MESH(timk ) tk HYPGEN input variable timk: Barth implicitness factor for k 0.0

set MESH(iaxis ) i HYPGEN input variable iaxis: controls treatment of singular axis BC 1

set MESH(exaxis ) e HYPGEN input variable exaxis: controls treatment of singular axis BC 0.1

set MESH(volres) v HYPGEN input variable volres: controls treatment of singular axis BC 0.4

set MESH(nsub ) n HYPGEN input variable nsub: controls number of sub-steps used to march one step 1

set MESH(srmax ) s uses srmax as a maximum stretching ratio to determine the number of points required for NPZREG none

set MESH(legrid ) 1 Causes BuildVol to use LEGRID instead of HYPGEN to generate volume grid 0

set MESH(rey ) r LEGRID input variable rey: used to determine initial spacing none

set MESH(chord ) c LEGRID input variable chord: used to determine initial spacing 1.0

set MESH(xref) x LEGRID input variable xref: used to determine initial spacing 0.1

set MESH(yplus) y LEGRID input variable yplus: used to determine initial spacing 1.0

set MESH(smogrdargs ) ARGS Used to pass ARGS as command-line parameters to the program SMOGRD

set MESH(adddummy) "iadja iadjb iadka iadkb iadla iadlb" Specifies number of dummy grid planes to add to j=1, j=jmax, k=1, k=kmax, l=1, l=lmax faces before performing smoothing with SMOGRD; dummy planes are removed after smoothing 0 0 0 0 0 0

set MESH(hypinargs) ARGS ARGS is a string composed of flags to be passed to the HYPIN program. The following parameters are allowed: -zmax ZMAX (this is the only one that's required); -wallsp WALLSP; -z1 Z1; -z2 Z2; -dz2 DZ2; -srmax SRMAX; -zmax 0.5

set MESH(nosmogrd ) 1 Overrides the default behavior of running SMOGRD for regions which do not have wall boundary conditions at L=1 0

set MESH(smogrd ) 1 Runs SMOGRD to smooth and enlarge wall-spacing cells in regions which are detected to have no wall-type boundary conditions at the L=1 surface; this is the default behavior 1

set MESH(nobccheck) 1 Overrides the default of checking the OVERFLOW input file for info about running HYPGEN and/or SMOGRD. 0

set MESH(phantom) 1 Setting this to 1 designates this mesh as a phantom mesh, which is to be used only for hole-cutting in PEGSUS, and it will not appear in the final grid system 0

set MESH(box) "file1 file2 ..." Designates MESH as a box mesh, to be generated by the program BOXGR, and to be sized to surround the grids contained in the files file1, file2, etc none

set MESH(command) "command1 ; command2 ; ... " A series of shell commands which will be used by BuildVol to generate the volume grid for zone MESH, instead of using the the built-in makevol script none

set MESH(nomakevol) 1 Designates that BuildVol does not need to build the volume grid for MESH none

set MESH(link_list) "string1 [string2 ...]" A space-separated list of strings used to limit the LINK lists created by BuildPegi; the LINK list for MESH contains only other grids whose name contains one of the strings none

set MESH(XXX,fringe) num Used by BuildPegi to specify fringe levels for a mesh. Typically num should be 1 or 2. XXX can be hole, ob, jmin, jmax, kmin, kmax, lmin, lmax. This changes the fringe level specified in the PEGSUS input files for hole boundaries, outer boundaries, or for the outer boundaries at the six different faces of the mesh, respectively. 2

lappend priority(family_name_a) "zone1 zone2" Used by BuildMixsuri to specify priorities within the mixsur input file. This gives zone1 priority over zone2 within the family named family_name. none

Parameter	Description	Default Value
set MESH(zreg) z	Wall-spacing used in volume grid generation.	0.5
set MESH(izstrt ) i	HYPGEN input variable izstr: selects stretching, 1 for exponential, 2 for hyperbolic	2
set MESH(npzreg ) n	HYPGEN input variable npzreg: number of points in l-direction	49
set MESH(dz0 ) z	HYPGEN input variable dz0: initial spacing	0.001
set MESH(dz1 ) z	HYPGEN input variable dz1: final spacing	0.1
set MESH(ibcja ) i	HYPGEN input variable ibcja: boundary condition for j=1	-1
set MESH(ibcjb ) i	HYPGEN input variable ibcjb: boundary condition for j=jmax	-1
set MESH(ibcka ) i	HYPGEN input variable ibcka: boundary condition for k=1	-1
set MESH(ibckb) i	HYPGEN input variable ibckb: boundary condition for k=kmax	-1
set MESH(imeth ) i	HYPGEN input variable imeth: selects dissipation method	2
set MESH(smu2 ) s	HYPGEN input variable smu2: second-order dissipation coefficient	1.0
set MESH(itsvol) i	HYPGEN input variable itsvol: number of times volumes are averaged	100
set MESH(timj ) tj	HYPGEN input variable timj: Barth implicitness factor for j	0.0
set MESH(timk ) tk	HYPGEN input variable timk: Barth implicitness factor for k	0.0
set MESH(iaxis ) i	HYPGEN input variable iaxis: controls treatment of singular axis BC	1
set MESH(exaxis ) e	HYPGEN input variable exaxis: controls treatment of singular axis BC	0.1
set MESH(volres) v	HYPGEN input variable volres: controls treatment of singular axis BC	0.4
set MESH(nsub ) n	HYPGEN input variable nsub: controls number of sub-steps used to march one step	1
set MESH(srmax ) s	uses srmax as a maximum stretching ratio to determine the number of points required for NPZREG	none
set MESH(legrid ) 1	Causes BuildVol to use LEGRID instead of HYPGEN to generate volume grid	0
set MESH(rey ) r	LEGRID input variable rey: used to determine initial spacing	none
set MESH(chord ) c	LEGRID input variable chord: used to determine initial spacing	1.0
set MESH(xref) x	LEGRID input variable xref: used to determine initial spacing	0.1
set MESH(yplus) y	LEGRID input variable yplus: used to determine initial spacing	1.0
set MESH(smogrdargs ) ARGS	Used to pass ARGS as command-line parameters to the program SMOGRD
set MESH(adddummy) "iadja iadjb iadka iadkb iadla iadlb"	Specifies number of dummy grid planes to add to j=1, j=jmax, k=1, k=kmax, l=1, l=lmax faces before performing smoothing with SMOGRD; dummy planes are removed after smoothing	0 0 0 0 0 0
set MESH(hypinargs) ARGS	ARGS is a string composed of flags to be passed to the HYPIN program. The following parameters are allowed: -zmax ZMAX (this is the only one that's required); -wallsp WALLSP; -z1 Z1; -z2 Z2; -dz2 DZ2; -srmax SRMAX;	-zmax 0.5
set MESH(nosmogrd ) 1	Overrides the default behavior of running SMOGRD for regions which do not have wall boundary conditions at L=1	0
set MESH(smogrd ) 1	Runs SMOGRD to smooth and enlarge wall-spacing cells in regions which are detected to have no wall-type boundary conditions at the L=1 surface; this is the default behavior	1
set MESH(nobccheck) 1	Overrides the default of checking the OVERFLOW input file for info about running HYPGEN and/or SMOGRD.	0
set MESH(phantom) 1	Setting this to 1 designates this mesh as a phantom mesh, which is to be used only for hole-cutting in PEGSUS, and it will not appear in the final grid system	0
set MESH(box) "file1 file2 ..."	Designates MESH as a box mesh, to be generated by the program BOXGR, and to be sized to surround the grids contained in the files file1, file2, etc	none
set MESH(command) "command1 ; command2 ; ... "	A series of shell commands which will be used by BuildVol to generate the volume grid for zone MESH, instead of using the the built-in makevol script	none
set MESH(nomakevol) 1	Designates that BuildVol does not need to build the volume grid for MESH	none
set MESH(link_list) "string1 [string2 ...]"	A space-separated list of strings used to limit the LINK lists created by BuildPegi; the LINK list for MESH contains only other grids whose name contains one of the strings	none
set MESH(XXX,fringe) num	Used by BuildPegi to specify fringe levels for a mesh. Typically num should be 1 or 2. XXX can be hole, ob, jmin, jmax, kmin, kmax, lmin, lmax. This changes the fringe level specified in the PEGSUS input files for hole boundaries, outer boundaries, or for the outer boundaries at the six different faces of the mesh, respectively.	2
lappend priority(family_name_a) "zone1 zone2"	Used by BuildMixsuri to specify priorities within the mixsur input file. This gives zone1 priority over zone2 within the family named family_name.	none

Misc. Info

For debugging boundary conditions and family information, use the BuildPlot script. It can plot composite surfaces or volumes, using PLOT3D to assign color coding for visual debugging.
Cleaning can be accomplished with the ScriptClean script.
You can access further help for any of the scripts in chimera/bin by executing that script with the -help flag at the command line.

NASA Ames Research Center, Moffett Field CA 94035-1000, (650) 604-5000
URL: http://rotorcraft.arc.nasa.gov/
This Website Maintained By: Randall L. Peterson.
Responsible NASA Official: Dr. William Warmbrodt (Chief)

Privacy Statement
Ames Research Center Homepage
NASA Homepage

Last Modified: Monday, 07-Jan-2008 11:58:08 PST

Manual for Scripts

Steven M. Nash, Stuart E. Rogers

Contents