\chapter{Conjoin}\label{ch:conjoin} \section{Introduction} A finite element analysis can often generate multiple results and/or restart databases due to model bulk data changes or restarting the analysis. The bulk data changes are caused by element death, element creation, and surface evolution. Because the \exo{} database requires a constant model meta data and bulk data description, the analysis code must close the current results and restart databases and create new databases if the model meta data or bulk data change. At the end of the analysis, there will be multiple database files all describing a similar model with similar meta data, but with each database containing a different set of bulk data descriptions of that meta data. Another cause of multiple \exo{} databases is when the analysis job is restarted one or more times. This is typically the case for long-running analyses whose total execution time exceeds the maximum allowed queue time on a compute cluster. A restart database is written at the end of each compute segment and then the job is resubmitted to the compute cluster and is restarted one or more times. At the end of the analysis, there will be at least one database for each compute segment and it is often desirable to combine these databases into a single database for visualization and post processing. \conjoin{} joins two or more \exo{} databases into a single database. The input databases should represent the same model geometry with similar variables. The output database will contain the model geometry and all of the non-temporally-overlapping results data. If two databases have overlapping timestep ranges, the timesteps from the later database will be used. 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 4 seconds from the first database and time data from 4 to 10 seconds from the second database. If two nodes have the same global id and are also colocated, then they are combined to a single node in the output. Similarly, elements with the same global id and the same nodal connectivity are combined into a single element in the output file. The output database will contain the union of the meta and bulk data entities (i.e., nodes, elements, element blocks, sidesets, and nodesets) from each input database. The existence of an entity at a particular timestep is indicated via a status variable. For example, if the first database is the mesh shown in Figure~\ref{fig:cjm1} at time 0.0 seconds, and the second database is the mesh shown in Figure~\ref{fig:cjm2} at time 1.0 seconds, then the combined mesh would be the union of the nodes and elements in the two meshes as shown in Figure~\ref{fig:cjall}. \begin{figure}[htp] \centering \subfloat[First Database, time 0]{\label{fig:cjm1}\includegraphics[scale=0.4]{figures/cjm1.png}} \subfloat[Second Database, time 1]{\label{fig:cjm2}\includegraphics[scale=0.4]{figures/cjm2.png}} \subfloat[Combined Database, time 0, 1]{\label{fig:cjall}\includegraphics[scale=0.4]{figures/cjall.png}} \caption{Example Input and Output Meshes for Conjoin} \end{figure} The values of the element status variable for each element at each timestep are shown below. A status value of 0 indicates that the element is active and a value of 1 indicates it is inactive. The nodes have a similar status variable. \begin{tabular}{l|ccccccc} \hline element & 1 & 2 & 3 & 4 & 5 & 6 & 7 \\ status at time 0 & 0 & 0 & 0 & 0 & 1 & 1 & 1 \\ status at time 1 & 1 & 1 & 1 & 0 & 0 & 0 & 0 \\ \hline \end{tabular} The output database will contain the variables that are defined on the first mesh. If later databases do not have those variables, then the data will be zero-filled for those timesteps. If later databases have additional variables, they will be ignored. \section{Invoking \conjoin} The minimal command line for executing \conjoin{} is: \begin{syntax} conjoin \{list of files to join\} \end{syntax} This would create an output mesh named \file{conjoin-out.e} containing the entities and data from the files listed on the command line. The files must be listed in order of increasing time step values. A nodal variable named \param{node\_status} and an element variable named \param{elem\_status} will be added to the variables already existing on the first file. The value of the status variables will be 0 to indicate an active node or element and 1 to indicate an inactive node or element. Several options are available to modify the default behavior of \conjoin{}. \subsection{Options} \renewcommand\arraystretch{1.5} \begin{longtable}{lp{4.0in}} \param{-help} & Print this summary and exit \\ \param{-output } & Name of the output file to create. The default output filename is \file{conjoin-out.e}. If the specified file already exists, it will be overwritten. \\ \param{-alive\_value } & Value (1 or 0) which will be used to indicate that an element is alive or active. The default behavior is that 0 indicates alive or active nodes and elements. \\ \param{-combine\_status\_variables } & The conjoin elem\_status variable will be combined with the specified status variable (val) existing on the mesh. Both variables must have the same value (1 or 0) to indicate that the element is alive or active. If 1 is alive, then the combined variable is the minimum of the two values. If 0 is alive, then the combined variable is the maximum of the two values. Use the \param{alive\_value} option to set conjoin's alive value \\ \param{-element\_status\_variable } & Element variable name to use as element existence status variable; it must not exist on input files. If specified as NONE, then it will not be written to the output file. Default = elem\_status \\ \param{-nodal\_status\_variable } & Nodal variable name to use as nodal status variable; it must not exist on input files. If specified as NONE, then it will not be written to the output file. Default = node\_status \\ \param{-omit\_nodesets} & Don't transfer nodesets to output file. \\ \param{-omit\_sidesets} & Don't transfer sidesets to output file. \\ \param{-gvar } & Comma-separated list of global variables to be joined or ALL or NONE. The default behavior is that all global variables will be written to the output file.\\ \param{-evar } & Comma-separated list of element variables to be joined or ALL or NONE. Variables can be limited to certain blocks by appending a colon followed by the block id. For example, \param{-evar sigxx:10:20} would result in the variable \param{sigxx} would be written for element blocks with id 10 and 20. The default behavior is that all element variables will be written to the output file. \\ \param{-nvar } & Comma-separated list of nodal variables to be joined or ALL or NONE. The default behavior is that all nodal variables will be written to the output file. \\ \param{-nsetvar } & Comma-separated list of nodeset variables to be joined or ALL or NONE. The default behavior is that all nodeset variables will be written to the output file.\\ \param{-ssetvar } & Comma-separated list of sideset variables to be joined or ALL or NONE. The default behavior is that all sideset variables will be written to the output file.\\ \param{-debug } & Debug level (values are or'd)\par \begin{tabular}{l@{ = }l} 1 & timing information.\\ 4 & Verbose Element block information.\\ 8 & Check consistent nodal coordinates between parts.\\ 16 & Verbose Sideset information.\\ 32 & Verbose Nodeset information.\\ 64 & put exodus library into verbose mode.\\ 128 & Check consistent global field values between parts. \\ \end{tabular}\\ \param{-width } & Width of output screen, default = 80 \\ \param{-version} & Print version and exit \\ \param{-copyright} & Show copyright and license data. \\ \end{longtable} When \conjoin{} is invoked, it will parse the user-specified options from the command line and it will also see if the environment variable \param{CONJOIN\_OPTIONS} exists. If the variable exists, then it will be parsed first followed by the parsing of the options on the command line. \section{Example} The output below shows the results of running the following command: \begin{syntax} conjoin -output adapt.e adaptBox.e* \end{syntax} The first section of the output shows the code version followed by some information showing the map from part number to filename. In this case there are 6 parts which will be joined. \begin{verbatim} conjoin (A code for sequentially appending Exodus II databases. Supersedes conex and conex2.) (Version: 1.2.1) Modified: 2011/01/12 Part 1: 'adaptBox.e' Part 2: 'adaptBox.e-s0002' Part 3: 'adaptBox.e-s0003' Part 4: 'adaptBox.e-s0004' Part 5: 'adaptBox.e-s0005' Part 6: 'adaptBox.e-s0006' \end{verbatim} \sectionline The next section of the output shows the output filename (\file{adapt.e} in this example), and gives a summary of the output mesh showing the entity counts and the variable summary. \begin{verbatim} Output: 'adapt.e' IO Word size is 8 bytes. Title: Default Sierra Title Number of coordinates per node = 3 Number of nodes = 151 Number of elements = 84 Number of element blocks = 1 Number of nodal point sets = 0 Number of element side sets = 2 Reading and Writing element connectivity & attributes Wrote coordinate names... Wrote coordinate information... Found 7 global variables. ExternalEnergy InternalEnergy KineticEnergy Momentum_x Momentum_y Momentum_z TIMESTEP Found 7 nodal variables. displ_x displ_y displ_z vel_x vel_y vel_z node_status Found 7 element variables. stress_xx stress_yy stress_zz stress_xy stress_yz stress_zx elem_status \end{verbatim} \sectionline The last section shows the progress of transferring the transient data to the output mesh. For each timestep, the output shows the part from which the data is being read and which timestep within that part is being used. It also show how many elements are active in that part and an estimate of how long it will take to finish transferring the data. Figures~\ref{fig:cjex1} to~\ref{fig:cjex4} show four views of the output mesh. \begin{verbatim} Step 1/11, time 0.0000e+00 (Part 1/6, step 1) Active Elem: 4 [ 9%, Elapsed=0.0s, ETA=0.0s] Step 2/11, time 5.0000e-01 (Part 1/6, step 2) Active Elem: 4 [ 18%, Elapsed=0.0s, ETA=0.0s] Step 3/11, time 1.0000e+00 (Part 2/6, step 1) Active Elem: 11 [ 27%, Elapsed=0.0s, ETA=0.0s] Step 4/11, time 1.2500e+00 (Part 3/6, step 1) Active Elem: 74 [ 36%, Elapsed=0.0s, ETA=0.0s] Step 5/11, time 1.5000e+00 (Part 3/6, step 2) Active Elem: 74 [ 45%, Elapsed= <1s, ETA= <1s] Step 6/11, time 1.7500e+00 (Part 4/6, step 1) Active Elem: 46 [ 55%, Elapsed= <1s, ETA= <1s] Step 7/11, time 2.0000e+00 (Part 4/6, step 2) Active Elem: 46 [ 64%, Elapsed= <1s, ETA= <1s] Step 8/11, time 2.5000e+00 (Part 4/6, step 3) Active Elem: 46 [ 73%, Elapsed= <1s, ETA= <1s] Step 9/11, time 3.0000e+00 (Part 5/6, step 1) Active Elem: 18 [ 82%, Elapsed= <1s, ETA= <1s] Step 10/11, time 3.5000e+00 (Part 6/6, step 1) Active Elem: 4 [ 91%, Elapsed= <1s, ETA= <1s] Step 11/11, time 4.0000e+00 (Part 6/6, step 2) Active Elem: 4 [100%, Elapsed= <1s, ETA=0.0s] ******* END ******* \end{verbatim} \begin{figure}[ht] \centering \subfloat[Time 0.0]{\label{fig:cjex1}\includegraphics[scale=0.25]{figures/cjex1s.png}} \subfloat[Time 1.0]{\label{fig:cjex2}\includegraphics[scale=0.25]{figures/cjex2s.png}}\\ \subfloat[Time 1.5]{\label{fig:cjex3}\includegraphics[scale=0.25]{figures/cjex3s.png}} \subfloat[Time 2.5]{\label{fig:cjex4}\includegraphics[scale=0.25]{figures/cjex4s.png}} \caption{Example Output Mesh from Conjoin} \end{figure} \section{Related Codes} \conjoin{} replaces the functionality of the \code{conex}\cite{bib:conex} code. \conjoin{} provides a superset of the \code{conex} functionality and is also much faster. \conjoin{} also supports nodeset and sideset variables and the naming of element blocks, nodesets, and sidesets which is not supported by \code{conex}. The input mesh databases to \code{Conex} are required to have the exact same bulk data which limits its use for adaptive analyses and other analyses which have varying numbers of active and inactive nodes and elements. \code{Conex} is no longer actively supported.