1.5. Style Guidelines
This section gives information that will affect the overall organization and appearance of an input file. It also contains recommendations that will help construct input files that are readable and easy to proof.
1.5.2. Continuation Lines
An input line can be continued by placing a \# pair of characters (or \$) at the end of the line. The following line is then taken to be a continuation of the preceding line that was terminated by the \# or \$. Everything after the line-continuation pair of characters is discarded, including the end-of-line.
1.5.3. Capital and Lower Case Letters
Almost all the character strings in the input lines are case insensitive. For
example, the BEGIN SIERRA key words could appear as:
BEGIN SIERRA
begin sierra
Begin Sierra
You could specify a SIERRA command block with:
BEGIN SIERRA BEAM
and terminate the command block with this input line:
END SIERRA beam
Case is important only for file name specifications. If you have defined a restart file with uppercase and lowercase letters and want to use this file for a restart, the file name you use to request this restart file must exactly match the original definition you chose.
1.5.4. Commas and Tabs
Commas and tabs in input lines are ignored.
1.5.5. Blank Spaces
We recommend that everything be separated by blank spaces. For example, a command line of the form
node set = nodelist_10
is recommended over the forms
node set= nodelist_10
node set =nodelist_10
Both of the above two lines are correct, but it is easier to check the first form (the equal sign surrounded by blank space) in a large input file.
The parser will accept the following line:
BEGIN SIERRABEAM
However, it is harder to check this line for the correct spelling of the key words and the intended SIERRA scope name than this line:
BEGIN SIERRA BEAM
It is possible to introduce hard-to-detect errors because of the way in which the blank spaces are handled by the command parser. Suppose you type
begin functions my_func
rather than the following correct form:
begin function my_func
For the incorrect form of this command line (in which functions is used rather than function), the parser will generate a string name of
s my_func
for the function name rather than the following expected name:
my_func
If you attempt to use a function named my_func, the parser will generate an error because the list of function names will include s my_func but not my_func.
1.5.6. General Format of the Command Lines
In general, command lines have the following form:
keyword = value
This pattern is not always followed, but it describes the vast majority of the command lines.
1.5.7. Delimiters
The delimiter used throughout this document is = (the equal sign). Typically, but not always, the = separates key words from input values in a command line. Consider this command line:
COMPONENTS = X
Here, the key word COMPONENTS is separated from its value, a string in this case, by the =. Some command lines do allow for other delimiters. The use of these alternate delimiters is not consistent, however, throughout the various command lines. (This lack of consistency has the potential for introducing errors in this document as well as in your input.) The = provides a strong visual cue for separating key words from values. By using the = as a delimiter, it is easier to proof your input file. It also makes it easier to do “cut and paste” operations. If you accidentally delete =, it is easier to detect than accidentally removing part of one of the other delimiters that could be used.
1.5.8. Order of Commands
Commands have no ordering requirements. Both the input sequence:
BEGIN PRESCRIBED DISPLACEMENT
NODE SET = nodelist_10
COMPONENT = X
FUNCTION = my_function
END PRESCRIBED DISPLACEMENT
and the input sequence:
BEGIN PRESCRIBED DISPLACEMENT
FUNCTION = my_function
COMPONENT = X
NODE SET = nodelist_10
END PRESCRIBED DISPLACEMENT
are valid, and they produce the same result. Remember, that command lines and command blocks must appear in the proper scope.
1.5.9. Abbreviated END Specifications
It is possible to terminate a command block without including the key word or key words that identify the block. You could define a specific instance of the prescribed displacement boundary condition with:
BEGIN PRESCRIBED DISPLACEMENT
and terminate it with:
END
as opposed to this specification:
END PRESCRIBED DISPLACEMENT
Both the short termination (END only) and the long termination (END followed by identification, or name, of the command block) are valid. It is recommended that the long termination be used for any command block that becomes large. The RESULTS OUTPUT command block described in later chapters can become fairly lengthy, so this is probably a good place to use the long termination. For most boundary conditions, the command block will typically consist of five lines. In such cases, the short termination can be used. Using the long termination for the larger command blocks will make it easier to proof your input files. If you use the long termination, the text following the END key word must exactly match the text following the BEGIN key word. You could not have BEGIN PRESCRIBED DISPLACEMENT paired with an END PRESCRIBED DISPL to define the beginning and ending of a command block.
1.5.10. Indentation
When constructing an input file, it is useful, but not required, to indent a scope that is nested inside another scope. Command lines within a command block should also be indented in relation to the lines defining the command block. This will make it easier to construct the input file with everything in the correct scope and with all the command blocks in the correct structure.
1.5.11. Aprepro Text Processing
Aprepro is used for input deck text preprocessing. Generally any text inside curly brackets { } will be interpreted by aprepro. This include text inside of comments. See [[1]] for more information. The sierra script can run aprepro automatically on an input file by adding a command line option as shown in this example:
sierra -a adagio -i sierra_input.i
Note, if there is text in a file surrounded by brackets { }, and you do not want it to be processed by aprepro, it can be “escaped,” or turned off for that text block, with the \ character. For example:
# Include an external file with aprepro
# {include("matProps.inp")}
# Turn aprepro off processing so that matProps is not included
# \{include("matProps.inp")}
1.5.12. Including Files
External text files containing input commands can be included at any point in the Sierra/SM input file using the aprepro include command. This command can be used in any context in the input file. To use this command, use the command include command followed by the name of the file to be included. For example, the command:
{include("displacement_history.i")}
would include the displacement_history.i as if the contents of that file were placed in the position that it is included in the input file. The included file is contained in the standard echo of the input provided at the beginning of the log file. If requested, aprepro substitution will occur inside of the included text. Note, the user must use double quotes around the name of the text file. If single quotes are used, aprepro will not be able to find the file.
1.5.1. Comments
A comment is anything between the
#symbol or the$symbol and the end-of-line. If the first non-blank character in a line is a#or$, the entire line is a comment line. You can also place a#or$(preceded by a blank space) after the last character in an input line used to define a command block or command line.