ExtractMPM

ExtractMPM Tool

The main visualization tools (NairnFEAMPM and NairnFEAMPMViz) have many visualization options, but may not have what you need. For 3D visualization, the options are more limited and NairnFEAMPMViz has very few options for visualizing 3D results. The purpose of the ExtractMPM tool is to read NairnMPM binary archive files, extract selected results, and write them to text, binary or XML files. These new files can serve as input to alternative visualization tools or alternative software for interpreting the data.

Compiling ExtractMPM

The first step is to compile the ExtractMPM command-line tool. On MacOS X or Windows, you can compile ExtractMPM using its target in the XCode or Visual Studio projects found in the nairn-mpm-fea/Common/Projects folder. On any other system (or alternatively in MacOS X), you can compile by changing directory to the nairn-mpm-fea/NairnMPM/tools directory and use the command

make ExtractMPM SYSTEM=(system)

where (system) defines the system being used. This option mainly picks path to the c++ compiler on your computer. For unsupported systems, you can manually set the path to that compiler using

make ExtractMPM CC=/usr/local/gcc48/bin/g++

Other options that can be passed to the make command are

CFLAGS - options passed to compiler (default: -c -O3)
LFLAGS - options during linking step (default: none)

Other make functions are:

make
make clean
make install

A make by itself will compile all tools (and not just ExtractMPM). The clean option will delete compiled objects and executables for all tools. The install option will copy all compiled tool executables to an install folder. The default install location is ~/bin but that can be changing by adding ioutput=(new folder) to the make command.

Using Extract MPM

ExtractMPM is most conveniently run by using the "Export Particle VTKs" options in NairnFEAMPM or in NairnFEAMPMViz. Alternative, you can run the ExtractMPM directly on a command line with

ExtractMPM [-hdDfFTXVsHPC] [-m num] [-M num] [-q data] [-n text] [-o path] archive0 archive1 ...

ExtractMPM reads the NairnMPM binary archive files in archive0, archive1, etc., extracts the data selected by the options, and outputs it all to standard output or to file(s) specified in the options.The flags and their descriptions, group by subject, are:

Exported Data

-q data

When exporting particle data, the output always includes particle position (x, y, and z (for 3D)), but can include additional data for each -q option. The allowed quantities for particle data are:

mat for material number
mass for particle mass (in g)
velx, vely, and velz for component of velocity vector (in mm/sec)
velocity for all three components of velocity. For VTK files, they will be output as a vector quantity (in mm/sec)
dispx, dispy, and dispz for component of displacement vector (in mm)
displacement for all three components of displacement. For VTK files, they will be output as a vector quantity (in mm)
sxx, syy, szz, sxy, sxz, and syz for a component of the stress tensor (in Pa)
stress for all 6 components of the stress tensor. For VTK files, they will be output as a tensor quantity with 9 elements of the stress tensor (in Pa)
pressure for pressure (in Pa)
vonmises for von Mises (or equivalent) stress (= sqrt(3 J2)) (in Pa)
exx, eyy, ezz, exy, exz, and eyz for a component of the strain tensor, which is elastic strain for plasticity materials (absolute)
strain for all 6 components of the strain tensor. For VTK files, they will be output as a tensor quantity with 9 elements of the strain tensor (absolute)
pexx, peyy, pezz, pexy, pexz, and peyz for a component of the plastic strain tensor (absolute)
plasticstrain for all 6 components of the plastic strain tensor. For VTK files, they will be output as a tensor quantity with 9 elements of the plastic strain tensor (absolute). But note that not all materials store plastic strain the archive files. For example, Hyperelastic-Plastic_Materials store the elastic, left-Cauchy green strain. This quantity will extract the values stored in the archive.
angz, angy, angx for rotation angles (in degrees) from material axes to current configuration (R = R_zR_yR_x or use transpose to rotate from current configuration to material axes; only R_z available for 2D results).
xmat, ymat, zmat for unit vectors in the material x, y, or z axes, which may rotate during a simulations (material axes for isotropic materials start aligned with the grid). Plotting glyphs oriented by these vectors can be used to visualization material directions in ParaView (and sometimes helps other visualizations too).
equivstrain for equivalent strain (= sqrt(2/3)|s| where s is deviatoric strain tensor from elastic strain only) (absolute)
strerg for strain energy (in J)
work for work energy (in J)
heat for heat energy (in J)
plerg for plastic energy (in J)
temp for temperature (in K)
conc for concentration (in wt %)
hist# for history variable where # can be from 1 to 19

