Code Structure and I/O

Files for Data Input

The Goma file I/O structure is diagrammed in Figure 2. Input to the program is divided into six categories: (1) command-line options, (2) problem description file, (3) material files, (4) ASCII continuation/restart file, (5) EXODUS II database file, and (6) sundry material property or boundary condition table lookup files. Goma is basically set up to run in batch mode, i.e., no input is required on the command line or after the run command is issued. There are, however, several command-line switches which can be used to redirect I/O, control the level of I/O, and activate debugging options.

I/O structure for Goma. Dashed lines indicate that the files or commands are not required.

The problem-description file is by default called “input” but can be renamed with the -i switch on the command line. A version of this file is also output as an “echo” file, viz. a prefix “echo” prepended to the input file name. The echo file is used to verify input into goma, as it clearly states all default settings for the input file and material files. . The input file itself contains the general description of the problem and directions to Goma on how to solve it (see Chapter 4). The file is split into thirteen sections: (1) File Specifications (Section 4.1) which directs I/O, (2) General Specifications (Section 4.2), (3) Time Integration Specifications (Section 4.3), (4) Continuation Specifications (Section 4.4), (5) Hunting Specifications (Section 4.5), (6) Augmenting Condition Specification (Section 4.6), (7) Solver Specifications (Section 4.7), (8) Eigensolver Specifications (Section 4.8), (9) Geometry Specification (Section 4.9), (10) Boundary Condition Specifications (Section 4.10), (11) Rotation Specifications (Section 4.11), (12) Problem Description (Section 4.12), and (13) Post Processing Specifications (Section 4.13); this latter section includes breakouts for fluxes and data (Section 4.14), particle traces (Section 4.15) and for volume-based integrals. The file format is described in detail in Chapter 4. Incidentally, the structure of the data input routines is divided roughly along the same lines as the input data file itself.

The material description files (using the nomenclature “[material name].mat”) contain all material property data and material property model and constitutive model specifications. The names of these files are specified in the problem description file. The format of these files and the available options are described in Chapter 5. Note that these files are also reproduced as output as “echo” files, with all default settings specified.

The ASCII continuation/restart files (may have any name) contain an ASCII list of the solution vector (values of field variables at nodes), which can be used as an initial guess for successive runs of Goma. The names of these files are specified in the problem description file, but may be changed with the -c (for input) or -s (for output) command-line options. These restart files are “recyclable”, in the sense that output from one Goma simulation may be used as input to another Goma simulation under certain restrictions.

The EXODUS II database files (may have any name but generally end in “.exoII”) contain a description of the finite-element structure for the current problem. All EXODUS II files contain a definition of the mesh, material blocks, and boundary sets. In the case of input EXODUS II files created from mesh generator output, this is the sole content of the file. Output EXODUS II database files contain a clone of the input EXODUS II mesh information and also contains the nodal values of all field variables in the solution. The names of these files are specified in the problem description file, but may be changed with the -ix (for input) or -ox (for output) command-line options. The only EXODUS II file required when running Goma is the one containing the current problem mesh. All others are either output for postprocessing or used to supply auxiliary external fields (e.g. magnetic fields).

Command-Line Arguments

Goma can be run using only the input files (all four listed above) to describe the problem and to direct the input and output; in this case Goma is run using the command “goma” without any arguments. However, command-line arguments offer additional flexibility for redirecting input or output and for adjusting common run-time parameters. The general command line for running Goma is:

$ goma [-nd] [-se fn] [-so fn] [-i fn] [-c fn] [-s fn] [-ix fn] [-ox fn] [-d int]
       [-n int] [-r dbl] [-a args] [-restart fn] [-h] [-ts dbl] [-te dbl] [-cb dbl]
       [-ce dbl] [-cd dbl] [-cn int] [-cmin dbl] [-cmax dbl] [-cm int] [-ct int] [-c_bc int]
       [-c_df int] [-c_mn int] [-c_mp int] [-bc_list] [-v]

Here fn denotes “file name”, int denotes “integer”, dbl denotes “float or double” and args denotes multiple sub-options or file names. The input line is parsed into options, which are preceded by a single hyphen (-) and arguments, which normally are fn, int, or dbl not preceded by a hyphen. The default, if no options are specified, is the input option (e.g. “goma input.alt” is the same as “goma -i input.alt”). The following is a list of the command-line options and their descriptions (two ways are shown to specify each option, an abbreviated and a verbose form).

-a args, -aprepro args

