MPM Archiving Options

These commands determine the way results of the calculations are archived for later analysis.

Archiving Particle Data

In MPM calculations, the calculation results are stored in a series of archive files. These files give periodic snapshots for the state of each material point. These files are read after the analysis to plot the results; in fact the results cannot be visualized without them. For more details, you can refer to the output file format definition.

Scripted Input Files

In scripted input files, the archiving options have two forms:

Archive (path)
ArchiveTime (time),<(first time)>,<(props)>
<ArchiveTime (time2),(second time),<(props2)>>
<ArchiveTime (time3),(third time),<(props3)>>
ToArchive (list of quantities)

or

ArchiveUnique (path)
ArchiveTime (time),<(first time)>,<(props)>
<ArchiveTime (time2),<(second time)>,<(props2)>>
<ArchiveTime (time3),(third time),<(props3)>>
ToArchive (list on quantities)

where

(path) gives a relative path name from the saved output file to the archived files. The path name should be entered in Unix style or
```
folder/folder/folder/root
```
where there can be any number of folders followed by the root archive file name. The saved files will be in that location and have names
```
root.num
```
where num is the step number being archived. The folder names and root name cannot contain any colons (":"), to avoid conflict with MacOS path names) or spaces (to be consistent with most Unix systems).
If a series MPM calculations are saved to the same folder without changing the archive path name, the later calculations will most likely overwrite the earlier calculations causing you to lose results. The solution is to use the second form above that replaces the Archive command with an ArchiveUnique command. The ArchiveUnique command forces creation of a new folder within the last folder of the path. In the above path example, the ArchiveUnique option will write to the files:
```
folder/folder/folder/#/root.num
```
where # is chosen from 1, 2, 3, ... to create a unique folder. You can then safely write multiple MPM output files to the save folder without conflicts
(time) gives the time interval between archiving results in alt time units (it can be an entity). The analysis will always archive the initial state (to define the problem). You only need to archive enough results to get good plots or movies after the analysis is done.
(first time) is an optional time to start archiving in alt time units (it can be an entity). If this time is greater than zero, the analysis will archive the initial state (to define the problem) and not archive anymore more results until this time is reached. After this time, archiving will proceed at the time interval specified in (time).
(props) forces archiving if (props) propagations and/or debonds have occurred since the last archive (default is 0, which disables counting of propagations).
(list on quantities) is a comma-separted list of quantities to be archived (see ToArchive command for the details.

A single ArchiveTime command is usually enough, but sometimes you want to archive infrequently at the beginning and then more frequently later or to archive by some other custom scheme. To create custom archiving schemes, you create archiving blocks with multiple ArchiveTime commands. Each subsequent ArchiveTime command adds a new block that archives with new (time) and (props) settings in the first and optional third arguments. The new block starts at the time given in the second parameter, which is now a required parameter and it must be a later time than the start of the previous archiving block.

ToArchive Command

The ToArchive command determines which calculation results to include in archived results by providing a comma-separated list of the following options (which can be in one or more ToArchive commands and are case sensitive):

velocity - particle velocities
stress - particle stress
strain - symmetric part of the displacement gradient (F-I), which in combination with rotstrain gives full deformation gradient
plasticstrain - an alternate particle strain; it is plastic strain for some materials, or something else for others
rotstrain - initial material axis rotation angles. Archiving this strain is needed to find rotation strains, deformation gradients, and to plot transformed material points. It is now automatically activated whenever strain is archived and therefore normall does not need to be set.
strainenergy - particle strain energy, which is cumulative V*σ.d(ε-ε_res)
workenergy - particle work energy, which is cumulative V*σ.dε
heatenergy - particle heat energy; the value will only be physically correct if all materials specify their heat capacity
plasticenergy - cumulative dissipated energy (despite the name, it is energy dissipated by any modeled mechanism)
lp - the angular momentum due to particle velocity gradient.
wp - the angular velocity due to particle velocity gradient.
temperature - particle temperature
concentration or porepressure - particle concentration and concentration gradient (when doing diffusion calculations) or particle pore pressure and pore pressure gradient (when doing poroelasticity calculations).
history# - where '#' is 1 to 19 to archive that history variable for a material. These history variables are only relevant for certain types of materials. To archive history data beyond #19 or to archive to a different format, you can use the HistoryArchive Custom Task.
elementcrossings - number of times the particle has crossed an element boundary since the last archive time.
damagenormal - the normal vector of the failure plane in the particle when using softening materials.
size - to archive particle sizes. The main use is to allow ExtractMPM to export an VTK file with an unstructured grid (-U option). This output can improve visualization in software like ParaView or VisIt.

The follow options archive options are for crack particles:

jintegral - crack tip J1 and J2 integrals
stressintensity - crack tip KI and KII
czmdisp - mode I and mode II energy dissipated per unit area by cohesive zones. Needed to be able to plot cohesive zone damage length or to find fracture mechanics energy release rate.
traction# - where '#' is 1 to 10 to archive that traction history variable for a traction law. These history variables are only relevant for certain types of cohesive laws.

Certain particle results are always archived and thus there is no need to specify them in a ToArchive command. The standard archived data are:

mass - particle mass
material ID - material ID number for particle
material angle - small-strain material angle (this is combined with strains and rotstrain to find rotational strains and deformation gradients.
thickness - thickness for 2D calculations
position - current particle position
original position - initial position for displacement calculations
crack position - crack particle positions
crack original position - initial crack particle positions
crack surface positions - location of crack surfaces

Finally, note that if no ToArchive command is used, the simulation will archive velocity, stress, strain, and all above "standard" properties. If ToArchive commands are used, the velocity, stress, and strain will no longer be archived unless you include them in the ToArchive commands along with any other properties you would like to visualize.

XML Input Files

In XML input files, the archiving commands, which must be within the <MPMHeader> element, are:

<ArchiveRoot unique='0'>(path)</ArchiveRoot>
<ArchiveGroup time= '(time)' start='(first time)' maxProps='(props)'/>
<MPMArchive result="(resultName)" setting='(YorN)'/>
<MPMArchive result="(resultName)" setting='(YorN)'/>
...
<MPMArchive result="(resultName)" setting='(YorN)'/>

where

(path) is the archive path. The optional unique attribute (if = 1) will force the creation of a new folder. Both these settings are as explained above.
(time) is the time interval between archiving. A units attribute determines the time units or default is time units.
(first time) is the first time results are archived. A units attribute determines the time units or default is time units.
(props) forces archiving if (props) propagations and/or debonds have occurred since the last archive (default is 0, which disables counting of propagations).
(resultName) is an archive quantity (from case insensitive names given above). The setting can be 'Y' or 'N' to archive or not archive (and the default is 'Y').

Alternative Archiving Option in XML Files

The MPMArchive commands for XML files became available in Dec. 2016. Prior to that command, MPM archiving options were set instead with the two commands:

<MPMArchiveOrder>iYYYYNYYYNYYNNNNNYNNNNNN</MPMArchiveOrder>
<CrackArchiveOrder>iYYYNNN</CrackArchiveOrder>

When using these commands instead of MPMArchive commands (and they are still allowed), calculation results included in the archive files are determined by a series of 'Y' and 'N' (or other) flags in the strings in the MPMArchiveOrder and CrackArchiveOrder commands. The byte options are described in following two sections

<MPMArchiveOrder>

Byte 1: byte order of archived files ('m' for old Macintosh order or 'i' for Intel chip order). This parameter is ignored on input but must be supplied for alignment.
Byte 2: default particle properties (particle mass, position, material information, and thickness). This byte must always by 'Y'.
Byte 3: particle velocity
Byte 4: particle stress
Byte 5: symmetric part of the displacement gradient (F-I), which in combination with rotational strain (Byte 18) gives full deformation gradient
Byte 6: an alternate particle strain; it is plastic strain for some materials, of something else for others
Byte 7: should always be 'N'. Present to support reading old versions of archive files.
Byte 8: particle work energy, which is cumulative σ.dε
Byte 9: particle temperature
Byte 10: particle plastic energy
Byte 11: should always be 'N'. Present to support reading old versions of archive files.
Byte 12: particle total shear strain components (du/dy and dv/dx), but no longer supported in visualization tools; it should be 'N'
Byte 13: particle strain energy, which is cumulative σ.d(ε-ε_res)

Byte 14: setting 'Y' or 'N' refers to particle history variable 1, but up to four history variables can be archived by using the following characters (note: the quantities archived are determined by the 4 least significant bits in the ASCII code shown for that character):

'1' (0x31) or 'Y' - history 1
'2' (0x32) - history 2
'3' (0x33) - history 1 and 2
'4' (0x34) - history 3
'5' (0x35) - history 1 and 3
'6' (0x36) - history 2 and 3
'7' (0x37) - history 1, 2, and 3
'8' (0x38) - history 4
'9' (0x39) - history 1 and 4
':' (0x3A) - history 2 and 4
';' (0x3B) - history 1, 2, and 4
'<' (0x3C) - history 3 and 4 (use '|' (0x7C) to avoid '<' in an XML file)
'=' (0x3D) - history 1, 3, and 4
'>' (0x3E) - history 2, 3, and 4 (use '~' (0x7E) to avoid '>' in an XML file)
'?' (0x3F) - history 1, 2, 3, and 4

History variables are only meaningful for some material types. See byte 22 to 24 below to archive history data beyond #4. To archive more history data or to archive to a different format, you can use the HistoryArchive Custom Task.

Byte 15: particle concentration and concentration gradients (when doing diffusion calculations) or particle pore pressure and pore pressure gradients (when doing poroelasticity calculations).
Byte 16: particle heat energy; the value will only be physically correct if all materials specify their heat capacity
Byte 17: number of times this particle crossed an element boundary since the last archive time.
Byte 18: particle rotational strain or antisymmetric part of the deformation gradient. Archiving this strain is needed to plot transformed material points and it is now automatically activated whenever strain or Byte 5 is Y (which means full deformation gradient is archived).
Byte 19: the normal vector of the failure plane in the particle when using softening materials.
Byte 20: the angular momentum due to particle spin (zero unless particle spin is activated).
Byte 21: the angular velocity due to particle spin (zero unless particle spin is activated; also zero on time step 0 due to calculations methods).

Byte 22: setting 'Y' or 'N' refers to particle history variable 5, but up to five more history variables can be archived by using the following characters (note: the quantities archived are determined by the 5 least significant bits in the ASCII code provided for that character):

'!' (0x21) or 'Y' - history 5
'"' (0x22) - history 6
'#' (0x23) - history 5 and 6
'$' (0x24) - history 7
'%' (0x25) - history 5 and 7
'&' (0x26) - history 6 and 7 (use 'f' (0x66) to avoid '&' in an XML file)
''' (0x27) - history 5, 6, and 7
'(' (0x28) - history 8
')' (0x29) - history 5 and 8
'*' (0x2A) - history 6 and 8
'+' (0x2B) - history 5, 6, and 8
',' (0x2C) - history 7 and 8
'-' (0x2D) - history 5, 7, and 8
'/' (0x2E) - history 6, 7, and 8
'/' (0x2F) - history 5, 6, 7, and 8
'0' (0x30) - history 9
'1' (0x31) - history 5 and 9
'2' (0x32) - history 6 and 9
'3' (0x33) - history 5, 6, and 9
'4' (0x34) - history 7 and 9
'5' (0x35) - history 5, 7, and 9
'6' (0x36) - history 6, 7, and 9
'7' (0x37) - history 5, 6, 7, and 9
'8' (0x38) - history 8 and 9
'9' (0x39) - history 5, 8, and 9
':' (0x3A) - history 6, 8, and 9
';' (0x3B) - history 5, 6, 8, and 4
'<' (0x3C) - history 7, 8, and 9 (use '|' (0x7C) to avoid '<' in an XML file)
'=' (0x3D) - history 5, 7, 8, and 9
'>' (0x3E) - history 6, 7, 8, and 9 (use '~' (0x7E) to avoid '>' in an XML file)
'?' (0x3F) - history 5, 6, 7, 8, and 9

History variables are only meaningful for some material types. See next two bytes to archive history data beyond #9.

Byte 23: setting 'Y' or 'N' refers to particle history variable 10, but history variables 10 to 14 can be archived using the characters listed for byte 22 (and replacing 5 to 9 with 10 to 14). See next byte to archive history data beyond #14.
Byte 24: setting 'Y' or 'N' refers to particle history variable 15, but history variables 15 to 19 can be archived using the characters listed for byte 22 (and replacing 5 to 9 with 15 to 19). To archive history data beyond #19 or to archive to a different format, you can use the HistoryArchive Custom Task.
Byte 25: particle size

Default value: iYNN... - i.e. one Y and the rest N

<CrackArchiveOrder>

Byte 1: Byte order of archived files ('m' for Macintosh order or 'i' for Intel chip order). This parameter is ignored on input but must be supplied for alignment.
Byte 2: Default crack particle properties (location, surface positions). This byte must always by 'Y'.
Byte 3: J Integral at designated crack tips.
Byte 4: Stress intensity factors at designated crack tips.
Byte 5: Mode I and Mode II energy dissipated by a cohesive zone.
Byte 6: Setting 'Y' or 'N' refers to traction history variable 1, but traction history variables 1 to 5 can be archived using the characters listed for byte 22 in the previous section (and replacing 5 to 9 with traction 1 to 5). See next byte to archive traction history data beyond #5.
Byte 7: Setting 'Y' or 'N' refers to traction history variable 6, but traction history variables 6 to 10 can be archived using the characters listed for byte 22 in the previous section (and replacing 5 to 9 with traction 6 to 10).

Default value: iYNN... - i.e. one Y and the rest N.

Archiving Mesh Data in VTK Files

As an alternative to particle data, you can archive grid results using the VTKArchive Custom Task, which write "VTK Legacy" files that can be viewed in other applications. This option is most useful for new visualization options for 3D simulations.

Notes

There are no options for archiving kinetic energy because it is easily calculated in visualization software from mass and velocity. Thus, to do kinetic energy calculations, you must archive particle velocity.
Total energy is sum of strain energy and kinetic energy. To visualize total energy results, you must archive strain energy and velocity (for kinetic energy)