Difference between revisions of "Archive File Formats"

Latest revision as of 13:53, 26 January 2023

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: mYYYYNYYYNYYNNNNYNNYNNNN
Crack archive format: mYYYNNNN

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 alt time units (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 analyses.

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
Byte 19: 16
Byte 20: 8
Byte 21: 8
Byte 22: 8 for 'Y', but 0, 8, 16, 24, 32, or 40 (for other settings)
Byte 23: 8 for 'Y', but 0, 8, 16, 24, 32, or 40 (for other settings)
Byte 24: 8 for 'Y', but 0, 8, 16, 24, 32, or 40 (for other settings)
Byte 25: 16 for 2D, 24 for 3D

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
Byte 19: 24
Byte 20: 24
Byte 21: 24
Byte 22: 8 for 'Y', but 0, 8, 16, 24, 32, or 40 (for other settings)
Byte 23: 8 for 'Y', but 0, 8, 16, 24, 32, or 40 (for other settings)
Byte 24: 8 for 'Y', but 0, 8, 16, 24, 32, or 40 (for other settings)

Crack Archive Order Byte Requirements (2D Analyses)

Byte 2: 88 (2D) or 120 (3D) (cannot be N and O means old format which is no longer supported)
Byte 3: 16
Byte 4: 16
Byte 5: 20
Byte 6: 8 for 'Y', but 0, 8, 16, 24, 32, or 40 (for other settings)
Byte 7: 8 for 'Y', but 0, 8, 16, 24, 32, or 40 (for other settings)

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. Refer to units table for details an any units.

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 - small-strain material angle (degrees) (for rotational strain and deformation gradient)
2D any version or 3D in ver5 or older has:
   double thickness - thickness (length units) (or 0 in 3D)
3D in ver6 or newer replaces thickness with two more angles:
   double angley - small-strain material angle (degrees) (for rotational strain and deformation gradient)
   double anglex - small-strain material angle (degrees) (for rotational strain and deformation gradient)
double x - current x position (length units)
double y - current y position (length units)
double z - current z position (length units) (3D only)
double origx - original x position (length units)
double origy - original y position (length units)
double origy - original z position (length units) (3D only)

Byte 3: Particle velocity

Setting Y stores components of particle velocity:

double velx - x direction velocity (velocity units)
double vely - y direction velocity (velocity units)
double vely - z direction velocity (velocity units) (3D only)

Byte 4: Particle stress

Setting Y stores components of particle stress:

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

Byte 5: Particle strain

Setting Y stores components of particle strain, which is elastic strain for plasticity materials, but it total strain for most hyperelastic 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 engineering plane shear strain (dimensionless)
double strainxz - x-z engineering plane shear strain (dimensionless) (3D only)
double strainyz - y-z engineering plane shear strain (dimensionless) (3D only)

Byte 6: Particle plastic strain (alternate strain for some materials)

Setting Y stores components of particle plastic strain for plasticity materials, but stores left Cauchy Green strain tensor for most hyperelastic materials:

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 engineering plane plastic shear strain (dimensionless)
double plstrainxz - x-z engineering plane plastic shear strain (dimensionless) (3D only)
double plstrainyz - y-z engineering 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 work energy

Setting Y stores total work energy or cumulative σ.dε:

double workEnergy - cumulative work energy (alt energy units)

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 (alt energy units)

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 (alt energy units)

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 heat energy

Setting Y stores cumulative heat energy:

double heatEnergy - cumulative heat energy (alt energy units)

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

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)

These can be combined with small-strain material angle and strains to find rotational strains and deformation gradient. These strains are now automatically archived whenever you archive strains..

Byte 19: Normal vector for damage mechanics

Setting Y stores normal vector to damage plane for some softening materials:

double normx - x component
double normy - y component
double normz - z component (3D Only)

Byte 20: Angular momentum

Setting Y stores particle angular momentum with Legacy units J-sec:

double Lpx - x component (3D only)
double Lpy - y component (3D only)
double Lpz - z component

This value is only non-zero in OSParticulas.

Byte 21: Angular velocity

Setting Y stores particle angular momentum with Legacy units J-sec:

double omegax - x component (3D only)
double omegay - y component (3D only)
double omegaz - z component

This value is only non-zero in OSParticulas.

Byte 22: Particle history variables 5-9

A setting of 'N' stores none; a setting of 'Y' stores history variable 5; see characters under byte 22 to store various combinations of history variables 5 to 9. The meaning and units are determined by the material and all are doubles:

double history5 - particle history information (if requested)
double history6 - particle history information (if requested)
double history7 - particle history information (if requested)
double history8 - particle history information (if requested)
double history9 - particle history information (if requested)

Only those requested will appear. See next two bytes to archive history data beyond #9.

Byte 23: Particle history variables 10-14

A setting of 'N' stores none; a setting of 'Y' stores history variable 10; see characters under byte 22 to store various combinations of history variables 10 to 14 (with 10 to 14 replacing 5 to 9). The meaning and units are determined by the material and all are doubles:

double history10 - particle history information (if requested)
double history11 - particle history information (if requested)
double history12 - particle history information (if requested)
double history13 - particle history information (if requested)
double history14 - particle history information (if requested)

Only those requested will appear. See next byte to archive history data beyond #14.

Byte 24: Particle history variables 15-19