Preprocess input files through the APREPRO preprocessor [with args as arguments to APREPRO] before reading into Goma. With this option, Goma performs a UNIX system() call to run APREPRO which will preprocess the input file and the material data files. The APREPRO input file is preprocessed from “input” or the filenamespecified by the -input option and written to “tmp.input”. Likewise, the material data files are preprocessed from “[material name].mat” to “tmp.[material name].mat”. After the “-a” on the command line, options for APREPRO are preceded by two hyphens (–). For example, the command line “goma -i input.pre -a CONSTANT1=0.2 –vd” will preprocess “input.pre” and the material data files specified in input.pre using APREPRO, and will pass the argument -vd (which prints version number and values of all variables to the screen) and CONSTANT1=0.2 (which sets the variable CONSTANT1 equal to 0.2 for preprocessing) to APREPRO; the preprocessed files will be “tmp.input” and “tmp.[material name].*mat*”.)

-c fn, -contin fn Change the name of the ASCII continuation/restart input

file (specified in Problem-Description File) to fn, (e.g. “goma -c old.soln.dat” uses the file “old.soln.dat” as the ASCII input file). Note that this option has no effect if the initial guess is not read from the ASCII file, i.e. unless “Initial Guess = read” is specified in the input file.

-d int, -debug int Change the debug flag to int. This option is convenient

when debugging and the user wants to see more output from Goma. (e.g. “goma - d -2” will run Goma with the Debug_Flag set to -2). Higher values generally produce more output.

-h, -help

Prints a helpful message with brief descriptions of these command line options.

-i fn, -input fn Redirect Goma to read the problem description file from

fn. The normal default option is to read from a file named “input”.

-ix fn, -inexoII fn Redirect Goma to read the input EXODUS II database

file (often called “in.exoII”) from fn.

-kway

Use builtin METIS KWAY decomposition

-rcb

Use builtin METIS recurisve bisection decomposition

-e, -external_decomp

Use external decomposition (such as through SEACAS decomp, or already decomposed files)

-n int

Change the maximum number of Newton iterations to int. This is especially convenient for setting the number of iterations to zero so that Goma just runs the post-processor on the set of input data.

-nd, -nodisplay

Do not display the run-time information on the screen. With this option, Goma sends the stdout and stderr output to temporary files that are removed at the end of the run. This command takes no arguments.

-ox fn, -outexoII fn Redirect Goma to write the output EXODUS II file

(often called “out.exoII”) to fn.

-r dbl, relax dbl Change the value of the Newton relaxation parameter

to dbl. This is convenient if a few Newton steps with relaxation are desired before using full Newton. (e.g. “goma -r 0.1” will use Newton’s method with updates one-tenth of the normal value.

-s fn, -soln fn Redirect Goma to write the output ASCII file

(normally called “soln.dat”) to fn.

-se fn, -stderr fn Redirect the standard error from Goma to fn. This

output is comprised of more urgent diagnostic error and timing messages.

-so fn, -stdout fn Redirect the standard output from Goma to fn.

This output is comprised of less urgent informational messages.

-ts dbl

Start time of simulation.

-te dbl

End time of simulation

-cb dbl

Continuation: Start value (see Gates et al., SAND2000-2465)

-ce dbl

Continuation: Final value (see Gates et al., SAND2000-2465)

-cd dbl

Continuation: Path step, ds (see Gates et al., SAND2000-2465)

-cn dbl

Continuation: Max number of path steps (see Gates et al., 2000)

-cm int

Continuation: Method (see Gates et al., 2000)

-ct int

Continuation: Type (see Gates et al., 2000)

-c_bc int

Continuation: Boundary condition ID (see Gates et al., 2000)

-c_df int

Continuation: BC Data Float ID (see Gates et al., 2000)

-c_mn int

Continuation: Material ID (see Gates et al., 2000)

-c_mp int

Continuation: Method property ID (see Gates et al, 2000)

-bc_list

Continuation: Method property ID (see Gates et al, 2000)

-v -version

Output goma version

-petsc string

Use petsc options in quoted string see Solution Algorithm card for more information

Note

To get the most up-to-date list, simple issue the* “goma -h” command at the command line. Also note that the continuation input parameters are explained in the Advanced Capabilities Manual (Gates et al. 2000 or newer version).

The primary purpose of the command-line options is to allow the user an easy way to redirect the input and output of Goma or to quickly change problem specifications. Most of the options are overrides of information in the problem description file, so in some cases it may be easier to edit the problem description file than to use command-line arguments.