\chapter{EJoin}\label{ch:ejoin} \section{Introduction} \ejoin{} is used to join 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. Elements are never combined even if all of the nodes on two elements are combined, the output file would have two elements with identical connectivity which is usually not desired. \end{itemize} If any of the input databases have timesteps, then the timestep values and counts must match on all databases with timesteps. \section{Invoking \ejoin} The minimal command line for executing \ejoin{} is: \begin{syntax} ejoin \{list of files to join\} \end{syntax} This would create an output mesh named \file{ejoin-out.e} containing the entities and data from the files listed on the command line. Several options are available to modify the default behavior of \ejoin{}. In the description of the options, there is the concept of a ``part'' which is simply the mesh from an input file. The parts are numbered sequentially starting at 1. \subsection{Options} \renewcommand\arraystretch{1.5} \begin{longtable}{lp{4.0in}} \param{-help} & Print this summary and exit \\ \param{-version} & Print version and exit \\ \param{-output } & Name of the output file to create. The default output filename is \file{ejoin-out.e}. If the specified file already exists, it will be overwritten. \\ \param{-omit\_blocks } & Omit the specified part/block pairs. The specification is \param{p\#:block\_id1:block\_id2,p\#:block\_id1}. For example, to omit block ids 1,3,4 from part 1; block ids 2,3,4 from part 2; and block 8 from part5, specify \param{-omit\_blocks p1:1:3:4,p2:2:3:4,p5:8}. \\ \param{-omit\_nodesets [val]} & If no value, then don't transfer any nodesets to the output file. If just \param{p\#,p\#,...} specified, then omit nodesets on the specified parts. If \param{p\#:id1:id2,p\#:id2,id4...} then omit the nodesets with the specified id in the specified parts. \\ \param{-omit\_sidesets [val]} & If no value, then don't transfer any sidesets to the output file. If just \param{p\#,p\#,...} specified, then omit sidesets on specified parts If \param{p\#:id1:id2,p\#:id2,id4...} then omit the sidesets with the specified id in the specified parts. \\ \param{-convert\_nodal\_to\_nodesets } & For each part listed (or \param{ALL}), create a nodeset containing the nodes of that part and output the nodal fields from that part as nodeset fields instead of nodal fields. Format is comma-separated list of parts (1-based), or \param{ALL} \\ \param{-match\_node\_ids} & Combine nodes if their global ids match. This option can not be specified if \param{-match\_node\_coordinates} is specified.\\ \param{-match\_node\_coordinates} & Combine nodes if they are within tolerance distance of each other. The \param{-tolerance } option is used to set the matching tolerance. This option can not be specified if \param{-match\_node\_ids} is specified.\\ \param{-tolerance } & Maximum distance between two nodes to be considered colocated. The default tolerance is calculated as 0.001 times the sum of the X, Y, and Z extents of the bounding box containing the overlapping regions of the bounding boxes of the two meshes being compared. This option is only meaningful if \param{-match\_node\_coordinates} is specified. \\ \param{-offset } & Comma-separated x,y,z offset for the nodal coordinates of all parts except for part 1\footnote{This option is planned to be changed in the future to allow specifying a different offset for each part including part 1. It is unknown at this time when this will be implemented or what the syntax will be.}. \\ \param{-steps } & Specify subset of timesteps to transfer to output file. Format is \param{beg:end:step}. For example, the input \param{-steps 1:10:2} would result in steps 1, 3, 5, 7, and 9 being transferred to the output file. To only transfer last step, use \param{-steps LAST} \\ \param{-gvar } & Comma-separated list of global variables to be joined or \param{ALL} or \param{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 \param{ALL} or \param{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 \param{ALL} or \param{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 \param{ALL} or \param{NONE}. Variables can be limited to certain sets by appending a colon followed by the nodeset id. E.g. -nsetvar temperature:10:20. 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 \param{ALL} or \param{NONE}. Variables can be limited to certain sets by appending a colon followed by the nodeset id. E.g. -ssetvar sigxx:10:20. The default behavior is that all sideset variables will be written to the output file.\\ \param{-disable\_field\_recognition} & Do not try to combine scalar fields into higher-order fields such as vectors or tensors based on the field suffix. \\ \param{-copyright} & Show copyright and license data. \\ \end{longtable} When \ejoin{} is invoked, it will parse the user-specified options from the command line and it will also see if the environment variable \param{EJOIN\_OPTIONS} exists. If the variable exists, then it will be parsed first followed by the parsing of the options on the command line. \section{Examples} The output below shows the results of a sample run of ejoin. In this example, there are three springs (drive, gate, and shutter) which have been prestressed in three separate analyses. The results data for these analyses are in the \file{*.rs} files. The analyst wants to join these prestress outputs back into the original mesh and then perform another analysis using the prestressed springs. The spring element blocks have ids 1, 2, and 3. Each of the individual spring prestress runs have 3 element blocks -- a spring and two spring attachment points. To create the final model, the following steps need to be done: \begin{itemize} \item Remove the spring element blocks from the original mesh database (\file{assembly.g}) \item Remove the spring attachment points from each prestressed spring model. \begin{itemize} \item Blocks 14 and 21 in the drive spring (part 2), \item Blocks 17 and 31 in the gate spring (part 3), and \item Blocks 72 and 61 in the shutter spring (part 4). \end{itemize} \item Join the remaining blocks into a single model including the results data from only the last timestep of the spring models. \end{itemize} These steps are accomplished using the following syntax: \begin{syntax} ejoin -omit_blocks p1:1:2:3,p2:14:21,p3:17:31,p4:72:61 -steps LAST -output assembly_final.g assembly.g drive.rs gate.rs shutter.rs \end{syntax} The output from executing this command is: \begin{verbatim} EJoin (A code for merging Exodus II databases; with or without results data.) (Version: 1.2.7) Modified: 2011/02/09 *** 50503 Nodes were merged/omitted. Wrote step 1/1, time 3.6000e-02 Database: assembly_final.g Number of coordinates per node = 3 Number of nodes = 274723 Number of elements = 220160 Number of element blocks = 25 Number of nodal point sets = 27 Number of element side sets = 4 Number of global variables = 128 Number of variables at each node = 42 Number of variables at each element = 34 Number of variables at each nodeset = 0 Number of variables at each sideset = 0 Number of time steps on the database = 1 ******* END ******* \end{verbatim} \section{Related Codes} \ejoin{} provides some, but not all, of the functionality of the \code{gjoin}~\cite{bib:gjoin} code. The main differences are: \begin{itemize} \item \code{gjoin} does not handle transient results data on the input databases. \item \code{gjoin} can combine element blocks from multiple input databases into a single element block. Similarly for nodesets and sidesets. \item \code{gjoin} can independently rotate, scale, and offset each input database; \ejoin{} can currently only offset the second and subsequent parts by the same value; however, it is planned to add additional part transformation (offset, scale, rotation) options to \ejoin{} in the future. \item \code{gjoin} tends to use memory inefficiently which can limit the size of database that it can generate; \ejoin{} should use memory more efficiently and allow the generation of much larger models. \end{itemize}