.. _introduction-input:

***********************
Overall Input Structure
***********************

Sierra/SM is one of many mechanics codes built on the SIERRA Framework. The SIERRA Framework provides the capability to perform multiphysics analyses by coupling together SIERRA codes appropriate for the mechanics of interest. Input files may be set up for analyses using only Sierra/SM, or they may be set up to couple Sierra/SM and one or more other SIERRA analysis codes. For example, you might run an implicit Sierra/SM analysis to compute a stress state, and then use the results of this analysis as initial conditions for an explicit analysis. For a Sierra multiphysics analysis, the commands for all physics modules used in the analysis will all be in the same input file. Therefore, the input for Sierra/SM reflects the fact that it could be part of a multiphysics analysis. Sierra/SM coupled with the Sierra package Aria is Arpeggio.

Sierra input file syntax uses ideas from programming languages. A multiphysics analysis is defined using *scope*, i.e., the extent of the subject matter that part of the input file deals with, to group similar commands. Examples of the Sierra input files are given in this section, in :numref:`introduction-scope`, and in :ref:`Appendix A <appendix-explicit>` and :ref:`Appendix B <appendix-implicit>`.

The broadest scope in the input file is the SIERRA scope. The SIERRA scope contains information that can be shared among different physics. Examples of physics information that can be shared are definitions of functions and materials. For example, in a coupled implicit/explicit Sierra/SM analysis, both the implicit and explicit components could reference functions to define time histories for boundary conditions or stress-strain curves. Material model definitions could also be shared in a similar manner.

A scope may contain another scope. Within a SIERRA scope the overall analysis from the start time to the end time is controlled by the ``procedure`` scope In a multiphysics analysis, a SIERRA scope may contain multiple procedures.

The ``procedure`` scope may contain a ``region`` scope. The region scope controls a single time step. Inside the procedure scope (but outside of the region scope) are commands that set the start time and the end time for the analysis.

Inside the region scope for Sierra/SM are definitions for boundary conditions and contact. In a multiphysics analysis, there would be more than one region. In a coupled implicit/explicit solid mechanics example, there would be both a Presto region and an Adagio region, each within its respective procedures. The definitions for boundary conditions and contact and the mesh specification for explicit dynamics would appear in the Presto region; the definitions for boundary conditions and contact and the mesh specification for the implicit analysis would appear in the Adagio region.

Scope is defined by a command block. The command blocks group together command lines or other command blocks that share a similar functionality. A command block will begin with an input line that has the word ``BEGIN`` and end with an input line that has the word ``END``. The SIERRA scope, for example, is defined by a command block that begins with an input line of the following form:

.. code-block:: sierrainput

    BEGIN SIERRA my_problem

The two character strings ``BEGIN`` and ``SIERRA`` are the key words for this command block. An input line defining a command block or a command line will have one or more key words. The string ``my_problem`` is a user-specified name for this SIERRA scope. The SIERRA scope is terminated by an input line of the following form:

.. code-block:: sierrainput

    END SIERRA my_problem

In the above input line, ``END`` and ``SIERRA`` are the key words
to end this command block. SIERRA scope termination may be shortened to

.. code-block:: sierrainput

    END

as discussed in :numref:`introduction-style-endspecs`. Similar input lines are used to define the procedure and region scopes. Boundary conditions are another example where a scope is defined. A particular instance of a boundary condition for a prescribed displacement boundary condition is defined with a command block. The command block for the boundary condition begins with an input line of the form:

.. code-block:: sierrainput

    BEGIN PRESCRIBED DISPLACEMENT

and ends with an input line of either of these forms:

.. code-block:: sierrainput

    END PRESCRIBED DISPLACEMENT

.. code-block:: sierrainput

    END

Command lines appear within the command blocks. The command lines typically have the form ``keyword = value``, where ``value`` can be a real, an integer, or a string. In the previous example of the prescribed displacement boundary condition, there would be command lines inside the command block that are used to set various values. For example, the boundary condition might apply to all nodes in node set 10, in which case there would be a command line of the following forms:

.. code-block:: sierrainput

    NODE SET = nodelist_10
 
.. code-block:: sierrainput

    NODESET = nodelist_10

If the prescribed displacement were to be applied along a given component direction, there would be a command line of this form:

.. code-block:: sierrainput

    COMPONENT = X

The form above would specify that the prescribed displacement would be in the :math:`x`-direction. Finally, if the displacement magnitude is described by a time history function with the name ``my_function``, there would be a command line of this form:

.. code-block:: sierrainput

    FUNCTION = my_function
 
Functions are discussed in :numref:`commands-scope-xyfuncs` and :numref:`commands-scope-genfuncs`.

The command block for the boundary condition with the appropriate command lines would appear as follows:
 
.. code-block:: sierrainput

    BEGIN PRESCRIBED DISPLACEMENT
        NODE SET = nodelist_10
        COMPONENT = X
        FUNCTION = my_function
    END PRESCRIBED DISPLACEMENT

It is possible to have a command line with the same key words appearing in different scopes. For example, we might have a command line identified by the word ``TYPE`` (introduced in :numref:`commands-scope-xyfuncs`) in two or more different scopes. The command line would perform different functions based on the scope in which it appeared, and the associated value could be different in the two locations.

The input lines are read by a parser that searches for recognizable key words. If the key words in an input line are not in the list of key words used by Sierra/SM to describe command blocks and command lines, the parser will generate an error. A set of key words defining a command line or command block for Sierra/SM that is not in the correct scope will also cause a parser error. For example, the key words ``STEP INTERVAL`` define a valid command line in the scope of the ``TIME CONTROL`` command block. However, if this command line was to appear in the scope of one of the boundary conditions, it would not be in the proper scope, and the parser would generate an error. Once the parser has an input line with any recognizable key words in the proper scope, a method can be called that will handle the input line.

There is an initial parsing phase that checks only the parser syntax. If the parser encounters a command line it cannot parse within a certain scope, the parser will indicate it cannot recognize the command line and will list the various command lines that can appear within that scope. The initial parsing phase will catch errors such as the one described in the previous paragraph (a command line in the wrong scope). It will also catch misspelled key words. 

The initial parsing catches some but not all types of errors. Some errors not detected in the initial parsing phase are caught afterwards and are handled one at a time. One such example is that initial parsing will not catch a command line value that is out of command line's specified range. A second example is a combination of command lines within a command block that is not allowed.