XML file output always includes mat and can include mass; they currently cannot include stress or strain.
When exporting crack particle data (-C option), the output always includes crack position and the crack number, but can include additional data for each -q option. The allowed quantities for crack particle data are:

J1 and J2 for crack tip J integral terms
KI and KII for crack tip stress intensity factors
czm1 and czm2 for dissipated mode I or mode II energy per unit area of a crack particle with a cohesive zone
tract# for traction history variable where # can be from 1 to 10

XML file output only includes crack particle positions and the tip material ID (1 based) if available in the archive file; they currently cannot include these extra crack archived properties.
Any requested particle or crack quantity not in the archive file will be output as zero. Entering an invalid quantity name will cause an error.

-m num

Omit data for particles with material number num. More than one use can remove multiple material types.

-M num

Include data for particles with material number num. More than one use can include multiple material types. If no -M options are used, then all materials are included. A material that is both included and excluded, will be excluded.

-P

Specify to export particle data only. Because particle data export is the default assumption, this option is normally not needed. The selected quantities should be only particle properties.

-C

Specify to export crack particle data only. The selected quantities should be only crack particle properties.

-h

Include a header at the beginning of the file. The header has text that describes the content of the file. Each line begins with a key word. The text after the space is the setting for that keyword. The possible keywords are

Name - optional text if the -n options is used
Source - name of the input archive file
Data - space delimited list of columns in the output
Included_Materials - space delimited list of included materials
Excluded_Materials - space delimited list of omitted materials
Format - format of the output numbers (text, xml, double, float)
Endian - for binary output will be little or big.
EndHeader - last line of the header

The header ends with the line feed character (0x0A) after EndHeader. For binary files, the header is padded to be a multiple of 8 bytes long. For VTK Legacy files, the name (if provided) and source will always be output on the second line of the file (i.e, the -h option is not needed).

-n text

The text defines a title or any brief comment about the extracted file. It is output in the header, but only if the -h option is used. For text with spaces, include it in quotes. For VTK Lagacy files it is output on the second line of the file.

Exported File Name

-o path: The output will be to standard output unless an output file path is specified in this option. The output file should not include an extension because one will be generated automatically based on the selected file type. When multiple archive files are extracted in a single command, the output files will add an index number to this specified output file name for each additional file (unless this default index number is overridden by the -s option).
-s: Include the step number in the output file name. NairnMPM archive files should have the step number as an extension. For example, if you are extracting data to a text file with root name ParticleData from archive file named archive.323 while using the -s option, the extracted file name will be ParticleData_323.txt. When extracting multiple files, inclusion of a step number will override the default index number (see -o option). If two of the multiple files have the same step number, the second one will overwrite the first. This problem will never occur when extracting from multiple files resulting from a single simulation.

Exported File Format

-T: Output as tab-delimited text file (extension .data). This option is the default output mode unless overridden by those below: -V, -U, -X, -d, -D, -f, or -F.
-V: These both out as a VTK Legacy file suitable for reading in visualization tools such as ParaView or VisIt. The file can have particle data or only crack data (with the -C option). Note the separate particle data and crack data files can be opened simultaneously in ParaView or VisIt to view them together (or to toggle or the other off for clarity) (extension .vtk). Particle data will export as a POLYDATA style VTK file (which limits visualization to point-based methods). Crack data, however, will export as an UNSTRUCTURED_GRID style VTK file (but, if 3D cracks cannot access the facet information, they will also export and a POLYDATA style VTK file).
-U: This option is identical to -V except will export particle data as an UNSTRUCTURED_GRID style VTK file. Each material point will be a cell in the VTK data and the cell will be deformed to match the current deformation of that particles. This type of file improves quality of the visualization. The two drawbacks are 1. you cannot use this option unless the simulation archived both strain and size, which are needed to deform the particle; 2. the files are much larger, but it appears visualization features in ParaView and VisIt are somewhat faster. This option can be used for crack data, but is equivalent to a crack export with -U.
-X: Output an XML file, but see below for details. These files are intended for input to new calculations (extension .xml).
-d: Output as little Endian binary file with double precision numbers (extension .data)
-D: Output as big Endian binary file with double precision numbers (extension .data)
-f: Output as little Endian binary file with single precision numbers or floats (extension .data)
-F: Output as big Endian binary file with single precision numbers or floats (extension .data)
-Z: Output as a custom binary file, which if not of general use and cannot export crack data (extension .xyz)

