\chapter{Command Input} \label{chap:command}

Each of the commands in \numbers\ are described below.  The commands are
divided into four categories: (1)~operational commands, (2)~parameter
setting commands, (3)~database selection and display commands, and
(4)~miscellaneous commands.  The operational commands are the commands
that actually perform the utility functions of \numbers, such as
calculating the mass properties, or verifying the correct definition of
contact surfaces.  The parameter setting commands are used to setup the
parameters required by the operational commands, such as the material
density which is required to calculate the mass properties.  The
database selection and display commands simply echo information
contained on the database to the terminal.  Miscellaneous commands are
simply commands that do not fit into any of the previous categories.

\input{cominput}

\newpage
\section{Operational Commands}\label{sec:oper}

\cmddef{\cmdverb{PROPERTIES}
      \param{nquad} \default{1},
      [\param{density}]
\cmdnext \cmdverb{MASS}
      \param{nquad} \default{1},
      [\param{density}]
} {
 \cmd{properties} or \cmd{mass} calculates several mass properties of
the body.  The calculated properties are the volume and mass of each
element block; the mass moments of inertia of the body; the
location of the center of gravity; the minimum, maximum, and average
element volume for each element block; and the number of elements in
each element block.   A value called the timestep factor is also
calculated.  This value can be used to estimate the timestep which will
be used in an explicit dynamic analysis.

The parameter \param{nquad} sets the number of quadrature (numerical
integration) points which will be used to calculate mass properties. It
must be 1 or 4 for a two-dimensional mesh, and 1 or 8 for a
three-dimensional mesh.  If it is not entered, it will be set to the
last entered value, or to 1 if it has never been set.  If all of the
material densities are equal, they can be set by entering a positive
value for the optional parameter \param{density}. If the densities are
not equal, they must be input through the \cmd{density} command.

If the \cmd{exodus} flag is \cmd{true}, the mass properties will be
calculated for the deformed shape of the body at each time step; if
\cmd{exodus} is \cmd{false}, values will only be calculated for the
undeformed geometry.  Section~\ref{sec:mass} describes the algorithms
used in this calculation, and the resulting output.
}

\cmddef{\cmdverb{LOCATE} \cmd{\{NODES$|$ELEMENTS\}}
      \param{locate\_option}
} {
\cmd{LOCATE} is used to locate \cmd{NODES} or \cmd{ELEMENTS} that are a
specified distance from a user-defined point, line, or plane.  The
several available options are defined below.  The algorithms used are
described in Section~\ref{sec:locate}.  If \cmd{ELEMENTS} is specified,
the distance is measured to the element centroid.  In the descriptions
of the \cmd{locate} options below, the $z$ coordinates are entered only
for three-dimensional bodies.  \cmd{LOCATE} calculates distances only
for the undeformed geometry regardless of the setting of the
\cmd{EXODUS} flag.

\cmdoption{\cmd{LOCATE \{NODES$|$ELEMENTS\} POINT}
   \param{$x_0$, $y_0$, $z_0$}, \param{distance}, \param{tolerance}
} {
outputs all \cmd{nodes} or \cmd{elements} located a
distance of \param{distance}$\pm$\param{tolerance} from the
point \param{$x_0$, $y_0$, $z_0$}.  If no nodes or elements are
located in the specified range, the minimum calculated distance
is printed.  The output includes the node or element number, the
coordinates of the node or the element centroid, the distance to the
point, and the angles $\theta$ and $\phi$\footnote{$\phi$ is defined for
three-dimensional bodies only}.  The angles are defined in
Section~\ref{sec:locate}
}

\cmdoption{\cmd{LOCATE \{NODES$|$ELEMENTS\} LINE}
   \param{$x_0$, $y_0$, $z_0$},
   \param{$x_1$, $y_1$, $z_1$},
   \param{distance},
   \param{tolerance},
   \cmd{[BOUNDED$|$UNBOUNDED]}\default{\cmd{UNBOUNDED}}
} {
outputs all \cmd{nodes} or \cmd{elements} located a distance of
\param{distance}$\pm$\param{tolerance} from the line defined by the two
points \param{$x_0$, $y_0$, $z_0$}, and \param{$x_1$, $y_1$, $z_1$}. If
no nodes or elements are located in the specified range, the minimum
calculated distance is printed.  The output includes the node or element
number, the coordinates of the node or the element centroid, and the
normal and parametric distances from the node or element centroid to the
line.  The distances are defined in Section~\ref{sec:locate}
}

\cmdoption{\cmd{LOCATE \{NODES$|$ELEMENTS\} PLANE}
   \param{$x_0$, $y_0$, $z_0$},
   \param{$i$, $j$, $k$},
   \param{distance},
   \param{tolerance}
} {
outputs all \cmd{nodes} or \cmd{elements} located a
distance of \param{distance}$\pm$\param{tolerance} from the plane that
passes through the point \param{$x_0$, $y_0$, $z_0$} and has a normal
defined by the vector \param{$i$, $j$, $k$}. This command is only
defined for a three-dimensional body.  If no nodes or elements are
located in the specified range, the minimum calculated distance is
printed.  The output includes the node or element number, the
coordinates of the node or the element centroid, and the normal and
radial distances to the plane.  The distances are defined in
Section~\ref{sec:locate}
}
}