A setting of 'N' stores none; a setting of 'Y' stores history variable 15; see characters under byte 22 to store various combinations of history variables 15 to 19 (with 15 to 19 replacing 5 to 9). The meaning and units are determined by the material and all are doubles:

double history15 - particle history information (if requested)
double history16 - particle history information (if requested)
double history17 - particle history information (if requested)
double history18 - particle history information (if requested)
double history19 - particle history information (if requested)

Only those requested will appear.

Rotational Strains and Deformation Gradient

All calculations track the full deformations gradient, but for historic reasons it is not saved by components, but by other terms. This section explains how to reconstruct it from the following archived data:

Particle strains - these strain are archived as absolute strains, but shear strains are engineering shear strains (i.e., twice the tensorial shear strains).
anglex, angley, and anglez - these angles are always saved in the default properties. 2D simulations have only anglez. They are archived in degrees.
anglex0, angley0, and anglez0 - these angles stored as "Rotational Strains" and they are define a rotation matrix, R₀ = R_z(anglez0)R_y(angley0)R_x(anglex0), to rotate initial material axes into the global x-y-z axis system. These are only non-zero when you set material point angles and are only needed for anisotropic materials. 2D simulations have only anglez0. They are archived in degrees.

To get the deformation gradient, first calculate engineering rotation strains using ω_xy = π*(anglez0-anglez)/90, ω_xz = -π*(angley0-angley)/90, and ω_yz = π*(anglex0-anglex)/90. The deformation gradient is then:

     |    1 + εxx     0.5*(γxy-ωxy)  0.5*(γxz-ωxz) |
 F = | 0.5*(γxy+ωxy)    1 + εyy      0.5*(γyz-ωyz) |
     | 0.5*(γxz+ωxz)  0.5*(γyz+ωyz)    1 + εzz     |

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 for 3D are currently only in OSParticulas. 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 ([[ConsistentUnits Command#Legacy and Consistent Units|length units]])
double y - current y position ([[ConsistentUnits Command#Legacy and Consistent Units|length units]])
double z - current z position ([[ConsistentUnits Command#Legacy and Consistent Units|length units]]) (3D only)
double origx - original x position ([[ConsistentUnits Command#Legacy and Consistent Units|length units]])
double origy - original y position ([[ConsistentUnits Command#Legacy and Consistent Units|length units]])
double origz - original z position ([[ConsistentUnits Command#Legacy and Consistent Units|length units]]) (3D only)
int inElemAbove - element number containing the crack top surface point
double xAbove - current x position of crack top surface ([[ConsistentUnits Command#Legacy and Consistent Units|length units]])
double yAbove - current y position of crack top surface ([[ConsistentUnits Command#Legacy and Consistent Units|length units]])
double zAbove - current z position of crack top surface ([[ConsistentUnits Command#Legacy and Consistent Units|length units]]) (3D only)
int inElemBelow - element number containing the crack bottom surface point
double xBelow - current x position of crack bottom surface ([[ConsistentUnits Command#Legacy and Consistent Units|length units]])
double yBelow - current y position of crack bottom surface ([[ConsistentUnits Command#Legacy and Consistent Units|length units]])
double zBelow - current y position of crack bottom surface ([[ConsistentUnits Command#Legacy and Consistent Units|length units]]) (3D only)

Byte 3: J Integral

Setting Y stores two components of J Integral:

double J1 - J Integral or energy release rate ([[ConsistentUnits Command#Legacy and Consistent Units|energy release units]])
double J2 - Second component of J Integral calculation ([[ConsistentUnits Command#Legacy and Consistent Units|energy release units]]) (when no crack propagation)
              or the actual J released ([[ConsistentUnits Command#Legacy and Consistent Units|energy release units]]) 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 ([[ConsistentUnits Command#Legacy and Consistent Units|stress intensity units]])
double KII - Mode II stress intensity factor ([[ConsistentUnits Command#Legacy and Consistent Units|stress intensity units]])

Byte 5: Mode I and Mode II energy released by cohesive zone

Setting Y stores cumulative energy released by a cohesive zone:

int counter - set to 1 and no longer used
double modeI - mode I energy released ([[ConsistentUnits Command#Legacy and Consistent Units|energy release units]])
double modeII - mode II energy released ([[ConsistentUnits Command#Legacy and Consistent Units|energy release units]])

Byte 6: Traction history variables 1 to 5

A setting of 'N' stores none; a setting of 'Y' stores traction history variable 1; see characters under byte 22 to store various combinations of history variables 1 to 5 (with 1 to 5 replaceing 5 to 9). The meaning and units are determined by the traction law and all are doubles:

double traction1 - traction history information (if requested)
double traction2 - traction history information (if requested)
double traction3 - traction history information (if requested)
double traction4 - traction history information (if requested)
double traction5 - traction history information (if requested)

Only those requested will appear. See next byte to archive traction history data beyond #5.

Byte 7: Traction history variables 6 to 10

A setting of 'N' stores none; a setting of 'Y' stores traction history variable 6; see characters under byte 22 to store various combinations of history variables 6 to 10 (with 6 to 10 replacing 5 to 9). The meaning and units are determined by the traction law and all are doubles:

double traction6 - traction history information (if requested)
double traction7 - traction history information (if requested)
double traction8 - traction history information (if requested)
double traction9 - traction history information (if requested)
double traction10 - traction history information (if requested)