Other Commands

-H: Print synopsis of ExtractMPM with brief description of all options and variables.

Deprecated Commands

The following commands are only needed for very old archive files. They can be ignored for all result archive files.

-b format: Specify the archive format of the file. Only needed for ver3 archive files. For ver4 archive files or newer it is overridden by the file format specified in the archive file's header. See MPM output file format information for more details.
-c format: Specify the crack archive format of the file. Only needed for ver3 archive files. For ver4 archive files or newer it is overridden by the file format specified in the archive file's header. See MPM output file format information for more details.
-2: Specify the archive file as one having 2D results. Because 2D results is the default assumption, this option is normally not needed.
-3: Specify the archive file as one having 3D results. Only needed for ver3 archive files. For ver4 archive files or newer it is overridden by the file format specified in the archive file's header.

Examples

The following examples are shown as given to the shell:

ExtractMPM -h -o positions arch.57: Output particle positions from a ver4 or newer archive file (arch.57) to the text file named positions.txt with a header at the beginning of the file.
ExtractMPM -d -b iYYYYNNNNNNNYNNNN -q syy -q szz -o str disks.78: Output particle positions and y- and z-direction normal stress from a ver4 or newer archive file (disks.78) to a little Endian file of double named str.data.
ExtractMPM -hF -q sxx -M 1 -o strxx disks.*: Output particle positions and x-direction normal stress from several ver4 archive files (disks.*) to a series big Endian files of floats named strxx.data, strxx_1.data, etc., including headers. The output file will include only data from particles for material number 1. The header will help determine which output file came from which archive file.
ExtractMPM -hC -o cracks disks.1289: Output crack number and crack particle particle positions from a ver4 archive file to a text file cracks.txt including a header. The output file will include only crack particle data.
ExtractMPM -V -q sxx -q velx -q dispx -s -o Output archive.*: Extract data for all "archive.#" files in the current folder and write to VTK file with name "Output_#.vtk". These output files can be read by ParaView for an alternate method of generating particle based plots for any extracted quantity.

You only need to specify file formats (in -b and -c options) and dimensionality (in -3 option) for ver3 archive files. These options will be read from the header of ver4 or newer files. The version ID of any archive file can be determined by looking at the first 4 bytes of the file. The ver4 or newer format took effect 25 OCT 2007. See MPM output file format information for more details on archive file versions.

Since the archive file format is specified in the command, when extracting from multiple ver3 archive files in a single command, they must all have the same format. This restriction does not apply when extracting from multiple ver4 or newer files.

XML File Extraction To Extend Calculations

The main use of XML file extractions is to restart NairnMPM calculations with particle results from a previous calculation. As a result, the XML file uses a format intended for defining material points in a NairnMPM input commands file. All material points will be in a single <PointList> structure. Each material point in the structure will have the following format:

<PointList>
     . . .
   <mp matl='1' angle='0' thick='1' wtconc='0' temp='0'>
     <pt units='mm' x='1.25' y='-11.25'/>
     <vel units='mm/sec' x='0' y='0'/>
     <mass m='1e-3'/>
   </mp>
       . . .
</PointList>

The material number (matl), material angle (angle, if 2D), thickness (thick, if 2D), and position (pt element) will always be in the extracted file. To include concentration (wtconc) and/or temperature (temp), use the -q conc and -q temp options, respectively. To include the velocity use the -q velx option (which will include all components of velocity). To include mass (and you normally should) use a -q mass option. Concentration, temperature, and velocity will only appear if they are in the archive file. All other requested quantities (including other components of velocity) will be ignored.

If you only want certain types of material points in the new calculations, use the -m or -M options to select the desired material types. You can include a header with the -h option and it will appear at the beginning of the file in an XML comment structure.

Finally, you can use the extracted XML file to define all or some of the material points in a new calculation. First, define the path to the new file in an ENTITY element in the file's DOCTYPE element such as:

<!DOCTYPE JANFEAInput SYSTEM '/full path to/NairnMPM.dtd'
[
  <!ENTITY mpfile "path to/pointlist.xml">
]>

where pointlist.xml is the name of the newly extracted XML file. Then, import that file in the <MaterialPoints> element such as:

<MaterialPoints>
   &mpfile;
</MaterialPoints>

In scripted files, the above can be done Entity and XMLData commands.