Archive File Formats

Finite element calculations using NairnFEA or material point method simulations using NairnMPM are written to one or more files. This page documents the format of those files. Normally you access these files with visualization tools that support their format. If needed, however, you can use information on this page to write your own tools to extract results from output files for analysis and plotting.

NairnFEA Output File

The results of FEA calculations are output to a single master text file. (usually with extension .fea). The text file defines the problem (lists the nodes, elements, materials, boundary conditions, etc.) and has tables of results (e.g., displacements, stresses, forces, energies, etc.). The contents of these text files are in plain English and should be self explanatory. Visualization software can parse these files to extract any needed information, which can be located by their sections.

The only unusual result is for imperfect interface elements. Since these elements are not solid elements, they cannot define all components of the stress tensor. Instead, there is only a traction vector normal to the interfacial surface. The normal component of the traction vector is output as sigma(xx) (or sigma(rr) for axisymmetric analyses). The tangential component of the traction vector is output as sigma(xy) (or sigma(rz) for axisymmetric analyses).

NairnMPM Output Files

The results of MPM calculations are output to a master text file and to a series of binary or text archive files.

Master Text File Format

A summary of all MPM calculations is written to a plain text file (usually with extension .mpm). The text file defines the problem (lists the nodes, elements, materials, initial cracks, boundary conditions, etc.), describes the archive file format, and has a list of all archived files. The nodes, elements, and boundary conditions may be in the text file or in separate text files along with the archive files. When in separate files, the master text file will list the path to the needed file. Whether the nodes, elements, and boundary conditions are in the text file or in separate files is determined by the Mesh command.

The contents of these text files are in plain English and should be self explanatory. Visualization software can parse these files to extract any needed information, which can be located by their sections.

Binary Archive File Format

The binary archive files will have information about the state of each material point. If there are cracks, the archive files will also include the current crack locations and calculated crack fracture parameters. The information written to the archive files and the frequency for storing archived results are determined by the MPM Archiving Options.

The "ARCHIVED ANALYSIS RESULTS" section of the master text file will begin with lines that define the location and format of the binary archive files. Some typical information is:

Root file name: results/root.
Archive format: mYYYYNYYYNYYNNNNY
Crack archive format: mYYYN

The first line is the relative path name from the master text file to the archive files. In the above example, the archive files will be stored as results/root.# where # is the step number when the archive file was written. The "Archive format" defines the information archived for each material point. The "Crack archive format" defines the information archived for each crack point. The following sections defines the format of the binary archive files.

Archive File Header

The first 4 bytes of a binary archive file has the archive version ID as 4 characters. The current archive versions are:

none, ver1, ver2

These are old formats that are no longer supported and therefore no longer documented. (Note: if the master text file does not provide the archive and crack formats, it is certain those archive files have one of these old formats).

ver3

These files have their format specified in the master text file (as listed above).

ver4

This format began at the end of NairnMPM 6.4.0 (October 2007). The difference from ver3 is that the file includes a 64 byte header that includes information about the archive file format right in the file. The header information is

Bytes 1-4: the version ID or ver4
Byte 5: number of characters in the archive format (A)
Byte 6 to (5+A): the archive format string
Byte (6+A): number of characters in the crack archive format (C)
Byte (7+A) to (6+A+C): the crack archive format
Byte (7+A+C): '2' or '3' for 2D or 3D analysis results
Byte (8+A+C) to 64: 0 bytes to fill out the header.

The archive format information is still included in the master text file. In fact, if the text file and the archive file have different formats, it means that archive file does not belong to those results, which can be used as optional verification of file data.

ver5

This format began in NairnMPM 6.7.0 (December 2008). It tacks on 5 more bytes of header information, still within a 64 byte header. The header information is

Bytes (8+A+C): '1' if analysis used structured grid (i.e., grid created with the GRID command); '0' otherwise.
Byte (9+A+C) to (12+A+C): current time in ms (float using Endian style from the archive format).
Byte (13+A+C) to 64: 0 bytes to fill out the header.

ver6

The format began in NairnMPM 7.2.2 (January 2010). It did not change the header, but added an extra double in the default properties for 3D calculations to track all three rotation angles.

After the file's 4 or 64-byte header, the remainder of the file is a series of records with archived results for each material point and each crack particle. Programs that read archive files must read the archive and crack formats (either from the master text file or from the ver4 file header) and support all Y and N options. If the number of characters in the specified format is less than the total number documented below, all extra characters are assumed to be N. In other words the binary achived file is assumed to be older, but backward compatible with this docmentation. The following sections give the details.

Byte Order Character

The first character in each format string is either m or i to indicate the archive file byte order follows old Macintosh chip methods or Intel chip methods. In pre-Intel Macintosh computers, bytes are stored from most significant to least significant byte. for example, the 4-byte integer representation for the number 1 (in hexadecimal) would be 0x00000001. In contrast, the same number on an Intel chip would be 0x01000000. Similarly, both Macintosh and Intel use IEEE methods for 8-byte double precision numbers, but the physical storage of bytes are in the opposite order.