\cmddef{\cmdverb{CAVITY  }
   \param{sset$_{1}$}, \param{sset$_{2}$}, \ldots, \param{sset$_n$}
} {
\cmd{CAVITY} calculates the volume of a cavity defined by the element
sidesets \param{sset$_{1}$} to \param{sset$_n$}.  The cavity volume
algorithm, the resulting output, and the rules for defining a valid
cavity are described in Section~\ref{sec:cavity}.

If the \cmd{EXODUS} flag is \cmd{TRUE}\footnote{See command
\cmd{EXODUS}}, the cavity volume is calculated for each of the selected
time steps, else only the undeformed cavity volume is calculated.
}

\cmddef{\cmdverb{LIMITS} [\cmd{ALLTIMES}]
} {
\cmd{limits} determines the minimum, maximum, and range of the
X, Y, and Z coordinates for each of the selected material blocks.
If \cmd{ALLTIMES} is specified, the limits are determined for each of
the selected time steps.  Note that the \cmd{exodus} flag status does
not affect this command.
}

\cmddef{\cmdverb{OVERLAP }
      \param{flag$_m$}, \param{flag$_s$}
} {
\cmd{overlap} is used to verify contact surfaces or slidelines.  The
command determines whether any of the nodes on the surface defined by
the sideset \param{flag$_s$} penetrate the element faces on the surface
defined by the sideset \param{flag$_m$}.  If a node on the
\param{flag$_s$} surface penetrates the \param{flag$_m$} surface, the
node and element numbers are output along with the connectivity array
for the penetrated element. The algorithm and assumptions used in this
calculation are described in Section~\ref{sec:overlap}.  \cmd{overlap}
checks only the undeformed geometry regardless of the setting of the
\cmd{EXODUS} flag.
}

