1.4. Conventions for Command Descriptions

The parts of an input file built into Sierra can be hard to distinguish from the user supplied parts. For example in Section 1.3, the user supplied only the name my_problem for the SIERRA scope and the name my_function for a function. This section presents the syntax used in this document to describe input files.

A note about continuation characters. Many individual command lines discussed in the text appear on several text lines. In the text of this document, the continuation symbols that are used to continue lines in an actual input file (\# and \$, Section 1.5.2) are not used for those instances where the description of the command line appears on several text lines. The description of command lines will indicate all the key words, delimiters, and values that constitute a complete command line. As an example, the DEFINE POINT command line (Section 2.1.7) is presented in the text as follows:

DEFINE POINT <string>point_name WITH COORDINATES
  <real>value_1 <real>value_2 <real>value_3

If the DEFINE POINT command line were used as a command line in an input file and spread over two input lines, it would appear, with actual values, as follows:

DEFINE POINT center WITH COORDINATES \#
  10.0 144.0 296.0

In the above example, the \# symbol implies the first line is continued onto the second line.

1.4.1. Key Words

The key word or key words for a command are shown in uppercase letters. For actual input, you can use all uppercase letters for the key words, all lowercase letters for the key words, or some combination of uppercase and lowercase letters for the key word.

1.4.2. User-Specified Input

The input that you supply is typically shown in lowercase letters. (Occasionally, uppercase letters may be used for user input for purposes of clarity or in examples.) The user-supplied input may be a real number, an integer, a string, or a string list. For the command descriptions, a type appears before the user input. The type (real, integer, string, string list) description is enclosed by angle brackets, <>, and precedes the user-supplied input. For example:

<real>value

indicates that the quantity value is a real number. For the description of an input command, you would see:

FUNCTION = <string>function_name

Your input would be

FUNCTION = my_name

if you have specified a function name called my_name.

Valid user input consists of:

`<integer>`	Integer data is a single integer number.
`<real>`	Real data is a single real number. It may be formatted with the usual conventions, such as `1234.56` or `1.23456e+03`.
`<string>`	String data is a single string.
`<string list>`	A string list consists of multiple strings separated by white space, a comma, a tab, or white space combined with a comma or a tab.

1.4.3. Optional Input

Anything in an input line that is enclosed by square brackets, [ ], represents optional input within the line. This convention is not used to identify optional input lines. Any command line that is optional (in its entirety) will be described within the text.

1.4.4. Default Values

A value enclosed by parentheses, (), appearing after the user input denotes the default value. For example:

SCALE FACTOR = <real>scale_factor(1.0)

implies the default value for scale_factor is 1.0. Any value you specify will overwrite the default.

For your actual input file, you may omit a command line if you want to use the default value associated with the command line. For example, there is a TIME STEP SCALE FACTOR command line used to set one of the time control parameters; the parameter for this command line has a default value of $0.9$. If you want to use the default value of $0.9$ for this parameter, you do not have to include the TIME STEP SCALE FACTOR command line in the TIME CONTROL command block.

1.4.5. Multiple Options for Values

Quantities separated by the | symbol indicate that one and only one of the possible choices must be selected. For example:

EXPANSION RADIUS = <string>SPHERICAL|CYLINDRICAL

implies that expansion radius must be defined as SPHERICAL or CYLINDRICAL. One of the values must appear. This convention also applies to some of the command options within a begin/end block. For example:

SURFACE = <string>surface_name|
NODE SET|NODESET = <string>nodelist_name

in a command block specifies that either a surface or a node set must be specified. In the case of node sets, either the command NODE SET or NODESET may be used.

Quantities separated by the / symbol can appear in any combination, but any one quantity in the sequence can appear only once. For example,

COMPONENTS = <string>X/Y/Z

implies that components can equal any combination of X, Y, and Z. Any value (X or Y or Z) can appear at most once, and at least one value of X, Y, or Z must appear. Some examples of valid expressions in this case are as follows:

COMPONENTS = Z

COMPONENTS = Z X

COMPONENTS = Y X Z

COMPONENTS = Z Y X

An example of an invalid expression would be the following:

COMPONENTS = Y Y Z

1.4.6. Known Issues and Workarounds

Where there are known issues with the code, these are documented in the following manner:

Known Issue

A description of the known issue with the code would be provided here.

Similarly, warnings regarding usage of code features that are not defective, but must be used with care because of their nature, are documented as follows:

Warning

A description of the warning related to the usage of a code feature would be provided here.

1.4.7. Commands Applicable to Only Explicit or Implicit Analyses

As mentioned previously, Sierra/SM has the ability to run either explicit dynamic analyses and implicit quasistatic and dynamic analyses. This guide documents all features of the code for either of these analysis types. In most cases, the features available for explicit analyses are also available for implicit analysis, and vice versa. However, there are some capabilities that are only available for one type of analysis. These are denoted in this document with the following icons in the margin.

Explicit only Features and commands only available for explicit dynamics have this icon in the margin next to their documentation.

Implicit only Features and commands only available for implicit dynamics and quasistatics have this icon in the margin next to their documentation.

In listings of command lines and blocks, smaller versions of these icons are used to denote commands only available for explicit or implicit analyses. These appear in the margin next to either an individual command line, or next to the opening line of a command block, as shown in these examples:

#Example explicit command line:
DEATH ON INVERSION = OFF/ON(OFF)

#Example implicit command line:
CAPTURE TOLERANCE = <real>cap_tol

#Example explicit command block:
BEGIN LINE WELD    
  ...
END [LINE WELD]

#Example implicit command block:
BEGIN SOLVER 
...
END [SOLVER]