If the byte order of the computer being used to read the archive files matches the byte order character, the files can be read as ordinary binary files. If the computer and the byte order character differ, the bytes for each element of the archived file have to be reversed as they are read.

Record Size

The information for each particle and each crack segment are stored as a series of binary records. All records are exactly the same size. The size is calculated from the sum of sizes required to store the information listed in the format strings. The following sizes assume doubles are 8 bytes, ints are 4 bytes (true on both 32 bit and 64 bit processors), and shorts are 2 bytes. Any byte with setting N will store no bytes. The following lists specify the number of bytes for setting Y. The numbers of bytes differ for 2D analyses vs. 3D analysis.

Archive Order Byte Requirements (2D Analyses)

Byte 2: 64 (cannot be N and O means old format which is no longer supported)
Byte 3: 16
Byte 4: 32
Byte 5: 32
Byte 6: 32
Byte 7: 0 (it must be N for all ver3 or newer files; a Y means an unsupported or invalid archive format)
Byte 8: 8
Byte 9: 8
Byte 10: 8
Byte 11: 0 (it must be N for all ver3 or newer files; a Y means an unsupported or invalid archive format)
Byte 12: 16
Byte 13: 8
Byte 14: 8 for 'Y', but 0, 8, 16, 24, or 32 (for other settings)
Byte 15: 24
Byte 16: 8
Byte 17: 4
Byte 18: 8

Archive Order Byte Requirements (3D Analyses)

Byte 2: 80 (ver5 or older) or 88 (ver6 or newer) (cannot be N)
Byte 3: 24
Byte 4: 48
Byte 5: 48
Byte 6: 48
Byte 7: 0 (it must be N for all 3D archives)
Byte 8: 8
Byte 9: 8
Byte 10: 8
Byte 11: 0 (it must be N for all 3D archives)
Byte 12: 0 (it must be N for all 3D archives)
Byte 13: 8
Byte 14: 8 for 'Y', but 0, 8, 16, 24, or 32 (for other settings)
Byte 15: 32
Byte 16: 8
Byte 17: 4
Byte 18: 24

Crack Archive Order Byte Requirements (2D Analyses)

Byte 2: 88 (cannot be N and O means old format not longer supported)
Byte 3: 16
Byte 4: 16
Byte 5: 20

Crack Archive Order Byte Requirements (3D Analyses)

3D calculations currently do not allow cracks.

Record Size in Archive File

The record size used in the file is the maximum of the archive order and crack archive order requirements for the dimensionailty of the analysis. Typically the crack archive will require less bytes than material point archive, but its record will still be the same size as the material point archive.

Material Points Archive Format

The following items may be archived for each material point. This section lists the quantity that is archived and its units in the archive file. The data appear in each record in the following order, but each item only appears if the archive setting for that byte is Y.

Byte 2: Default Properties

This setting must be Y. A setting of O is means an old archive format that is no longer supported. The default properties are:

int inElem - element number containing the material point
double mp - mass (g)
short matnum - material number
short unused - not used
double anglez - material angle (for anisotropic materials) (degrees)
2D any version or 3D in ver5 or older has:
   double thickness - thickness (mm) (or 0 in 3D)
3D in ver6 or newer replaces thickness with two more angles:
   double angley - material angle (for anisotropic materials) (degrees)
   double anglex - material angle (for anisotropic materials) (degrees)
double x - current x position (mm)
double y - current y position (mm)
double z - current z position (mm) (3D only)
double origx - original x position (mm)
double origy - original y position (mm)
double origy - original z position (mm) (3D only)

Byte 3: Particle velocity

Setting Y stores components of particle velocity:

double velx - x direction velocity (mm/sec)
double vely - y direction velocity (mm/sec)
double vely - z direction velocity (mm/sec) (3D only)

Byte 4: Particle stress

Setting Y stores components of particle stress:

double stressxx - x direction normal stress (Pa)
double stressyy - y direction normal stress (Pa)
double stresszz - z direction normal stress (Pa)
double stressxy - x-y plane shear stress (Pa)
double stressxz - x-z plane shear stress (Pa) (3D only)
double stressyz - y-z plane shear stress (Pa) (3D only)

Byte 5: Particle strain

Setting Y stores components of particle strain, which is elastic strain for plasticity materials:

double strainxx - x direction normal strain (dimensionless)
double strainyy - y direction normal strain (dimensionless)
double strainzz - z direction normal strain (dimensionless)
double strainxy - x-y plane shear strain (dimensionless)
double strainxz - x-z plane shear strain (dimensionless) (3D only)
double strainyz - y-z plane shear strain (dimensionless) (3D only)

Byte 6: Particle plastic strain

Setting Y stores components of particle plastic strain:

