The ExtractMPM tool will extract data from NairnMPM archive files and write them to text, binary or XML files. These extractions give you access to the data to enable use of alternative visualization tools or alternative software for interpreting the data.
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 executable at any location.
Using Extract MPM
You run the ExtractMPM command line tool 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:
- -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)
- 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)
- angz, angy, angx for rotation angles (in degrees) from material axes to current configuration (R = RzRyRx or use tranpose to rotate from current configuration to material axes; only Rz available for 2D results).
- 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 %)
- hist1, hist2, hist3, and hist4 for history variable 1 through 4
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 tt. Any requested particle or crack quantity not in the archive file will be output as zero.
- -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.
- 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.
- Specify to export crack particle data only. The selected quantities should be only crack particle properties.
- 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).
- 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
- Output as tab-delimited text file (extension .data). This option is the default output mode unless overridden by those below: -V, -X, -d, -D, -f, or -F.
- 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).
- Output an XML file, but see below for details. These files are intended for input to new calculations. (extension .xml).
- Output as little Endian binary file with double precision numbers (extension .data)
- Output as big Endian binary file with double precision numbers (extension .data)
- Output as little Endian binary file with single precision numbers or floats (extension .data)
- Output as big Endian binary file with single precision numbers or floats (extension .data)
- -H or -?
- Print synopsis of ExtractMPM with brief description of all options and variables.
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.
- Specify the archive file as one having 2D results. Because 2D results is the default assumption, this option is normally not needed.
- 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.
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.
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.