EXODUS/packages/seacas/doc-source/exo_utils/introduction.tex

\chapter{Introduction}

The applications \exodiff{}, \epu{}, \ejoin{}, and \conjoin{} are
documented in this report.  These applications are members of the
Sandia Engineering Analysis Code Access System (SEACAS~\cite{bib:seacas})
which is used by analysts at Sandia National Laboratories.  The
applications all read and/or write finite element databases stored in
the \exo{}~\cite{bib:exodus} format.

Each application is targeted at a few specific areas of functionality:

\begin{description}
\item[\exodiff] compares the results data from two \exo{} files with
user-specified relative or absolute tolerances. Output is either (1)~a
summary of the differences, or (2)~a new \exo{} database where each
variable is the difference of the variables in the input files.
Typical uses are for verifying the results written by an application
code in regression testing or for comparing the results of multiple
analyses in a parameter study. \exodiff{} is described in
Chapter~\ref{ch:exodiff}\footnote{Richard Drake, \SNLA, was
responsible for the initial design and creation of \exodiff}.

\item[\epu] combines multiple \exo{} databases produced by a parallel
application into a single \exo{} database.  \epu{} provides several
options for controlling the output database contents.  Typical uses
are for combining two or more processor-specific \exo{} databases into
a single \exo{} database.
\epu{} is described in Chapter~\ref{ch:epu}.

\item[\ejoin] joins two or more \exo{} databases into a single
\exo{} database. The input databases must have disjoint meta and bulk data.
That is,
\begin{itemize}
\item element blocks are not combined in the output model.  Each
element block in each input file will produce an element block in the
output file. Similarly for nodesets and sidesets.
\item Each node in each input file will produce a node in the output
file unless one of the node matching options
(\param{-match\_node\_ids} or \param{-match\_node\_coordinates}) is specified.
\item Each element in each input file will produce an element in the
output file.
\end{itemize}
If any of the input databases have timesteps, then the timestep values
and counts must match on all databases with timesteps.
\ejoin{} is described in Chapter~\ref{ch:ejoin}.

\item[\conjoin] joins two or more \exo{} databases into a single
database. The input databases should represent the same model meta
data and similar bulk data with results data written sequentially. The
output database will contain the model geometry and all of the
non-temporally-overlapping results data. For example, if the first
database contains time data from 0 to 5 seconds, and the second
database contains time data from 4 to 10 seconds; the output database
will contain time data from 0 to 10 seconds.  Typical uses are to join
databases written from restarted analyses into a single database.
\conjoin{} is described in Chapter~\ref{ch:conjoin}.
\end{description}

Three of the applications above are used to join multiple \exo{}
databases into a single \exo{} database, so it can be confusing to
decide which code should be used.
\begin{itemize}
\item If the multiple \exo{} databases were created as the output from a
parallel analysis code with each compute processor writing its portion
of the model, then \epu{} would be used to join the databases.

\item If the multiple \exo{} databases each contain a distinct portion of the
analysis model, then \ejoin{} would be used to join the databases.

\item If the multiple \exo{} databases each contain basically the same
analysis model at different times throughout the analysis event, then
\conjoin{} would be used to join the databases.

\end{itemize}

\section{\exo{} Concepts}
The \exo{} database documentation can be accessed at
\url{http://sandialabs.github.io/seacas/exodusII-new.pdf}. It
contains a full detailed description of \exo{}. This section presents
an overview of the concepts and structure of an \exo{} database to give some
details which will be referred to in subsequent chapters. An \exo{}
database contains groupings of nodes and elements.  The groupings or
entities include element blocks, nodesets, and sidesets.

\subsection{Meta Data and Bulk Data}
The data or information in an \exo{} database can be grouped into two
major types: meta data and bulk data.  The meta data is the data that
gives an overview of the model and geometry that the \exo{} database
contains. It is data like:
\begin{itemize}
\item element block, nodeset, sideset counts, ids, and names;
\item the topology of the elements in an element block;
\item the names of the transient variables and which entities the
	variables are defined on.
\item shape and position of the entities, i.e., the model ``topology''.
\end{itemize}

The bulk data is the ``problem size'' data such as the ids and
coordinates for each node; the ids, connectivity, and attributes for
each element; the list of nodes in a nodeset and the list of elements
and element faces in a sideset; the values of the transient data on
each node and element.

The meta data is a higher-level view of the model and the bulk data is
one realization of that model.  Note that several different databases
can have the same or similar meta data; but they could have vastly
different bulk data.  As a trivial example, the meta data for a model
could be:
\begin{itemize}
\item a single element block named ``cube'' with an id of 1.
\item element block ``cube'' contains ``hex8'' elements.
\item element block ``cube'' is centered on the origin and is 10
inches per side with faces aligned with X, Y, and Z planes.
\item a nodeset named ``PosX'' with id 1 on the positive X face.
\end{itemize}

One instance of bulk data for this meta data is an element block with
1,000,000 hexes with global ids ranging from 2 to 2,000,000 by 2.
Another instance of bulk data for the same meta data could have the
same element block with 8 hex elements with global ids
10,20,30,40,50,60,70,80.

Another example of multiple bulk data instances for a single meta data
is decomposing an \exo{} database for a parallel run on 4 processors.
Each decomposed database would have the same meta data, but the bulk
data would be different on each decomposed database.

\subsection{Database Sections}
An \exo{} database is often thought of as containing multiple
``sections''.  These include the ``mesh'' section which includes the
bulk data describing the geometries; the element connectivities; and
collections of nodes and/or (element, element-local-face) pairs which
can be used for boundary conditions.  Basically, all of the
non-transient portions of the bulk data.  Historically, this has been
called the ``genesis'' section of the \exo{} database.  The other
section includes the ``results'' portion of the bulk data which is the
global, nodal, element, nodeset, and sideset variables; and the
timestep time values. The ``results'' portion is also called the
``transient'' section and is usually applied to transient data with
each time step associated with a unique output state of the analysis
code. The results portion is not required to be time-related data and
can store information about any serialized data. For example, the
calculated modal frequencies and mode shapes of the model could be
stored in the ``transient'' section.

The \exo{} database documentation includes much more detail, but the
above terminology should be helpful for some of the utility
descriptions that follow in subsequent chapters.

\section{Licensing}
Each of the utilities described in this section is open-source
licensed under the ``New BSD License'' or ``Modified BSD License''.
The terms of the license are:

\begin{quote}
Copyright(C) 20XX\footnote{The year is different for each of \epu{},
\exodiff, \ejoin, and \conjoin.} National Technology & Engineering Solutions
of Sandia, LLC (NTESS).  Under the terms of Contract DE-NA0003525 with
NTESS, the U.S. Government retains certain rights in this software.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

\begin{itemize}
\item Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.

\item Redistributions in binary form must reproduce the above
      copyright notice, this list of conditions and the following
      disclaimer in the documentation and/or other materials provided
      with the distribution.

\item Neither the name of NTESS nor the names of its
      contributors may be used to endorse or promote products derived
      from this software without specific prior written permission.
\end{itemize}

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
\end{quote}

The software is available at \url{https://github.com/sandialabs/seacas}.