****************
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.

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.

.. _introduction-style-continuation:

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.

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:

.. code-block:: sierrainput

    BEGIN SIERRA

.. code-block:: sierrainput

    begin sierra

.. code-block:: sierrainput

    Begin Sierra

You could specify a ``SIERRA`` command block with:

.. code-block:: sierrainput

    BEGIN SIERRA BEAM

and terminate the command block with this input line:

.. code-block:: sierrainput

    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.

Commas and Tabs
===============

Commas and tabs in input lines are ignored.

Blank Spaces
============

We recommend that everything be separated by blank spaces. For example, a command line of the form

.. code-block:: sierrainput

    node set = nodelist_10

is recommended over the forms

.. code-block:: sierrainput

    node set= nodelist_10

.. code-block:: sierrainput

    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:

.. code-block:: sierrainput

    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:

.. code-block:: sierrainput

    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

.. code-block:: sierrainput

    begin functions my_func

rather than the following correct form:

.. code-block:: sierrainput

    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

.. code-block:: sierrainput

    s my_func

for the function name rather than the following expected name:

.. code-block:: sierrainput

    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``. 

General Format of the Command Lines
===================================

In general, command lines have the following form:

.. code-block:: sierrainput

    keyword = value

This pattern is not always followed, but it describes the vast majority of the command lines.

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:

.. code-block:: sierrainput

    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.

Order of Commands
=================

Commands have no ordering requirements. Both the input sequence:

.. code-block:: sierrainput
    
    BEGIN PRESCRIBED DISPLACEMENT
      NODE SET = nodelist_10
      COMPONENT = X
      FUNCTION = my_function
    END PRESCRIBED DISPLACEMENT 

and the input sequence:

.. code-block:: sierrainput

    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.

.. _introduction-style-endspecs:

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:

.. code-block:: sierrainput

    BEGIN PRESCRIBED DISPLACEMENT

and terminate it with:

.. code-block:: sierrainput

    END

as opposed to this specification:

.. code-block:: sierrainput

    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.

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.

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 [:footcite:p:`int:ref:sja`] 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:

.. code-block:: sh
    
    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:

.. code-block:: sh
    
    # Include an external file with aprepro
    #   {include("matProps.inp")}

    # Turn aprepro off processing so that matProps is not included
    #   \{include("matProps.inp")}

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:

.. code-block:: sh
    
    {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.

.. raw::
   html

   <hr>

.. footbibliography::