\cmddef{\cmdverb{GAP}
      \param{flag$_m$}, \param{flag$_s$},
      \param{d$_{\max}$}, \param{\cmd{[DISTANCE$|$NORMAL]}}
} {
\cmd{gap} calculates the distance between nodes on the surfaces defined
by the sideset flags \param{flag$_m$} and \param{flag$_s$}.  For each
node on the sideset \param{flag$_m$}, the program searches for a
matching node on the sideset \param{flag$_s$}.  A matching node is
the closest node measured according to the method specified by
\param{\cmd{[DISTANCE$|$NORMAL]}}.  If \cmd{DISTANCE} is specified, the
distance is simply the actual distance between the two nodes; if
\cmd{normal} is specified, the distance is the tangential distance to
the node on the \param{flag$_s$} surface measured from a line passing
through the node on the \param{flag$_m$} surface and normal to the
surface.  If the distance to the closest \param{flag$_s$} node is
greater than \param{d$_{\max}$}, then the \param{flag$_m$} node has no
match and is not shown in the output.

For each  \param{flag$_m$} node with a match, the output shows the
matching  \param{flag$_s$} node, the direction cosines of the surface,
and the normal and tangential distance from the  \param{flag$_m$} node
to the  \param{flag$_s$} node where the normal is defined by the
direction cosine vector.

If the \cmd{EXODUS} flag is \cmd{TRUE}, the above information is output
for each time step.  Note that the node matching process and the
determination of the surface normal are only performed on the undeformed
geometry; therefore, the distances output for subsequent time steps are
measured relative to the undeformed normal.

This command is normally used to calculate the change in distance
between two surfaces, for example, the closure of a drift in a
geomechanics problem.  Note that unless \param{d$_{\max}$} is specified,
a match will be found for every node on the \param{flag$_m$} surface.
This output from this command can be very large; it is recommended that
\cmd{echo} be turned \cmd{off} prior to executing a \cmd{GAP} command.
The algorithm and assumptions used for this command are described in
Section~\ref{sec:gap}.
}

\section{Parameter Setting Commands}\label{sec:param}

\cmddef{\cmdverb{AXISYMMETRIC}
} {
\cmd{AXISYMMETRIC} informs \numbers\ that the two-dimensional body
described in the \EXO\ database is axisymmetric.  All of the relevant
operational commands will calculate values based on an axisymmetric
geometry.  This is the default for two-dimensional bodies.
}

\cmddef{\cmdverb{PLANAR} or \cmdverb{PLANE}
} {
\cmd{PLANAR} informs \numbers\ that the two-dimensional body described
in the \EXO\ database is planar or plane strain. All of the relevant
operational commands will calculate values based on a planar geometry.
}

\cmddef{\cmdverb{EXODUS}
      \cmd{[ON$|$OFF]} \\
      \default{\cmd{ON} if timesteps present, else \cmd{OFF}}
} {
\cmd{EXODUS} sets the \cmd{EXODUS} flag to \cmd{TRUE} which indicates
that the operational commands should calculate values for each of the
selected time steps, or \cmd{FALSE} which indicates that the operational
commands should only calculate values for the basic undeformed geometry.
}

\cmddef{\cmdverb{DENSITY }
} {
\cmd{DENSITY} prompts the user for the density of each of the element
blocks.  The material density is used in the mass properties calculation
(Commands \cmd{MASS} and \cmd{PROPERTIES}).  If densities are not
entered prior to entering a \cmd{MASS} or \cmd{PROPERTIES} command, the
\cmd{density} command will be executed automatically.  An optional
16-character label can be entered following the density.  The label will
be used to identify the material blocks in the mass properties output.
The label cannot contain any blanks.
}

\cmddef{\cmdverb{SELECT}
   \param{option}
} {
\cmd{SELECT} selects the materials or material blocks for the
operational commands.

\cmdoption{\cmd{SELECT BLOCKS}
   [\cmd{ALL},]
   \param{block\_id$_{1}$}, \param{block\_id$_{2}$}, \ldots\
      \\ \default{all element blocks}
} {
selects the element blocks. The \param{block\_id} is the element block
identifier displayed by the \cmd{LIST BLOCKS} command. The relevant
operational commands will only calculate values for the selected element
blocks.
}
}

\cmdoption{\cmd{SELECT MATERIALS}
   [\cmd{ALL},]
   \param{material\_id$_{1}$}, \param{material\_id$_{2}$}, \ldots\
      \\ \default{all materials}
} {
selects the element blocks with the material number corresponding to
\param{material\_id}.  The relevant operational commands will only
calculate values for the selected materials.
}

