ExtractMPM

The ExtractMPM tool will extract data from NairnMPMarchive files and write them to text, binary or XML files. You can use your own visualization tools to work with this extracted data.

Compiling ExtractMPM

The first step is to compile the ExtractMPM command-line tool. When using MacOS X, you can compile ExtractMPM using that target in the project found at nairn-mpm-fea/Common/Projects/NairnMPM.xcodeproj. On any other system (or alternatively in MacOS X), you can compile using the command line

c++ -O3 -o ExtractMPM ExtractMPM.cpp

The -O3 options turns on optimization. You can change the -o path name as desired to install the executeable at any location.

Using Extract MPM

You run the ExtractMPM command line tool with

ExtractMPM [-hdDfFTXVsH23PC] [-b format] [-c format] [-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 are:

-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).

-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)

-T

Output as tab-delimited text file (extension .data). This option is the default output mode unless overridden by -d, -D, -f, -F, or -X option.

-X

Output an XML file, but see below for details. These files are intended for input to new calculations. (extension .xml).

-V

Output as a VTK Legacy file suitable for reading in visualization tools such as ParaView. The file will have only particle data, which may limit options in visualizations tools that need cell data. (extension .vtk). See <a href="#paraex">below</a> for example of plotting particle data in <a href="http://www.paraview.org">ParaView</a>.

-H

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

-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 <a href="../outformat/index.html#versionid">archive file's header</a>.

-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.

-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 <a href="../outformat/index.html#versionid">archive file's header</a>. See <a href="../outformat/index.html#mpmoutput">MPM output file format</a> information or <a href="../xmlformat/MPMHeader.html#mpmarchive">MPMArchiveOrder command</a> for details on the archive format. The format for a given file will be listed in the <a href="../outformat/index.html#mpmoutput">master text file</a> for that calculation result.

-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 <a href="../outformat/index.html#versionid">archive file's header</a>. See <a href="../outformat/index.html#mpmoutput">MPM output file format</a> information or <a href="../xmlformat/MPMHeader.html#crackarchive">CrackArchiveOrder command</a> for details on the crack archive format. The format for a given file will be listed in the <a href="../outformat/index.html#mpmoutput">master text file</a> for that calculation result.

-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.

-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, velz, and velz for component of velocity vector (in mm/sec)
• dispx, dispy, and dispz for component of displacement vector (in mm)
• sxx, syy, szz, sxy, sxz, and syz for a component 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)
• pexx, peyy, pezz, pexy, pexz, and peyz for a component of the plastic strain tensor (absolute)
• strerg for strain energy (in J)
• plerg for plastic energy (in J)
• temp for temperature (in K)
• conc for concentration (in wt %)

XML files always include mat and can include mass; they currently cannot include stress or strain.
    When exporting crack particle data, the output always includes the crack number followed by the crack particle position (x, y, and z (for 3D)), 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

XML files only include crack particle positions and the tip material ID (1 based) if available in the archive file; they currently cannot include J integral or stress intensity factors. Any requested particle or crack quantity not in the archive file will be output as zero.

-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 specifed 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 overide 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.

-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.

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.

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 <a href="../outformat/index.html#versionid">header</a> 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 <a href="../outformat/index.html#mpmoutput">MPM output file format</a> information for more details of 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 muultiple ver4 or newer files.

XML File Extractions

The use of XML file extractions is to restart NairnMPM calculations with particle results from a previous calculations. 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. Concentraation, 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 SYSTEM "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>

<a name="paraex"></a>Particle Plots in ParaView

To get started using <a href="http://www.paraview.org">ParaView</a> for particle plots, try the following example simulation and analysis:

1. Run the TwoSpheres.fmcmd example in nairn-mpm-fea/NairnMPM/input and save the results.
2. Use ExtractMPM on a file from the Results folder with the following command line:

   ExtractMPM -V -q sxx -q velx -q dispx -n Example -o TwoSpheres spheres.264
   

3. Download, install, and run <a href="htpp://www.paraview.org">ParaView</a>. Use it to open the TwoSpheres.vtk file created by the above extraction. Then:
   • Click "Apply" in the object inspector.
   • Click or use menu command to add Glyphs.
   • Select Glyph Type "Sphere."
   • Enter Radius = 1.25 (1/4 of the 5 mm cell size).
   • Scroll down, click to "Edit Scale" and edit it to be 1.
   • Click "Apply" to get the particle plot

You should have gotten a plot of two spheres in contact. You can explore all the <a href="http://www.paraview.org">ParaView</a> options for ways to visualize the results. You can color by any of the properties extracted to the file. If you extract multiple files and load them all into <a href="http://www.paraview.org">ParaView</a>, you can animate the results. When extracting results from multiple files in a single simulation, you should use the -s option to include step number in the file name. This method insures that <a href="http://www.paraview.org">ParaView</a> will read the files in the correct order.