double plstrainxx - x direction plastic normal strain (dimensionless)
double plstrainyy - y direction plastic normal strain (dimensionless)
double plstrainzz - z direction plastic normal strain (dimensionless)
double plstrainxy - x-y plane plastic shear strain (dimensionless)
double plstrainxz - x-z plane plastic shear strain (dimensionless) (3D only)
double plstrainyz - y-z plane plastic shear strain (dimensionless) (3D only)

Byte 7: Original Position

This setting should always be N otherwise the archive file has an unsupported or invalid format.

Byte 8: Particle external work

Setting Y stores total external work (which is only non-zero if the material point had an applied external force):

double extwork - cumulative external work (J)

Byte 9: Particle temperature

Setting Y stores particle temperature:

double temperature - temperature difference (Celsius)

Byte 10: Particle plastic energy

Setting Y stores particle plastic energy:

double plastEnergy - cumulative plastic energy (J)

Byte 11: Future Expansion

This setting should always be N otherwise the archive file has an unsupported or invalid format.

Byte 12: Particle total shear strain components (du/dy and dv/dx)

Setting Y stores two components of total strain gradient that combine to give total x-y shear strain. Only useful in 2D analysis and can get same information by archiving rotational strain instead:

double dudy - Strain gradient term du/dy (dimensionless)
double dvdx - Strain gradient term dv/dx (dimensionless)

Byte 13: Particle strain energy

Setting Y stores particle strain energy:

double strainEnergy - cumulative strain energy (J)

Byte 14: Particle history variable 1

Up to four history variables may be stored. A setting of 'N' stores none; a setting of 'Y' stores history variable 1; character '1' to '9', ':' , ';', '<', '=', '>', and '?' store various combinations of history variables 1 to 4 (the stored variables are determined by a bit-wise check on the four least-significant bits of the ASCII value of the setting minus ASCII for '0' = 0x30, see here for specifics). The meaning and units are determined by the material and all are doubles:

double history1 - particle history information
double history2 - particle history information
double history3 - particle history information
double history4 - particle history information

Byte 15: Particle concentration and concentration gradient

Setting Y stores particle concentration and concentration gradient. These values will only be non-zero when diffusions calculations are activated:

double concentration - particle concentration
double dcdx - particle concentration gradient (dc/dx)
double dcdy - particle concentration gradient (dc/dy)
double dcdz - particle concentration gradient (dc/dz) (3D only)

Byte 16: Particle thermal energy

Setting Y stores approximate energy to to temperature change:

double thermalEnergy - cumulative thermal energy (J)

Byte 17: Element crossings

Setting Y stores number of times this particle has crossed element boundaries:

int elemCrossings - cumulative element crossing

Byte 18: Rotational strain

Setting Y stores initial material angle(s). The evolving angles are always stored in the material angle properties:

double anglez0 - initial material angle z (degrees)
double angley0 - initial material angle y (degrees) (3D Only)
double anglex0 - initial material angle x (degrees) (3D Only)

The rotational engineering strains are ω_xy = -π*(anglez-anglez0)/90, ω_xz = π*(angley-angley0)/90, and ω_yz = -π*(anglex-anglex0)/90, which are twice the tensorial rotational strains.

Crack Archive Format

The following items may be archived for each crack point. This section lists the quantity that is archived and the units for that item. Crack archives are currently only in 2D analyses. The data appear in each record in the following order, but each item only appears if the archive setting for that byte is Y.

Byte 2: Default Properties

This setting must be Y or O. A setting of O means an old archive format that is no longer supported. The default parameters that are archived as crack point properties are:

int inElem - element number containing the crack point
int tipMatnum - crack tip material ID (1 based) or -1 for no material or -2 for exterior crack tip
spacer - for alignment with material point records, unused bytes (count = sizeof(double)-sizeof(int))
short marker - -1 for first point in crack, -2 for other points
short tractionMat - traction law material number (<=0 for no tractional law)
double x - current x position (mm)
double y - current y position (mm)
double origx - original x position (mm)
double origy - original y position (mm)
int inElemAbove - element number containing the crack top surface point
double xAbove - current x position of crack top surface (mm)
double yAbove - current y position of crack top surface (mm)
int inElemBelow - element number containing the crack bottom surface point
double xBelow - current x position of crack bottom surface (mm)
double yBelow - current y position of crack bottom surface (mm)

Byte 3: J Integral

Setting Y stores two components of J Integral:

double J1 - J Integral or energy release rate (J/m^2)
double J2 - Second component of J Integral calculation (J/m^2) (when no crack propagation)
              or the actual J released (J/m^2) the last time the crack propagated
              (when propagation is activated)

Byte 4: Stress Intensity Factor

Setting Y stores two components of stress intensity factor:

double KI - Mode I stress intensity factor (MPa sqrt(m))
double KII - Mode II stress intensity factor (MPa sqrt(m))

Byte 5: Dynamic Energy Balance Results

Setting Y stores information about crack growth using criterion 3:

int counter - count of crack increments
double released - energy released (J/m^2)
double absorbed - energy absorbed (J/m^2)