\cmddef{\cmdverb{TMIN}
   \param{tmin} \default{minimum database time}
} {
\cmd{TMIN} sets the minimum selected time \param{tmin} to the specified
parameter value.
}

\cmddef{\cmdverb{TMAX}
   \param{tmax} \default{maximum database time}
} {
\cmd{TMAX} sets the maximum selected time \param{tmax} to the specified
parameter value.
}

\cmddef{\cmdverb{DELTIME}
   \param{$\Delta t$} \default{0.0}
} {
\cmd{DELTIME} sets the selected time interval \param{$\Delta t$} to the
specified parameter value.
}

\cmddef{\cmdverb{TIMES}
   \param{tmin} \cmd{TO} \param{tmax} \cmd{BY} \param{$\Delta t$}
} {
\cmd{TIMES} sets \param{tmin}, \param{tmax}, and
\param{$\Delta t$} with a single command.
}

\section{Database Display Commands}
\label{cmd:display}

\cmddef{\cmdverb{LIST}
   \param{option}
} {
\cmd{LIST} displays the database information specified by \param{option}
on the user's terminal. The ``selected'' items are specified with the
\cmd{SELECT} command.

\cmdoption{\cmd{LIST \{VARS$|$VARIABLES\}}
} {
displays a summary of the database. The summary includes the database
title; the number of nodes, elements, and element blocks; the number of
node sets and side sets; and the number of each type of
variable.
}

\cmdoption{\cmd{LIST \{BLOCKS$|$MATERIALS\}}
} {
displays a summary of the element blocks. The summary includes
the block identifier, the number of elements in the block, the element
number of the first and last element in the block, and the block status,
either selected or not selected.
}

\cmdoption{\cmd{LIST \{NSETS$|$NODESETS\}}
} {
displays a summary of the node sets. The summary
includes the set identifier and the number of nodes in the set.
}

\cmdoption{\cmd{LIST \{SSETS$|$SIDESETS\}}
} {
displays a summary of the side sets. The summary
includes the set identifier, the number of elements in the set, and the
number of nodes in the set.
}

\cmdoption{\cmd{LIST STEPS}
} {
displays the number of time steps and the minimum and maximum time step
times.
}

\cmdoption{\cmd{LIST TIMES}
} {
displays the step numbers and times for all time steps on the database.
}
}

\cmddef{\cmdverb{HELP}
   \param{command} \default{no parameter}
} {
\cmd{HELP} displays information about the program command given as the
parameter. If no parameter is given, all the command verbs are
displayed. \cmd{HELP} is system-dependent and may not be available on
all systems.
}

\section{Miscellaneous Commands}\label{sec:misc}

\cmddef{\cmdverb{ECHO}
      \cmd{[ON$|$OFF]} \default{\cmd{ON}}
} {
\cmd{ECHO} controls the output of results to the terminal.  If \cmd{ON},
the results are output to the screen. If \cmd{OFF}, \cmd{PRINT} is
automatically set to \cmd{ON}.  Error messages and information from a
\cmd{LIST} command are always output to the terminal.
}

\cmddef{\cmdverb{PRINT}
      \cmd{[ON$|$OFF]} \default{\cmd{ON}}
} {
\cmd{PRINT} controls the output of results to the output file.  If
\cmd{ON}, the results are printed to the output file. If \cmd{OFF},
\cmd{ECHO} is automatically set to \cmd{ON}.
}

\cmddef{\cmdverb{COMMENT }   [\cmd{PAGE,}] \param{ncom}\default{1}
} {
\cmd{COMMENT} prompts the user for a \param{ncom} comment lines which
are written to the output file.  If the optional parameter \cmd{PAGE} is
present, a page eject will be written to the output file prior to
writing the comment line(s).
}

\cmddef{\cmdverb{EXIT    }
} {
\cmd{EXIT} exits the program and closes all files.
}